OpenTelemetry integration for PHP applications
You can integrate OpenTelemetry with PHP by configuring the default OpenTelemetry Protocol (OTLP) Exporter of any PHP application (instrumented by OpenTelemetry) to send the OpenTelemetry traces to the Instana agent or the Instana backend. This is described in OpenTelemetry.
Requirements
The OpenTelemetry instrumentation for PHP application has the following requirements:
- OpenTelemetry PHP extension
- Composer autoloading
- OpenTelemetry SDK
- OpenTelemetry instrumentation libraries
- Configuration
The OpenTelemetry PHP extension must be installed together with other dependencies like the OpenTelemetry SDK and one or more instrumented libraries in the PHP environment. For more information about installing these components and their dependencies, see OpenTelemetry's documentation and OpenTelemetry WordPress Automatic Instrumentation demo application.
OpenTelementry traces are sent either directly to the Instana backend or the Instana agent depending on the configuration that is used. Both options might need to be configured to enable ingestion of OpenTelemetry traces through their OTLP endpoints. For more information, see Sending OpenTelemetry data to Instana.
Enabling OpenTelemetry automatic instrumentation
OpenTelemetry automatic instrumentation can be configured either by setting the environment variables or modifying the php.ini
file that the OpenTelemetry SDK uses to determine how to format the traces it emits, which protocol to
use for transporting them, and which endpoint to send them to.
The following variables must be configured either through the INI file or by setting them in the environment:
OTEL_PHP_AUTOLOAD_ENABLED
- Specifies the state of OpenTelemetry automatic instrumentation. Set it to
true
to enable it andfalse
to disable it.
- Specifies the state of OpenTelemetry automatic instrumentation. Set it to
OTEL_SERVICE_NAME
- Specifies the service name that is used in infrastructure correlation.
OTEL_TRACES_EXPORTER
- Specifies the OpenTelemetry exporter to use for exporting traces. Set it to
otlp
to use OTLP Exporter.
- Specifies the OpenTelemetry exporter to use for exporting traces. Set it to
OTEL_EXPORTER_OTLP_PROTOCOL
- Specifies the transport protocol to be used by OTLP Exporter for sending traces to the configured endpoint. Allowed values are
grpc
,http/protobuf
,http/json
.
- Specifies the transport protocol to be used by OTLP Exporter for sending traces to the configured endpoint. Allowed values are
OTEL_EXPORTER_OTLP_ENDPOINT
- Specifies the endpoint URL that the OTLP Exporter must send traces to. Set it to either the Instana agent or Instana backend OTLP endpoint corresponding to the protocol set in variable
OTEL_EXPORTER_OTLP_PROTOCOL
. For more information about Instana backend and Instana agent endpoints, ports and protocols for OTLP data ingestion, see Sending OpenTelemetry data to Instana. Use the Instana agent's OTLP endpoint as this might improve the infrastructure correlation of the OpenTelemetry traces.
- Specifies the endpoint URL that the OTLP Exporter must send traces to. Set it to either the Instana agent or Instana backend OTLP endpoint corresponding to the protocol set in variable
The following example shows the environment variables configured to send the OpenTelemetry traces to the Instana agent running on the local host over gRPC protocol:
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
With these configurations in place, a PHP application can be started and OpenTelemetry traces from it will be visible in the Instana UI.
Known limitations
When visualizing OpenTelemetry traces in Instana UI, some spans might show Unspecified
in their destination endpoint and destination service placeholders due to limited infrastructure correlation for these traces. This is because
the OpenTelemetry PHP automatic instrumentation might not set some expected fields in the OTLP traces that the Instana backend expects for determining the endpoint and service names when correlating.