OpenTelemetry PHP distro for Uptrace
This document explains how to configure OpenTelemetry PHP SDK to export spans and metrics to Uptrace using OTLP/HTTP.
To learn about OpenTelemetry API, see OpenTelemetry PHP Tracing API and OpenTelemetry PHP Metrics API.
OpenTelemetry PHP
First, install Composer using the installation instructions and add the following line to your project's composer.json
file, as this library has not reached a stable release status yet:
"minimum-stability": "dev"
Then, you can install uptrace-php:
composer require uptrace/uptrace
Configuration
You can configure Uptrace client using a DSN (Data Source Name, e.g. https://<token>@uptrace.dev/<project_id>
) from the project settings page.
$conf = new Uptrace\Config();
// copy your project DSN here or use UPTRACE_DSN env var
//$conf->setDsn('https://<token>@uptrace.dev/<project_id>');
$conf->setServiceName('myservice');
$conf->setServiceVersion('1.0.0');
$conf->setDeploymentEnvironment('production');
$uptrace = new Uptrace\Distro($conf);
$tracerProvider = $uptrace->createTracerProvider();
You can also use environment variables to configure the client:
Env var | Description |
---|---|
UPTRACE_DSN | A data source that is used to connect to uptrace.dev. For example, https://<token>@uptrace.dev/<project_id> . |
OTEL_RESOURCE_ATTRIBUTES | Key-value pairs to be used as resource attributes. For example, service.name=myservice,service.version=1.0.0 . |
OTEL_PROPAGATORS | Propagators to be used as a comma separated list. The default is tracecontext,baggage . |
Getting started
Step 0. Create an Uptrace project to obtain a DSN (connection string), for example,
https://<token>@uptrace.dev/<project_id>
.Step 2. Copy the code to
main.php
replacing the<dsn>
:
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use OpenTelemetry\API\Trace\SpanKind;
$conf = new Uptrace\Config();
// copy your project DSN here or use UPTRACE_DSN env var
//$conf->setDsn('https://<token>@uptrace.dev/<project_id>');
$conf->setServiceName('myservice');
$conf->setServiceVersion('1.0.0');
$uptrace = new Uptrace\Distro($conf);
$tracerProvider = $uptrace->createTracerProvider();
// Create a tracer. Usually, tracer is a global variable.
$tracer = $tracerProvider->getTracer('app_or_package_name');
// Create a root span (a trace) to measure some operation.
$main = $tracer->spanBuilder('main-operation')->startSpan();
// Future spans will be parented to the currently active span.
$mainScope = $main->activate();
$child1 = $tracer->spanBuilder('child1-of-main')
->setSpanKind(SpanKind::KIND_SERVER)
->startSpan();
$child1Scope = $child1->activate();
$child1->setAttribute('key1', 'value1');
try {
throw new \Exception('Some error message');
} catch (\Exception $exc) {
$child1->setStatus('error', $exc->getMessage());
$child1->recordException($exc);
}
$child1Scope->detach();
$child1->end();
$child2 = $tracer->spanBuilder('child2-of-main')->startSpan();
$child2Scope = $child1->activate();
$child2->setAttributes(['key2' => 42, 'key3' => 123.456]);
$child2Scope->detach();
$child2->end();
// End the span and detached context when the operation we are measuring is done.
$mainScope->detach();
$main->end();
echo $uptrace->traceUrl($main) . PHP_EOL;
// Send buffered spans and free resources.
$tracerProvider->shutdown();
- Step 3. Run the example to get a link for the generated trace:
php main.php
trace URL: https://uptrace.dev/traces/<trace_id>
- Step 4. Follow the link to view the generated trace:
What's next?
- Look for instrumentations and browse examples.
- Learn about Tracing API and Metrics API to create your own instrumentations.