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 APIopen in new window and OpenTelemetry PHP Metrics APIopen in new window.

Uptrace PHP

First, install Composer using the installation instructionsopen in new window 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


You can configure Uptrace client using a DSN (Data Source Name) from the project settings page.

$uptrace = Uptrace\Distro::builder()
    // copy your project DSN here or use UPTRACE_DSN env var

// Create a tracer. Usually, tracer is a global variable.
$tracer = Globals::tracerProvider()->getTracer('app_or_package_name');

You can also use environment variables to configure the client:

Env varDescription
UPTRACE_DSNA data source that is used to connect to For example, https://<token><project_id>.
OTEL_RESOURCE_ATTRIBUTESKey-value pairs to be used as resource attributes. For example,,service.version=1.0.0.
OTEL_SERVICE_NAME=myserviceSets the value of the resource attribute. Takes precedence over OTEL_RESOURCE_ATTRIBUTES.
OTEL_PROPAGATORSPropagators to be used as a comma separated list. The default is tracecontext,baggage.

See OpenTelemetry documentationopen in new window for details.


Spend 5 minutes to install OpenTelemetry distro, generate your first trace, and click the link in your terminal to view the trace.


require __DIR__ . '/../../vendor/autoload.php';

use OpenTelemetry\API\Common\Instrumentation\Globals;
use OpenTelemetry\API\Trace\SpanKind;

$uptrace = Uptrace\Distro::builder()
    // copy your project DSN here or use UPTRACE_DSN env var

// Create a tracer. Usually, tracer is a global variable.
$tracer = Globals::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('GET /posts/:id')
$child1Scope = $child1->activate();
$child1->setAttribute('http.method"', 'GET');
$child1->setAttribute('http.route"', '/posts/:id');
$child1->setAttribute('http.url', 'http://localhost:8080/posts/123');
$child1->setAttribute('http.status_code', 200);
try {
    throw new \Exception('Some error message');
} catch (\Exception $exc) {
    $child1->setStatus('error', $exc->getMessage());

$child2 = $tracer->spanBuilder('child2-of-main')->startSpan();
$child2Scope = $child1->activate();
    'db.system' => 'mysql',
    'db.statement' => 'SELECT * FROM posts LIMIT 100',

// End the span and detached context when the operation we are measuring is done.

echo $uptrace->traceUrl($main) . PHP_EOL;
php main.php
trace URL:<trace_id>
  • Step 4. Follow the link to view the generated trace:

Basic trace

Already using OTLP exporter?

If you are already using OTLP exporter, you can configure it to export data to Uptrace without changing any code.

To maximize performance and efficiency, consider the following recommendations when configuring the OTLP exporter.

Use BatchSpanProcessor to export multiple spans in a single request.AllEssential
Enable gzip compression to compress the data before sending and reduce the traffic cost.AllEssential
Prefer delta metrics temporality, because such metrics are smaller and Uptrace must convert cumulative metrics to delta anyway.MetricsRecommended
Use AWS X-Ray ID generator for OpenTelemetry.Traces, LogsOptional

To configure OpenTelemetry to send data to Uptrace, use the provided endpoint and pass the DSN via uptrace-dsn header:

# Only for OTLP/gRPC

# Only for OTLP/HTTP

# Pass Uptrace DSN in gRPC/HTTP headers.
export OTEL_EXPORTER_OTLP_HEADERS="uptrace-dsn=https://<token><project_id>"

# Enable gzip compression.

# Enable exponential histograms.

# Prefer delta temporality.

When configuring BatchSpanProcessor, use the following settings:

# Maximum allowed time to export data in milliseconds.

# Maximum batch size.
# Using larger batch sizes can be problematic,
# because Uptrace rejects requests larger than 20MB.

# Maximum queue size.
# Increase queue size if you have lots of RAM, for example,
# `10000 * number_of_gigabytes`.

# Max concurrent exports.
# Setting this to the number of available CPUs might be a good idea.

What's next?

Next, instrument more operations to get a more detailed picture. Try to prioritize network calls, disk operations, database queries, error and logs.

You can also create your own instrumentations using OpenTelemetry PHP Tracing APIopen in new window.

Last Updated: