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
• Configuration
• Getting started
• What's next?

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.