OpenTelemetry php library

Table of Contents

• Introduction
• Project status
  • Specification conformance
  • Backwards compatibility
• Requirements
  • Required dependencies
  • Optional dependencies
• Installation
• Getting started
  • Instrumenting an application
  • Instrumenting a library
  • Trace signals
    • Auto-instrumentation
    • Framework instrumentation
    • Manual instrumentation
      • Set up a tracer
      • Creating spans
      • Nesting spans
      • Distributed tracing
    • Examples
  • Metrics signals
    • Examples
  • Log signals
• User Quickstarts
• Versioning
• Contributing

Introduction

This is the monorepo for the main components of OpenTelemetry PHP.

All OpenTelemetry libraries are distributed via packagist, notably:

• API: open-telemetry/api
• SDK: open-telemetry/sdk
• Semantic Conventions: open-telemetry/sem-conv
• Context: open-telemetry/context
• Exporters: open-telemetry/exporter-*
• Contrib: open-telemetry/sdk-contrib
• Extensions: open-telemetry/extension-*

The open-telemetry/opentelemetry package contains all of the above and is the easiest way to try out OpenTelemetry.

---

This repository also hosts and distributes generated client code used by individual components as separate packages. These packages are:

• Generated OTLP ProtoBuf files: open-telemetry/gen-otlp-protobuf
• Generated Jaeger Thrift files: open-telemetry/gen-jaeger-thrift

For now the generated code packages are meant to be only used by library components internally.

---

The OpenTelemetry PHP Contrib repository hosts contributions that are not part of the core distribution or components of the library. Typically, these contributions are vendor specific receivers/exporters and/or components that are only useful to a relatively small number of users.

Additional packages, demos and tools are hosted or distributed in the OpenTelemetry PHP organization.

Project Status

Signal	Status	Project
Traces	Alpha	N/A
Metrics	Alpha	N/A
Logs	N/A	N/A

This project currently lives in a alpha status. Our current release is not production ready; it has been created in order to receive feedback from the community.
As long as this project is in alpha status, things may and probably will break once in a while.

Specification conformance

We attempt to keep the OpenTelemetry Specification Matrix up to date in order to show which features are available and which have not yet been implemented.

If you find an inconsistency in the data in the matrix vs. the data in this repository, please let us know in our slack channel and we'll get it rectified.

---

Backwards Compatibility

We aim to provide backward compatibility (without any guarantee) even for alpha releases, however the library will raise notices indicating breaking changes and what to do about them.
If you don't want these notices to appear or change the error message level, you can do so by calling:

OpenTelemetry\SDK\Common\Dev\Compatibility\Util::setErrorLevel(0)

to turn messages off completely, or (for example)

OpenTelemetry\SDK\Common\Dev\Compatibility\Util::setErrorLevel(E_USER_DEPRECATED)

to trigger only deprecation notices. Valid error levels are 0 (none), E_USER_DEPRECATED, E_USER_NOTICE, E_USER_WARNING and E_USER_ERROR
However (as long as in alpha) it is safer to pin a dependency on the library to a specific version and/or make the adjustments mentioned in the provided messages, since doing otherwise may break things completely for you in the future!

Requirements

The library and all separate packages requires a PHP version of 7.4.x, 8.0.x or 8.1.x

Required dependencies

1) Install PSR17/18 implementations

The SDK and Contrib packages have a dependency on both a HTTP Factories (PSR17) and a php-http/async-client implementation. You can find appropriate composer packages implementing given standards on packagist.org. Follow this link to find a PSR17 (HTTP factories) implementation, and this link to find a php-http/async-client implementation.

---

Optional dependencies

1) Install PHP ext-grpc

The PHP gRPC extension is only needed, if you want to use the OTLP GRPC Exporter from the Contrib package.

Three ways to install the gRPC extension are described below. Keep in mind, that whatever way to install the extension you choose, the compilation can take up to 10-15 minutes. (As an alternative you can search for a pre-compiled extension binary for your OS and PHP version, or you might be lucky and the package manager of your OS provides a package for the extension)

• Installation with pecl installer (which should come with your PHP installation):

[sudo] pecl install grpc

• Installation with pickle installer (which you can find here):

[sudo] pickle install grpc

• Manually compiling the extension, which is not really complicated either, but you should know what you are doing, so we won't cover it here.

Notice: The artifact of the gRPC extension can be as large as 100mb (!!!), Some 'hacks' to reduce that size, are mentioned in this thread. Use at your own risk.

2) Install PHP ext-mbstring

The library's components will load the symfony/polyfill-mbstring package, but for better performance you should install the PHP mbstring extension. You can use the same install methods as described for the gRPC extension above, however most OS` package managers provide a package for the extension.

3) Install PHP ext-zlib

