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.

Installation

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

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 varDescription
UPTRACE_DSNA data source that is used to connect to uptrace.dev. For example, https://<token>@uptrace.dev/<project_id>.
OTEL_RESOURCE_ATTRIBUTESKey-value pairs to be used as resource attributes. For example, service.name=myservice,service.version=1.0.0.
OTEL_PROPAGATORSPropagators to be used as a comma separated list. The default is tracecontext,baggage.

Getting started

<?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();
php main.php
trace URL: https://uptrace.dev/traces/<trace_id>
  • Step 4. Follow the link to view the generated trace:

Basic trace

What's next?

Last Updated: