Skip to main content

PHP Opentelemetry Instrumentation

This doc contains instructions about how to set up OpenTelemetry(OTel) instrumentation in your PHP application. OpenTelemetry, also known as OTel for short, is an open-source observability framework that can help you generate and collect telemetry data - traces, metrics, and logs from your PHP application.

Once the telemetry data is generated, you can configure an exporter to send the data to SigNoz for monitoring and visualization.

There are three major steps to using OpenTelemetry:

  • Instrumenting your PHP application with OpenTelemetry
  • Configuring the exporter to send data to SigNoz
  • Validating that configuration to ensure that data is being sent as expected.

In this documentation, we will instrument a PHP application for traces and send it to SigNoz.

Requirements​

Send traces to SigNoz Cloud​

Based on your application environment, you can choose the setup below to send traces to SigNoz Cloud.

From VMs, there are two ways to send data to SigNoz Cloud.

Send traces directly to SigNoz cloud​

Here we will be sending traces to SigNoz cloud in 4 easy steps, if you want to send traces to self hosted SigNoz , you can refer to this. We will be using Zero-code configuration for Automatic Instrumentation.

Step 1: Setup Development Environment

To configure our PHP application to send data, you need to use OpenTelemetry PHP extension. Since the extension is built from the source, you need to have the build tools, which can be installed using the following command:

sudo apt-get install gcc make autoconf

Step 2: Build the extension

With our environment set up we can install the extension using PECL:

pecl install opentelemetry

After successfully installing the OpenTelemetry extension, add the extension to php.ini file of your project:

[opentelemetry]
extension=opentelemetry.so

Verify that the extension is enabled by running:

php -m | grep opentelemetry

This should output:

opentelemetry

Step 3: Add the dependencies

Add dependencies required for OpenTelemetry SDK for PHP to perform automatic instrumentation using this command :

composer config allow-plugins.php-http/discovery false
composer require \
  open-telemetry/sdk \
  open-telemetry/exporter-otlp \
  php-http/guzzle7-adapter \
  open-telemetry/transport-grpc
info

You can install the additional dependencies provided by OpenTelemetry for different PHP frameworks from here.

Step 4: Set environment variables and run app

We are passing the environment variables on run time and this way we don't have to change anything in code. Run your application using:

env OTEL_PHP_AUTOLOAD_ENABLED=true \
    OTEL_SERVICE_NAME=<SERVICE_NAME> \
    OTEL_TRACES_EXPORTER=otlp \
    OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
    OTEL_EXPORTER_OTLP_ENDPOINT=<SIGNOZ_ENDPOINT> \
    OTEL_EXPORTER_OTLP_HEADERS=signoz-access-token=<INGESTION_KEY> \
    OTEL_PROPAGATORS=baggage,tracecontext \
    php -S localhost:8080 app.php

You can change the env vars value by referencing values from the following lookup table

Environment VariableValue
OTEL_SERVICE_NAME<SERVICE_NAME> replace it with name of your app
OTEL_EXPORTER_OTLP_ENDPOINT<SIGNOZ_ENDPOINT> replace this with SigNoz cloud endpoint
OTEL_EXPORTER_OTLP_HEADERSsignoz-access-token=<INGESTION_KEY> replace this with the ingestion key which you must have received in mail
php -S localhost:8080 app.phpyou can replace this with the run command of your PHP application

Send traces via OTel Collector binary​

Step 1: Install OTel Collector

OTel Collector binary helps to collect logs, hostmetrics, resource and infra attributes. It is recommended to install Otel Collector binary to collect and send traces to SigNoz cloud. You can correlate signals and have rich contextual data through this way.

note

You can find instructions to install OTel Collector binary here in your VM. Once you are done setting up your OTel Collector binary, you can follow the below steps for instrumenting your PHP application.

Step 2: Setup Development Environment

To configure our PHP application to send data, you need to use OpenTelemetry PHP extension. Since the extension is built from the source, you need to have the build tools, which can be installed using the following command:

sudo apt-get install gcc make autoconf

Step 3: Build the extension

With our environment set up we can install the extension using PECL:

pecl install opentelemetry

After successfully installing the OpenTelemetry extension, add the extension to php.ini file of your project:

[opentelemetry]
extension=opentelemetry.so

Verify that the extension is enabled by running:

php -m | grep opentelemetry

This should output:

opentelemetry

Step 4: Add the dependencies

Add dependencies required for OpenTelemetry SDK for PHP to perform automatic instrumentation using this command :

composer config allow-plugins.php-http/discovery false
composer require \
  open-telemetry/sdk \
  open-telemetry/exporter-otlp \
  php-http/guzzle7-adapter \
  open-telemetry/transport-grpc
info

You can install the additional dependencies provided by OpenTelemetry for different PHP frameworks from here.

Step 5: Set environment variables and run app

We are passing the environment variables on run time and this way we don't have to change anything in code. Run your application using:

env OTEL_PHP_AUTOLOAD_ENABLED=true \
    OTEL_SERVICE_NAME=<SERVICE_NAME> \
    OTEL_TRACES_EXPORTER=otlp \
    OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
    OTEL_EXPORTER_OTLP_ENDPOINT=<COLLECTOR_ENDPOINT> \
    OTEL_PROPAGATORS=baggage,tracecontext \
    php -S localhost:8080 app.php

You can change the env vars value by referencing values from the following lookup table

Environment VariableValue
OTEL_SERVICE_NAME<SERVICE_NAME> replace it with name of your app
OTEL_EXPORTER_OTLP_ENDPOINT<COLLECTOR_ENDPOINT> replace this with the Otel Collector Endpoint. If you have hosted it somewhere, provide the URL. Otherwise, the default is http://localhost:4317, if you have followed our guide.
php -S localhost:8080 app.phpyou can replace this with the run command of your PHP application

Send Traces to Self-Hosted SigNoz​

Step 1: Setup Development Environment

To configure our PHP application to send data, you need to use OpenTelemetry PHP extension. Since the extension is built from the source, you need to have the build tools, which can be installed using the following command:

sudo apt-get install gcc make autoconf

Step 2: Build the extension

With our environment set up we can install the extension using PECL:

pecl install opentelemetry

After successfully installing the OpenTelemetry extension, add the extension to php.ini file of your project:

[opentelemetry]
extension=opentelemetry.so

Verify that the extension is enabled by running:

php -m | grep opentelemetry

This should output:

opentelemetry

Step 3: Add the dependencies

Add dependencies required for OpenTelemetry SDK for PHP to perform automatic instrumentation using this command :

composer config allow-plugins.php-http/discovery false
composer require \
  open-telemetry/sdk \
  open-telemetry/exporter-otlp \
  php-http/guzzle7-adapter \
  open-telemetry/transport-grpc
info

You can install the additional dependencies provided by OpenTelemetry for different PHP frameworks from here.

Step 4: Set environment variables and run app

We are passing the environment variables on run time and this way we don't have to change anything in code. Run your application using:

env OTEL_PHP_AUTOLOAD_ENABLED=true \
    OTEL_SERVICE_NAME=<SERVICE_NAME> \
    OTEL_TRACES_EXPORTER=otlp \
    OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
    OTEL_EXPORTER_OTLP_ENDPOINT=<SIGNOZ_ENDPOINT> \
    OTEL_PROPAGATORS=baggage,tracecontext \
    php -S localhost:8080 app.php

You can change the env vars value by referencing values from the following lookup table

Environment VariableValue
OTEL_SERVICE_NAME<SERVICE_NAME> replace it with name of your app
OTEL_EXPORTER_OTLP_ENDPOINT<SIGNOZ_ENDPOINT> replace this with the url where you have hosted SigNoz
php -S localhost:8080 app.phpyou can replace this with the run command of your PHP application

Sample PHP Application​

We have included a sample PHP application at Sample PHP App Github Repo,

Tutorial​

Here's a tutorial with step by step guide on how to install SigNoz and start monitoring a sample PHP app.

Frequently Asked Questions​

  1. How to find what to use in IP of SigNoz if I have installed SigNoz in Kubernetes cluster?

    Based on where you have installed your application and where you have installed SigNoz, you need to find the right value for this. Please use this grid to find the value you should use for IP of SigNoz

  2. I am sending data from my application to SigNoz, but I don't see any events or graphs in the SigNoz dashboard. What should I do?

    This could be because of one of the following reasons:

    1. Your application is generating telemetry data, but not able to connect with SigNoz installation

      Please use this troubleshooting guide to find if your application is able to access SigNoz installation and send data to it.

    2. Your application is not actually generating telemetry data

      Please check if the application is generating telemetry data first. You can use Console Exporter to just print your telemetry data in console first. Join our Slack Community if you need help on how to export your telemetry data in console

    3. Your SigNoz installation is not running or behind a firewall

      Please double check if the pods in SigNoz installation are running fine. docker ps or kubectl get pods -n platform are your friends for this.