brettmc / opentelemetry-php

The OpenTelemetry PHP Library

OpenTelemetry for PHP

See opentelemetry.io for more information and documentation.

Table of Contents

• Introduction
  • Releases
• Getting started
• Project status
  • Specification conformance
  • Backwards compatibility
• Getting started
  • Instrumenting an application
  • Instrumenting a library
  • Trace signals
    • Auto-instrumentation
    • Framework instrumentation
    • Manual instrumentation
    • Distributed tracing
    • Examples
  • Metrics signals
    • Examples
  • Log signals
• Versioning
• Contributing

Introduction

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

Releases

Releases for both this repository and contrib are based on read-only git subtree splits from our monorepo. You should refer to packagist.org for all packages, their versions and details.

You can also look at the read-only repositories, which live in the opentelemetry-php organization.

Getting Started

See Getting Started

All OpenTelemetry libraries are distributed via packagist, notably:

• API: open-telemetry/api
• SDK: open-telemetry/sdk
• Context: open-telemetry/context
• Semantic Conventions: open-telemetry/sem-conv
• Exporters: open-telemetry/exporter-*
• Extensions: open-telemetry/extension-*
• Auto-instrumentation modules: open-telemetry/opentelemetry-auto-*

The open-telemetry/opentelemetry-php-instrumentation extension can be installed to enable auto-instrumentation of PHP code (in conjunction with contrib modules).

The OpenTelemetry PHP Contrib repository hosts contributions that are not part of the core distribution or components of the library.

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, please let us know in our slack channel and we'll get it rectified.

Backwards compatibility

See compatibility readme.

Requirements

See https://opentelemetry.io/docs/php/getting-started#requirements

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 an exporter from the Contrib packages as well:

$ composer require open-telemetry/sdk

or

$ composer require open-telemetry/sdk open-telemetry/exporter-zipkin

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

SDK autoloading

See https://opentelemetry.io/docs/instrumentation/php/sdk#autoloading

See autoload_sdk.php example

Configuration

See https://opentelemetry.io/docs/instrumentation/php/sdk#configuration

Trace signals

Auto-instrumentation

See https://opentelemetry.io/docs/instrumentation/php/automatic/

Framework instrumentation

• Symfony SDK Bundle

Distributed tracing

See https://opentelemetry.io/docs/instrumentation/php/propagation/

See examples/traces/demo for a working example.

Trace examples

You can use the zipkin 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

Meters must be obtained from a MeterProvider

Metrics examples

See basic example

Log signals

See https://opentelemetry.io/docs/instrumentation/php/logging/

Logging examples

See getting started example

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.