Integrating OpenTelemetry with Instana for PHP applications

You can use OpenTelemetry with PHP applications along with IBM Instana Observability.

Supported OS

OpenTelemetry integration is supported and tested on only Linux operating systems.

Prerequisites

To integrate OpenTelemetry with Instana, you need the following components:

OpenTelemetry PHP extension
Composer for dependency management
OpenTelemetry SDK and instrumentation libraries
An active IBM Instana Observability account
Instana agent installed and configured in your environment

You need these components for all the integration options.

Setting up OpenTelemetry integration

You can use any one of the following options to integrate OpenTelemetry with Instana:

Instana Distribution of OpenTelemetry Collector (IDOT): Using the Instana-managed OpenTelemetry Collector to receive and process OpenTelemetry data.
Instana OTLP endpoints: Configuring OpenTelemetry OTLP exporter to send OTel data directly to Instana agent or Instana backend OTLP endpoints.
Instana OpenTelemetry PHP Exporter: Using the dedicated Instana OpenTelemetry PHP exporter that converts OTel spans into Instana native spans and uses the Instana native transport layer.

Option 1: Using Instana Distribution of OpenTelemetry Collector

The Instana Distribution of OpenTelemetry Collector (IDOT) is a fully managed and pre-configured version of the OpenTelemetry Collector that seamlessly integrates with Instana's observability platform.

To collect telemetry data from your PHP applications, complete the following steps to set up and configure IDOT:

Install the collector: Deploy the Instana Distribution of OpenTelemetry Collector as a sidecar, daemon, or gateway depending on your infrastructure needs. For detailed instructions to configure IDOT collector, see Instana Distribution of OpenTelemetry Collector documentation.

Configure your PHP application: Set up your PHP application to send OpenTelemetry data to the Instana collector:

OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_SERVICE_NAME=your_service_name
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:24317
OTEL_PROPAGATORS=instana,tracecontext

Option 2: Using Instana OTLP endpoints

You can integrate OpenTelemetry with PHP by configuring the default OpenTelemetry Protocol (OTLP) Exporter to send the OpenTelemetry traces directly to the Instana agent or the Instana backend.

Enabling automatic (zero-code) instrumentation

You can enable automatic instrumentation by setting environment variables, which allows OpenTelemetry to automatically trace supported PHP libraries.

For reference, see this WordPress PHP demo application which showcases OpenTelemetry PHP zero-code instrumentation and OpenTelemetry integration with Instana.

You can activate automatic instrumentation by setting the following minimal environment variables:

Variable	Description
`OTEL_PHP_AUTOLOAD_ENABLED`	Set to `true` to enable OpenTelemetry zero-code instrumentation
`OTEL_SERVICE_NAME`	Logical service name for infrastructure correlation
`OTEL_TRACES_EXPORTER`	Must be set to `otlp`
`OTEL_EXPORTER_OTLP_PROTOCOL`	Choose `grpc`, `http/protobuf`, or `http/json`
`OTEL_EXPORTER_OTLP_ENDPOINT`	URL of the OTLP endpoint either the Instana agent or backend

Example

OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_SERVICE_NAME=wordpress_otel_instrumentation
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_PROPAGATORS=instana,tracecontext

With these configurations in place, you can start a PHP application and OpenTelemetry traces from it are visible in the Instana UI.

You can also configure PHP applications to send OpenTelemetry traces directly to the Instana agent or backend by using OTLP endpoints.

Sending data to agent OTLP endpoint

The Instana agent provides OTLP endpoints that can receive OpenTelemetry data directly from your PHP applications.

To send data to the Instana agent OTLP endpoint, configure your PHP application as follows:

OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_SERVICE_NAME=your_service_name
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_PROPAGATORS=instana,tracecontext

Sending data to backend OTLP endpoint

For environments where direct communication with the Instana agent is not possible, you can configure your PHP application to send OpenTelemetry data directly to the Instana backend.

For more information, see Sending OpenTelemetry data to Instana.

To send data to the Instana backend OTLP endpoint, configure your PHP application as follows:

OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_SERVICE_NAME=your_service_name
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT="https://{instana-backend-otlp-acceptor-endpoint}":4317"
OTEL_EXPORTER_OTLP_HEADERS="x-instana-key:=apiToken {your-api-token}"
OTEL_PROPAGATORS=instana,tracecontext

Replace {region} with your Instana region and {your-api-token} with your Instana API token.

Configuring manual instrumentation

You need to manually instrument your applications with the OpenTelemetry SDK in the following cases:

You are not using OTel or Instana supported PHP library instrumentation.
You want to extend the PHP Tracer library's functionality.
You need finer control over instrumenting your applications.

To setup manual instrumentation, complete the following steps:

Install OpenTelemetry API and SDK packages.

composer require open-telemetry/sdk
composer require open-telemetry/api

Add your desired manual OpenTelemetry instrumentation to your PHP code following the OpenTelemetry PHP Manual Instrumentation documentation.
Choose OpenTelemetry trace context propagator for distributed applications. Instana supports W3C trace headers and Instana native headers for trace propagation.
- Using Instana propagator
```
OTEL_PROPAGATORS=instana
```
- Using tracecontext propagator
```
OTEL_PROPAGATORS=tracecontext
```
Using propagators allow Instana to join OpenTelemetry spans and other Instana spans into a single trace of your application.

For more information on example instrumentation for distributed tracing, see Enabling context propagation for distributed tracing.

The following simple example demonstrates manual instrumentation with a parent and a child span:


use OpenTelemetry\SDK\Registry;
use OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor;
use OpenTelemetry\SDK\Trace\TracerProvider;
use OpenTelemetry\API\Trace\SpanKind;

$tracerProvider = new TracerProvider(
   new SimpleSpanProcessor(
      Registry::spanExporterFactory("otlp")->create()
      )
    );
$tracer = $tracerProvider->getTracer('test');
$rootSpan = $tracer->spanBuilder('rootSpan')->startSpan();
$scope = $rootSpan->activate();

// Do some work
sleep(1);
// Create a child span (automatically becomes a child of the active span)
$childSpan = $tracer->spanBuilder('child-operation')
    ->startSpan();
$childScope = $childSpan->activate();
$childSpan->end();
$childScope->detach();

// Do more work
sleep(1);

// Add string attribute
$rootSpan->setAttribute('string.attribute', 'value');
$scope->detach();
$rootSpan->end();
$tracerProvider->shutdown();

OpenTelemetry Instana Propagator

The OpenTelemetry Propagator for Instana provides HTTP header propagation and baggage propagation to be used with the PHP application. This propagator converts the Instana trace correlation headers (X-INSTANA-T/X-INSTANA-S/X-INSTANA-L) to the OpenTelemetry SpanContext and OpenTelemetry SpanContext to Instana headers.

You can find a simple distributed PHP application example here demonstrating manual instrumentation that uses the Instana context propagator.

The Instana propagator does not handle a TraceState header without a parent span.

Installing the Propagator

To install the Instana propagator extension through composer, use the following command:

composer require open-telemetry/opentelemetry-propagation-instana

Using the Propagator

The Instana propagator uses both extract and inject methods to extract and inject trace context into the header. The propagator can be instantiated in the following ways:

Instantiating Instana propagator class.

$propagator = InstanaPropagator::getInstance();

Using environment variable

OTEL_PROPAGATORS=instana,baggage

For Baggage propagation, use OpenTelemetry MultiTextMapPropagator, then pass the array list of propagators such as Instana and baggage propagator as follows:

$propagator = new MultiTextMapPropagator([InstanaPropagator::getInstance(), BaggagePropagator::getInstance()]);

Option 3: Using Instana OpenTelemetry PHP Exporter

The Instana OpenTelemetry PHP Exporter is a dedicated exporter that converts OpenTelemetry spans into Instana native spans and uses the Instana native transport layer to forward traces to the Instana backend.

For detailed information on installation, configuration, and usage of the Instana OpenTelemetry PHP Exporter, see the OpenTelemetry PHP exporter.