Manual Instrumentation

Libraries that want to export telemetry data using OpenTelemetry MUST only depend on the opentelemetry-api package and should never configure or depend on the OpenTelemetry SDK.

The SDK configuration must be provided by Applications which should also depend on the opentelemetry-sdk package, or any other implementation of the OpenTelemetry API. This way, libraries will obtain a real implementation only if the user application is configured for it.

Installation

The following shows how to install, initialize, and run an application instrumented with OpenTelemetry.

To use the OpenTelemetry SDK for PHP you need packages that satisfy the dependencies for php-http/async-client-implementation and psr/http-factory-implementation, for example the Guzzle 7 HTTP Adapter satisfies both:

composer require "php-http/guzzle7-adapter"

Now you can install the OpenTelemetry SDK:

composer require open-telemetry/sdk

Tracing

Setup

The first step is to get a handle to an instance of the OpenTelemetry interface.

If you are an application developer, you need to configure an instance of the OpenTelemetry SDK as early as possible in your application. This can be done using the Sdk::builder() method. The returned SdkBuilder instance gets the providers related to the signals, tracing and metrics, in order to build the OpenTelemetry instance.

You can build the providers by using the TracerProvider::builder() and MeterProvider::builder() methods. It is also strongly recommended to define a Resource instance as a representation of the entity producing the telemetry; in particular the service.name attribute is the most important piece of telemetry source-identifying info.

Example

<?php
$resource = ResourceInfoFactory::defaultResource();
$transport = (new GrpcTransportFactory())->create('http://collector:4317' . OtlpUtil::method(Signals::TRACE));
$exporter = new SpanExporter($transport);

$reader = new ExportingReader(
    new MetricExporter(
        PsrTransportFactory::discover()->create('http://collector:4318/v1/metrics', 'application/x-protobuf')
    ),
    ClockFactory::getDefault()
);

$meterProvider = MeterProvider::builder()
    ->setResource($resource)
    ->addReader($reader)
    ->build();

$tracerProvider = TracerProvider::builder()
    ->addSpanProcessor(
        (new BatchSpanProcessorBuilder($spanExporter))
            ->setMeterProvider($meterProvider)
            ->build()
    )
    ->setResource($resource)
    ->setSampler(new ParentBased(new AlwaysOnSampler()))
    ->build();

Sdk::builder()
    ->setTracerProvider($tracerProvider)
    ->setMeterProvider($meterProvider)
    ->setPropagator(TraceContextPropagator::getInstance())
    ->setAutoShutdown(true)
    ->buildAndRegisterGlobal();

$instrumentation = new CachedInstrumentation('example');
$tracer = $instrumentation->tracer();

It's important to run the tracer provider's shutdown() method when the PHP process ends, to enable flushing of any enqueued telemetry. The shutdown process is blocking, so consider running it in an async process. Otherwise, you can use the ShutdownHandler to register the shutdown function as part of PHP's shutdown process:

\OpenTelemetry\SDK\Common\Util\ShutdownHandler::register([$tracerProvider, 'shutdown']);
\OpenTelemetry\SDK\Common\Util\ShutdownHandler::register([$meterProvider, 'shutdown']);

Acquiring a Tracer

To do Tracing you'll need to acquire a Tracer.

Note: Methods of the OpenTelemetry SDK should never be called.

First, a Tracer must be acquired, which is responsible for creating spans and interacting with the Context. A tracer is acquired by using the OpenTelemetry API specifying the name and version of the library instrumenting the instrumented library or application to be monitored. More information is available in the specification chapter Obtaining a Tracer.

$tracer = Globals::tracerProvider()->getTracer('instrumentation-library-name', '1.0.0');

Important: the "name" and optional version of the tracer are purely informational. All Tracers that are created by a single OpenTelemetry instance will interoperate, regardless of name.

Create Spans

To create Spans, you only need to specify the name of the span. The start and end time of the span is automatically set by the OpenTelemetry SDK.

$span = $tracer->spanBuilder("my span")->startSpan();

// Make the span the current span
try {
  $scope = $span->activate();
  // In this scope, the span is the current/active span
} finally {
    $span->end();
    $scope->detach();
}

It's required to call end() to end the span, and you must detach the active scope if you have activated it.

Create nested Spans

Most of the time, we want to correlate spans for nested operations. OpenTelemetry supports tracing within processes and across remote processes. For more details how to share context between remote processes, see Context Propagation.

