OpenTelemetry PHP exporter (public preview)

The OpenTelemetry PHP SDK supports vendor-specific exporters. The spans that are created with the SDK can be sent to an Instana agent. For more information on exporters and the OpenTelemetry PHP SDK, refer to their documentation.

OpenTelemetry PHP exporter is supported on Linux operating systems only.

Installing the exporter

To install the exporter through Composer, run the following command:

composer require instana/opentelemetry-php-exporter

Configuring the exporter

You can create and configure the exporter in three ways:

  • Using the Instana SpanFactory
  • Configuring the SpanExporter instance manually
  • Using the OpenTelemetry registry

To use the exporter, complete the following steps:

  1. Install the composer package into your project.
  2. Create an instance of the InstanaExporter.

You must provide the following two Instana environment variables to the application for the factory and registry:

INSTANA_AGENT_HOST
INSTANA_AGENT_PORT

If the INSTANA_AGENT_HOST and INSTANA_AGENT_PORT environment variables are not set, the following default values are used:

INSTANA_AGENT_HOST=127.0.0.1
INSTANA_AGENT_PORT=42699

$tracerProvider = new TracerProvider(
    new SimpleSpanProcessor(
        (new \Instana\SpanExporterFactory)->create()
    )
);

To manually configure SpanExporter, run the following command:

$transport = new InstanaTransport('127.0.0.1:42699');
$exporter =  new SpanExporter(
	$transport, 
	new SpanConverter($transport->getUuid(), $transport->getPid())
);
$tracerProvider = new TracerProvider(
    new SimpleSpanProcessor($exporter)
);

To configure the exporter by using the OpenTelemetry registry, use the key "instana" when you construct a span exporter:

$tracerProvider = new TracerProvider(
    new SimpleSpanProcessor(
        Registry::spanExporterFactory("instana")->create()
    )
);

Example of exporter usage

After the tracer provider is set up, you can initialize an OpenTelemetry PHP tracer and use the SDK as normal.

$tracer = $tracerProvider->getTracer('io.instana.opentelemetry.php');

$span = $tracer->spanBuilder('root')->startSpan();
$span->setAttribute('remote_ip', '1.2.3.4')
    ->setAttribute('country', 'CAN');
$span->addEvent('generated_session', [
    'id' => md5((string) microtime(true)),
]);
$span->end();

$tracerProvider->shutdown();

Auto instrumentation

The exporter supports auto-instrumentation, and you can configure the exporter in conjunction with the OpenTelemetry SDK. To enable auto-instrumentation, use the following environment variables or configure the php.ini file:

OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_TRACES_EXPORTER=instana

After you configure the exporter, the traces that are exported to the Instana agent are installed in your application. The traces are dependent on the instrumentation libraries. Therefore, you must add the appropriate instrumentation libraries that your application requires.

composer require open-telemetry/opentelemetry-auto-curl
composer require open-telemetry/opentelemetry-auto-wordpress

Setting a custom service name

You can define a custom service name for your application by using the environment variables INSTANA_SERVICE_NAME or OTEL_SERVICE_NAME. If both variables are present, the value of INSTANA_SERVICE_NAME takes precedence over OTEL_SERVICE_NAME.

Capturing custom HTTP headers

In the PHP Instana exporter, you can capture the custom HTTP headers from both requests and responses by using the environment variables. You can use the following environment variables to specify the custom HTTP headers:

OTEL_PHP_INSTRUMENTATION_HTTP_RESPONSE_HEADERS=content-type,server
OTEL_PHP_INSTRUMENTATION_HTTP_REQUEST_HEADERS=host,accept

Distributed tracing

Instana PHP exporter supports w3C trace context propagation.

Limitations

  • The exporter currently does not support the distributed tracing with Instana native headers X-INSTANA-T, X-INSTANA-L, and X-INSTANA-S.