This tutorial demonstrates how to instrument PHP applications to capture logs, metrics, and traces using OpenTelemetry and send them to Coralogix. It relies on a Slim micro framework application, but other web frameworks – such as WordPress, Symfony, or Laravel – can also be used.
The OpenTelemetry-PHP instrumentation is currently in beta release. Releases, including the latest release, can be found here.
Instrumentation can be accomplished automatically or manually. Automatic instrumentation is the most efficient way to add instrumentation to PHP applications, injecting bytecode via an agent to capture telemetry. Manual instrumentation involves adding observability code to an app yourself. While this is more labor intensive, it provides the most control over the SDK configuration.
Prerequisites
A Coralogix account, set up on the Coralogix domain corresponding to the region where your data is stored
PHP 8.0+ for auto-instrumentation, and at least PHP 7.4 for manual-instrumentation
open-telemetry/sdk provides an implementation of the OpenTelemetry API and can be set up and configured in a number of ways.
Send Data to Coralogix
Coralogix provides OTLP endpoints for various regions. Using the gRPC exporter can improve data transmission performance. Install the additional extensions through terminal.
STEP 1. Install gRPC.
pecl install grpc protobuf
Notes:
Installing gRPC make take several minutes, as the extension builds from source.
STEP 2. Add the following extension to your php.ini file (e.g. /etc/php.in).
OTEL_PHP_AUTOLOAD_ENABLED: For OpenTelemetry PHP, set to true to enable automatic instrumentation and globally register the SDK.
OTEL_TRACES_EXPORTER: As auto-instrumentation currently works on traces only, set the traces exporter to otlp to send it.
OTEL_EXPORTER_OTLP_ENDPOINT: Select the OpenTelemetry endpoint associated with your Coralogix domain.
OTEL_EXPORTER_OTLP_HEADERS: Input your Coralogix Send-Your-Data API key in the Authorization header for authentication.
OTEL_RESOURCE_ATTRIBUTES: Input the names of your application and subsystem. You will need to specify 4 RESOURCE_ATTRIBUTES for the application and subsystem:
application.name=<CXApplicationName>
api.name=<CXSubSystemName>
cx.application.name=<CXApplicationName>
cx.subsystem.name=<CXSubSystemName>
STEP 4. Run the instrumentation.
The index.php script below is a simple demo of a dice roll. It does not contain any code from the OpenTelemetry SDK.
<?php
use Psr\\Http\\Message\\ResponseInterface as Response;
use Psr\\Http\\Message\\ServerRequestInterface as Request;
use Slim\\Factory\\AppFactory;
require __DIR__ . '/vendor/autoload.php';
$app = AppFactory::create();
$app->get('/rolldice', function (Request $request, Response $response) {
$result = random_int(1,6);
$response->getBody()->write(strval($result));
return $response;
});
$app->run();
STEP 5. Open a terminal window and run the instrumentation as a web server. Once the server is running, make HTTP calls to the application route using a browser or the curl command-line tool.
In your Coralogix toolbar, navigate to Explore > Tracing. You should now see traces generated by your application.
STEP 7. To add logging capabilities, the instrumentation code needs to be configured with a logger such as monolog. To do this, add the required dependencies.
STEP 8. Replace index.php script as follows. The command manually deploys the OpenTelemetry loggerProvider and attaches it to the OpenTelemetry Monolog Handler.
<?php
use Monolog\\Logger;
use OpenTelemetry\\API\\Common\\Instrumentation\\Globals;
use OpenTelemetry\\Contrib\\Logs\\Monolog\\Handler;
use Psr\\Http\\Message\\ResponseInterface as Response;
use Psr\\Http\\Message\\ServerRequestInterface as Request;
use Psr\\Log\\LogLevel;
use Slim\\Factory\\AppFactory;
require __DIR__ . '/vendor/autoload.php';
$loggerProvider = Globals::loggerProvider();
$handler = new Handler(
$loggerProvider,
LogLevel::INFO
);
$monolog = new Logger('otel-php-monolog', [$handler]);
$app = AppFactory::create();
$app->get('/rolldice', function (Request $request, Response $response) use ($monolog) {
$result = random_int(1,6);
$response->getBody()->write(strval($result));
$monolog->info('dice rolled', ['result' => $result]);
return $response;
});
$app->run();
STEP 9. To enable traces and logs, configure the environment variables and set the respective telemetry exporters to use the otlp protocol.
STEP 11. To view your logs, navigate to Explore > Logs in your Coralogix toolbar. The generated logs will be displayed.
Manual Instrumentation
By adding observability code to an application using the OpenTelemetry PHP SDK, you gain greater control over which telemetry to provision and send. This approach also enables you to integrate OpenTelemetry with popular PHP libraries available in the community repository.
Common Configuration
Before creating the respective providers for each type of observability, configure the Instrumentation SDK as environment variables using system export commands or within the PHP code using putenv . Set all observability exporters to none initially until manual instrumentation for each type is completed.
Set all traces, metrics and logs (e.g. OTEL_<OBSERVABILITY>_EXPORTER ) to none first.
Traces
STEP 1. Set the otlp exporter for traces.
export OTEL_TRACES_EXPORTER=otlp
STEP 2. Add spans.
Replace the index.php script with the following code. This code manually creates spans with additional information that provides insights into the trace telemetry.
<?php
use OpenTelemetry\\SDK\\Trace\\TracerProviderFactory;
use Psr\\Http\\Message\\ResponseInterface as Response;
use Psr\\Http\\Message\\ServerRequestInterface as Request;
use Psr\\Log\\LogLevel;
use Slim\\Factory\\AppFactory;
require __DIR__ . '/vendor/autoload.php';
//Initialize TraceProvider and Tracer
$tracerFactory = new TracerProviderFactory();
$tracerProvider = $tracerFactory->create();
$tracer = $tracerProvider->getTracer('demo_trace');
$app = AppFactory::create();
$app->get('/rolldice', function (Request $request, Response $response) use ($tracer) {
//create spans
$span = $tracer->spanBuilder("roll_event")->startSpan();
$result = random_int(1,6);
$response->getBody()->write(strval($result));
//set attributes and events to span
$span->setAttribute("dice_roll", $result);
$span->addEvent('rolled_event', [
//key:value
'roll_value' => $result,
]);
//end span to send
$span->end();
return $response;
});
$app->run();
//shutdown providers
$tracerProvider->shutdown();
Notes:
The TracerProviderFactory class from the SDK provides a way to create the necessary TracerProvider by using system environment variables as the default.
getTracer() creates instances of $tracer with a required name (and other attributes) to propagate context information about the system.
Add information to spans using setAttribute and addEvent. Span attributes store specific operation properties, while span events can carry zero or more span attributes, which themselves are key:value maps.
It is necessary to call end() at the end of a any code logic to ensure that it is sent.
It is important to call shutdown() at the end of the instrumentation to allow the TracerProvider to do any necessary cleanup and export telemetry.
STEP 3. Generate traces.
To generate traces, run the PHP web-server in the directory. Once the server is running, make HTTP calls to the application route using a browser or the curl command-line tool.
STEP 4. To view your traces, navigate to Explore > Traces in your Coralogix toolbar. The generated traces will be displayed.
Metrics
STEP 1. Set the otlp exporter for metrics.
export OTEL_METRICS_EXPORTER=otlp
STEP 2. Add a meter and metrics instrument.
Replace the index.php script with the following code, instrumenting metrics via the OpenTelemetry SDK.
<?php
use OpenTelemetry\\SDK\\Metrics\\MeterProviderFactory;
use Psr\\Http\\Message\\ResponseInterface as Response;
use Psr\\Http\\Message\\ServerRequestInterface as Request;
use Slim\\Factory\\AppFactory;
require __DIR__ . '/vendor/autoload.php';
//Initialize Meters
$meterFactory = new MeterProviderFactory();
$meterProvider = $meterFactory->create();
$meter = $meterProvider->getMeter('demo_meter');
//Initialise Histogram
$histogram = $meter->createHistogram('roll', 'num', 'The output of roll result');
$app = AppFactory::create();
$app->get('/rolldice', function (Request $request, Response $response) use ($histogram) {
$result = random_int(1,6);
$response->getBody()->write(strval($result));
//add to the metric counter
$histogram->record($result);
return $response;
});
$app->run();
//shutdown providers
$meterProvider->shutdown();
Notes:
The MeterProviderFactory class in the SDK provides a way to create the necessary MeterProvider by using system environment variables as the default.
Calling getMeter() creates instances of $meter with a required name, and other optional attributes such as version and schema_url, to define the instrumentation scope of emitted telemetry. Meters are identified by these fields, and are considered identical if all identifying fields are equal.
To create a histogram instrument, use the createHistogram function. Other types of instruments can also be created; see meter operations for details.
Use record() to store data related to the meter instrument.
Metrics are exported when either forceFlush() or shutdown() is called on the meter provider. It is important to call shutdown() at the end of the instrumentation to allow the MeterProvider to do any necessary cleanup and export telemetry.
STEP 3. Send your metrics.
To generate metrics, run the PHP web-server in the directory. Once the server is running, make HTTP calls to the application route using a browser or the curl command-line tool.
STEP 4. To view your metrics, access the Grafana Dashboard in your Coralogix app.
Click on Explore.
Select “roll_num_sum” in the metrics browser.
Use the roll_num_sum{} or any other relevant “roll_num” metric.
Click on Run query.
Logs
STEP 1. Set the otlp exporter for logs.
export OTEL_LOGS_EXPORTER=otlp
STEP 2. Install the required packages.
Logging is a mature and well-established function. OpenTelemetry’s logging approach is not intended to be used directly but rather to be integrated into existing loggers, such as Monolog.
The Monolog package and OpenTelemetry’s logger integration with Monolog are required.
The OpenTelemetry handler, configured with an OpenTelemetry LoggerProvider, is used to send Monolog LogRecords to OpenTelemetry.
STEP 3. Add logs via Monolog.
Replace the index.php script with the following code.
<?php
use Monolog\\Logger;
use OpenTelemetry\\Contrib\\Logs\\Monolog\\Handler as MonologHandler;
use OpenTelemetry\\SDK\\Logs\\LoggerProviderFactory;
use Psr\\Http\\Message\\ResponseInterface as Response;
use Psr\\Http\\Message\\ServerRequestInterface as Request;
use Psr\\Log\\LogLevel;
use Slim\\Factory\\AppFactory;
require __DIR__ . '/vendor/autoload.php';
//Initialize Logger
$loggerFactory = new LoggerProviderFactory();
$loggerProvider = $loggerFactory->create();
$handler = new MonologHandler(
$loggerProvider,
LogLevel::DEBUG,
);
//Initialize Monolog
$monolog = new Logger('logger', [$handler]);
$monolog->info('hello world');
$app = AppFactory::create();
$app->get('/rolldice', function (Request $request, Response $response) use ($monolog) {
$result = random_int(1,6);
$response->getBody()->write(strval($result));
//log results
$monolog->debug('result rolled ' . strval($result));
return $response;
});
$app->run();
//shutdown providers
$loggerProvider->shutdown();
Notes:
The LoggerProviderFactory class in the SDK provides a way to create the necessary LoggerProvider by using system environment variables as the default.
Thus MonologHandler is configured with the OpenTelemetry LoggerProvider to send log records from Monolog to OpenTelemetry by setting as the default handler for $monolog
Send logs at different levels (e.g. debug, info, error) with the $monolog logger.
It is important to call shutdown() at the end of the instrumentation to allow the LoggerProvider to do any necessary cleanup and export telemetry.
STEP 3. Send your logs.
To generate logs, run the PHP web-server in the directory. Once the server is running, make HTTP calls to the application route using a browser or the curl command-line tool.
STEP 4. To view your logs, navigate to Explore > Logs in your Coralogix toolbar. The generated logs will be displayed.
Troubleshooting
PHP Extensions
To ensure that the opentelemetry-beta, grpc, and protobuf modules are installed and declared correctly in the php.ini file, run the command php -m to list all the loaded PHP modules.
If the grpc module takes too long to install, it is because it compiles from source. However, building on Docker and using the docker-php-extension-installer can help create a base layer or image, so that all the modules do not need to be re-installed.
Telemetry Not Sending
If your traces, metrics, or logs are not appearing in your Coralogix dashboard, check your instrumentation.
To verify that all OpenTelemetry environment variables are configured properly, use the printenv command in the terminal.
Check that all dependencies are properly included in the composer.json file. You can run composer show --installed to see the list of installed packages.
Check that telemetry is getting generated via the console by changing the respective exporters to console.
Oh no!We didn’t find anything for “”,