In order to use compression in HTTP requests you should install the PHP zlib extension. You can use the same install methods as described for the gRPC extension above, however most OS` package managers provide a package for the extension.

4) Install PHP ext-ffi

Experimental support for using fibers in PHP 8.1 for Context storage requires the ffi extension, and can be enabled by setting the OTEL_PHP_FIBERS_ENABLED environment variable to a truthy value (1, true, on).

Using fibers with non-CLI SAPIs may require preloading of bindings. One way to achieve this is setting ffi.preload to src/Context/fiber/zend_observer_fiber.h and setting opcache.preload to vendor/autoload.php.

5) Install PHP ext-protobuf

The PHP protobuf extension is optional when using either the OTLPHttp or OTLPGrpc exporters from the Contrib package.

The protobuf extension makes both exporters significantly more performant, and we recommend that you do not use the PHP package in production. Note that protobuf 3.20.0+ is required for php 8.1 support

---

Installation

The recommended way to install the library's packages is through Composer:

Install Composer using the installation instructions and add

 "minimum-stability": "dev"

To your project's composer.json file, as this library has not reached a stable release status yet.

To install the complete library with all packages you can run:

$ composer require open-telemetry/opentelemetry

This is perfect for trying out our examples or demos.

Getting Started

You can find a getting started guide on opentelemetry.io

OpenTelemetry's goal is to provide a single set of APIs to capture signals, such as distributed traces and metrics, from your application and send them to an observability platform. This project allows you to do just that for applications written in PHP. There are two steps to this process: instrument your application, and configure an exporter.

To start capturing signals from your application it first needs to be instrumented.

Using OpenTelemetry in an Application

Your application should only depend on Interfaces provided by the API package:

$ composer require open-telemetry/api

In the best case you will use Dependency Inversion and write an adapter to not depend on the API directly.

Make sure your application works with a dependency on the API only, however to make full use of the library you want to install the SDK package and probably the Contrib package as well:

$ composer require open-telemetry/sdk

or

$ composer require open-telemetry/sdk open-telemetry/sdk-contrib

Make sure any SDK or Contrib code is set up by your configuration, bootstrap, dependency injection, etc.

Using OpenTelemetry to instrument a Library

Your library should only depend on Interfaces provided by the API package:

$ composer require open-telemetry/api

For development and testing purposes you also want to install SDK and Contrib packages:

$ composer require --dev open-telemetry/sdk open-telemetry/sdk-contrib

Trace signals

Auto-instrumentation

We do not currently support auto-instrumentation, but are internally discussing how to implement it

Framework instrumentation

• Symfony SDK Bundle is the recommended way to use opentelemetry-php with symfony

Manual instrumentation

If you wish to build your own instrumentation for your application, you will need to use the API, the SDK, and probably the contrib module (which contains most of the exporters).

Set up a tracer

Tracers must be obtained from a TracerProvider:

$tracerProvider = new \OpenTelemetry\SDK\Trace\TracerProvider(
    new \OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessor(
        new \OpenTelemetry\Contrib\OtlpGrpc\Exporter('otel-collector:4317')
    )
);
\OpenTelemetry\SDK\Common\Util\ShutdownHandler::register([$tracerProvider, 'shutdown']);
$tracer = $tracerProvider->getTracer('example');

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, as demonstrated above.

Creating spans

$span = $tracer->spanBuilder('root')->startSpan();
//do some work
$span->end();

Nesting spans

You can activate a span, so that it will be the parent of future spans.

When you activate a span, it's critical that you also detach it when done. We recommend doing this in a finally block:

$root = $tracer->spanBuilder('root')->startSpan();
$scope = $root->activate();
try {
    $child = $tracer->spanBuilder('child')->startSpan();
    $child->end();
} finally {
    $root->end();
    $scope->detach();
}

When an active span is deactivated (scope detached), the previously active span will become the active span again.

Distributed tracing

OpenTelemetry supports distributed tracing via Context Propagation, where traces can be correlated across multiple services. To enable this, outgoing HTTP requests must be injected with standardized headers which are understood by other OTEL-enabled services.

$request = new Request('GET', 'https://www.example.com');
$carrier = [];
TraceContextPropagator::getInstance()->inject($carrier);
foreach ($carrier as $name => $value) {
    $request = $request->withAddedHeader($name, $value);
}
$response = $client->send($request);

See examples/traces/demo for a working example.

Trace examples

You can use the zipkin or jaeger example to test out the reference implementations. This example performs a sample trace with a grouping of 5 spans and exports the result to a local zipkin or jaeger instance.

If you'd like a no-fuss way to test this out with docker and docker-compose, you can perform the following simple steps:

1. Install the necessary dependencies by running make install.
2. Execute the example trace using make smoke-test-exporter-examples:.

Exported spans can be seen in zipkin at http://127.0.0.1:9411

Exported spans can also be seen in jaeger at http://127.0.0.1:16686

Metrics signals

coming soon

Metrics examples

This section is deprecated, we have a new metrics implementation in development

You can use the examples/prometheus/PrometheusMetricsExample.php file to test out the reference implementation we have. This example will create a counter that will be scraped by local Prometheus instance.

The easy way to test the example out with docker and docker-compose is:

1. Run make metrics-prometheus-example. Make sure that local ports 8080, 6379 and 9090 are available.

2. Open local Prometheus instance: http://localhost:9090

3. Go to Graph section, type "opentelemetry_prometheus_counter" in the search field or select it in the dropdown menu. You will see the counter value. Every other time you run make metrics-prometheus-example will increment the counter but remember that Prometheus scrapes values once in 10 seconds.

4. In order to stop docker containers for this example just run make stop-prometheus

Log signals

frozen pending delivery of tracing and metrics

User Quickstarts

• Exploring OpenTelemetry in Laravel Applications

Versioning

Versioning rationale can be found in the Versioning Documentation

Contributing

We would love to have you on board, please see our Development README and Contributing README.