For a method a calling a method b, the spans could be manually linked in the following way:

  $parentSpan = $tracer->spanBuilder("parent")->startSpan();
  $scope = $parentSpan->activate();
  try {
    $child = $tracer->spanBuilder("child")->startSpan();
    //do stuff
    $child->end();
  } finally {
    $parentSpan->end();
    $scope->detach();
  }

Get the current span

Sometimes it's helpful to do something with the current/active span at a particular point in program execution.

$span = OpenTelemetry\API\Trace\Span::getCurrent();

And if you want the current span for a particular Context object:

$span = OpenTelemetry\API\Trace\Span::fromContext($context);

Span Attributes

In OpenTelemetry spans can be created freely and it's up to the implementor to annotate them with attributes specific to the represented operation. Attributes provide additional context on a span about the specific operation it tracks, such as results or operation properties.

$span = $tracer->spanBuilder("/resource/path")->setSpanKind(SpanKind::CLIENT)->startSpan();
$span->setAttribute("http.method", "GET");
$span->setAttribute("http.url", (string) $url);

Create Spans with events

Spans can be annotated with named events (called Span Events) that can carry zero or more Span Attributes, each of which itself is a key:value map paired automatically with a timestamp.

$span->addEvent("Init");
...
$span->addEvent("End");

$eventAttributes = Attributes::create([
    "key" => "value",
    "result" => 3.14159;
]);
$span->addEvent("End Computation", $eventAttributes);

Create Spans with links

A Span may be linked to zero or more other Spans that are causally related via a Span Link. Links can be used to represent batched operations where a Span was initiated by multiple initiating Spans, each representing a single incoming item being processed in the batch.

$span = $tracer->spanBuilder("span-with-links")
        ->addLink($parentSpan1->getContext())
        ->addLink($parentSpan2->getContext())
        ->addLink($parentSpan3->getContext())
        ->addLink($remoteSpanContext)
    ->startSpan();

For more details how to read context from remote processes, see Context Propagation.

Set span status and record exceptions

A status can be set on a span, typically used to specify that a span has not completed successfully - SpanStatus::ERROR. In rare scenarios, you could override the Error status with Ok, but don't set Ok on successfully-completed spans.

It can be a good idea to record exceptions when they happen. It's recommended to do this in conjunction with setting span status.

The status can be set at any time before the span is finished:

$span = $tracer->spanBuilder("my-span")->startSpan();
$scope = $span->activate();
try {
  // do something
} catch (Throwable $t) {
  $span->setStatus(StatusCode::STATUS_ERROR, "Something bad happened!");
  $span->recordException($t); //This will capture things like the current stack trace in the span.
  throw $t;
} finally {
  $span->end(); // Cannot modify span after this call
  $scope->detach();
}

Sampler

It is not always feasible to trace and export every user request in an application. In order to strike a balance between observability and expenses, traces can be sampled.

The OpenTelemetry SDK offers four samplers out of the box:

• AlwaysOnSampler which samples every trace regardless of upstream sampling decisions.
• AlwaysOffSampler which doesn't sample any trace, regardless of upstream sampling decisions.
• ParentBased which uses the parent span to make sampling decisions, if present.
• TraceIdRatioBased which samples a configurable percentage of traces, and additionally samples any trace that was sampled upstream.

$tracerProvider = TracerProvider::builder()
  ->setSampler(new AlwaysOnSampler())
  //or
  ->setSampler(new AlwaysOffSampler())
  //or
  ->setSampler(new TraceIdRatioBasedSampler(0.5))
  ->build();

Additional samplers can be provided by implementing OpenTelemetry\SDK\Trace\SamplerInterface. An example of doing so would be to make sampling decisions based on attributes set at span creation time.

Span Processor

Different Span processors are offered by OpenTelemetry. The SimpleSpanProcessor immediately forwards ended spans to the exporter, while the BatchSpanProcessor batches them and sends them in bulk.

$tracerProvider = TracerProvider::builder()
  ->addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporterFactory()->create()))
  ->build();

Transports

All exporters require a Transport, which is responsible for the sending of telemetry data from an exporter:

• PsrTransport - uses a PSR18 client to send data over HTTP
• StreamTransport - uses a stream to send data
• GrpcTransport - uses gRPC to send protobuf-encoded data

Exporter

Span processors are initialized with an exporter which is responsible for sending the telemetry data to a particular backend:

• InMemory: keeps the data in memory, useful for testing and debugging.
• Console: sends the data to a stream such as stdout or stderr
• Zipkin: prepares and sends the collected telemetry data to a Zipkin backend via the Zipkin APIs.
• Logging Exporter: saves the telemetry data into log streams.
• OpenTelemetry Protocol Exporter: sends the data in OTLP format to the OpenTelemetry Collector or other OTLP receivers. The underlying Transport can send:
• protobuf over HTTP
• protobuf over gRPC
• JSON over HTTP

Logging and Error Handling

OpenTelemetry can be configured to use a PSR-3 logger to log information about OpenTelemetry, including errors and warnings about misconfigurations or failures exporting data:

$logger = new Psr3Logger(LogLevel::INFO);
LoggerHolder::set($logger);

If no PSR-3 logger is provided, error messages will instead be recorded via trigger_error (at a level no higher than E_USER_WARNING).

For more fine-grained control and special case handling, custom handlers and filters can be applied to the logger (if the logger offers this ability).

Metrics

OpenTelemetry can be used to measure and record different types of metrics from an application, which can then be pushed to a metrics service such as the OpenTelemetry collector:

• counter
• async counter
• histogram
• async gauge
• up/down counter
• async up/down counter

Meter types and usage are explained in the metrics concepts documentation.

Setup

First, create a MeterProvider:

$reader = new ExportingReader((new ConsoleMetricExporterFactory())->create());

$meterProvider = MeterProvider::builder()
    ->addReader($reader)
    ->build();

You can now use the meter provider to retrieve meters.

Synchronous meters

A synchronous meter must be manually adjusted as data changes:

$up_down = $meterProvider
    ->getMeter('my_up_down')
    ->createUpDownCounter('queued', 'jobs', 'The number of jobs enqueued');
//jobs come in
$up_down->add(2);
//job completed
$up_down->add(-1);
//more jobs come in
$up_down->add(2);

$meterProvider->forceFlush();

Synchronous metrics are exported when forceFlush() and/or shutdown() are called on the meter provider.

Asynchronous meters

Async meters are observable, eg ObservableGauge. When registering an observable/async meter, you provide one or more callback functions. The callback functions will be called by a periodic exporting metric reader, for example based on an event-loop timer. The callback(s) are responsible for returning the latest data for the meter.

In this example, the callbacks are executed when $reader->collect() is executed:

$queue = [
    'job1',
    'job2',
    'job3',
];
$meterProvider
    ->getMeter('my_gauge')
    ->createObservableGauge('queued', 'jobs', 'The number of jobs enqueued')
    ->observe(static function (ObserverInterface $observer) use ($queue): void {
        $observer->observe(count($queue));
    });
$reader->collect();

Readers

Currently we only have an ExportingReader, which is an implementation of the periodic exporting metric reader. When its collect() method is called, all associated asynchronous meters are observed, and metrics pushed to the exporter.

Logging

As logging is a mature and well-established function, the OpenTelemetry approach is a little different for this signal.

The OpenTelemetry logger is not designed to be used directly, but rather to be integrated into existing logging libraries as a handler. In this way, you can choose to have some or all of your application logs sent to an OpenTelemetry-compatible service such as the collector.

Setup

You get a logger from a LoggerProvider. Log records get emitted via an EventLogger:

<?php
$loggerProvider = new LoggerProvider(
    new SimpleLogsProcessor(
        new ConsoleExporter()
    )
);
$logger = $loggerProvider->getLogger('demo', '1.0', 'http://schema.url', [/*attributes*/]);
$eventLogger = new EventLogger($logger, 'my-domain');

Once configured, a LogRecord can be created and sent via the event logger's logEventmethod:

$record = (new LogRecord('hello world'))
    ->setSeverityText('INFO')
    ->setAttributes([/*attributes*/]);

$eventLogger->logEvent('foo', $record);

Integrations for 3^rd-party logging libraries

Monolog

You can use the monolog handler to send monolog logs to an OpenTelemetry-capable receiver:

composer require open-telemetry/opentelemetry-logger-monolog

$loggerProvider = new LoggerProvider(/*params*/);

$handler = new \OpenTelemetry\Contrib\Logs\Monolog\Handler(
    $loggerProvider,
    \Psr\Log\LogLevel::ERROR,
);
$logger = new \Monolog\Logger('example', [$handler]);

$logger->info('hello, world');
$logger->error('oh no', [
    'foo' => 'bar',
    'exception' => new \Exception('something went wrong'),
]);

$loggerProvider->shutdown();