This document contains instructions on how to set up OpenTelemetry instrumentation in your PHP applications and view your application traces in 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. 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
brew install gcc make autoconf
Step 2: Build the extension
With our environment set up we can install the extension using PECL:
pecl install opentelemetry
pecl install protobuf
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/opentelemetry-auto-slim
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=ingest.<region>.signoz.cloud:443 \
OTEL_EXPORTER_OTLP_HEADERS=signoz-ingestion-key=<INGESTION_KEY> \
OTEL_PROPAGATORS=baggage,tracecontext \
php -S localhost:8080 app.php
- Set the
<region>to match your SigNoz Cloud region - Replace
<your-ingestion-key>with your SigNoz ingestion key <service_name>is name of your service
Send traces via OTel Collector binary
Step 1. Install OTel Collector binary
OTel Collector binary helps to collect logs, hostmetrics, resource and infra attributes.
You can find instructions to install OTel Collector binary here in your VM.
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
brew install gcc make autoconf
Step 3: Build the extension
With our environment set up we can install the extension using PECL:
pecl install opentelemetry
pecl install protobuf
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/opentelemetry-auto-slim
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 Variable | Value |
|---|---|
| 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.php | you can replace this with the run command of your PHP application |
Step 1: Install OTel Collector agent in K8s
For PHP application deployed on Kubernetes, you need to install OTel Collector agent in your k8s infra to collect and send traces to SigNoz Cloud. You can find the instructions to install OTel Collector agent here.
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
brew 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
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 Variable | Value |
|---|---|
| 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.php | you can replace this with the run command of your PHP application |
From Windows, there are two ways to send data to SigNoz Cloud.
- Send traces directly to SigNoz Cloud
- Send traces via OTel Collector binary (recommended)
Send traces directly to SigNoz cloud
Here we will be sending traces to SigNoz cloud in 4 easy steps. We will be using Zero-code configuration for Automatic Instrumentation.
Step 1: Setup Development Environment
Initialize the application using
composer init --no-interaction --stability beta --require slim/slim:"^4" --require slim/psr7:"^1"
After successful run of prior command a file named composer.json will be generated if it does not exist. Next run the following command, make sure the version of php you are using is 7.4 or else you might encounter some issues running the following command.
composer update
Step 2: Build the extension
With our environment set up we can install the extension using PECL:
pecl install opentelemetry
If gRPC is already downloaded and installed, skip the following step.
pecl install grpc
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 guzzlehttp/guzzle
You can install the additional dependencies provided by OpenTelemetry for different PHP frameworks from here.
Step 4: Modify php code
<?php
use OpenTelemetry\API\Common\Instrumentation\Globals;
use OpenTelemetry\API\Trace\Propagation\TraceContextPropagator;
use OpenTelemetry\Contrib\Otlp\SpanExporter;
use OpenTelemetry\SDK\Common\Attribute\Attributes;
use OpenTelemetry\SDK\Common\Export\Stream\StreamTransportFactory;
use OpenTelemetry\SDK\Resource\ResourceInfo;
use OpenTelemetry\SDK\Resource\ResourceInfoFactory;
use OpenTelemetry\SDK\Sdk;
use OpenTelemetry\SDK\Trace\Sampler\AlwaysOnSampler;
use OpenTelemetry\SDK\Trace\Sampler\ParentBased;
use OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor;
use OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessorBuilder;
use OpenTelemetry\SDK\Trace\TracerProvider;
use OpenTelemetry\SemConv\ResourceAttributes;
use OpenTelemetry\Contrib\Grpc\GrpcTransportFactory;
use OpenTelemetry\Contrib\Otlp\OtlpUtil;
use OpenTelemetry\API\Common\Signal\Signals;
function initOpenTelemetry()
{
$resource = ResourceInfoFactory::emptyResource()->merge(ResourceInfo::create(Attributes::create([
ResourceAttributes::SERVICE_NAME => '<SERVICE_NAME>'
])));
$headers = [
'signoz-ingestion-key' => "<INGESTION_KEY>",
];
$transport = (new GrpcTransportFactory())->create('ingest.<region>.signoz.cloud:443' . OtlpUtil::method(Signals::TRACE), 'application/x-protobuf', $headers);
$spanExporter = new SpanExporter($transport);
$tracerProvider = TracerProvider::builder()
->addSpanProcessor(
(new BatchSpanProcessorBuilder($spanExporter))->build()
)
->setResource($resource)
->setSampler(new ParentBased(new AlwaysOnSampler()))
->build();
Sdk::builder()
->setTracerProvider($tracerProvider)
->setPropagator(TraceContextPropagator::getInstance())
->setAutoShutdown(true)
->buildAndRegisterGlobal();
}
?>
- Set the
<region>to match your SigNoz Cloud region - Replace
<your-ingestion-key>with your SigNoz ingestion key <service_name>is name of your service
Step 5: Set environment variables and run app
Run application using your run command or the following generalized command (depending on framework you are using):
php -S localhost:8080 app.php
Send traces via OTel Collector binary
Step 1. Install OTel Collector binary
OTel Collector binary helps to collect logs, hostmetrics, resource and infra attributes.
You can find instructions to install OTel Collector binary here in your VM.
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:
Step 3: Build the extension
With our environment set up we can install the extension using PECL:
pecl install opentelemetry
If gRPC is already downloaded and installed, skip the following step.
pecl install grpc
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 guzzlehttp/guzzle
You can install the additional dependencies provided by OpenTelemetry for different PHP frameworks from here.
Step 5: Modify php code
<?php
use OpenTelemetry\API\Common\Instrumentation\Globals;
use OpenTelemetry\API\Trace\Propagation\TraceContextPropagator;
use OpenTelemetry\Contrib\Otlp\SpanExporter;
use OpenTelemetry\SDK\Common\Attribute\Attributes;
use OpenTelemetry\SDK\Common\Export\Stream\StreamTransportFactory;
use OpenTelemetry\SDK\Resource\ResourceInfo;
use OpenTelemetry\SDK\Resource\ResourceInfoFactory;
use OpenTelemetry\SDK\Sdk;
use OpenTelemetry\SDK\Trace\Sampler\AlwaysOnSampler;
use OpenTelemetry\SDK\Trace\Sampler\ParentBased;
use OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor;
use OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessorBuilder;
use OpenTelemetry\SDK\Trace\TracerProvider;
use OpenTelemetry\SemConv\ResourceAttributes;
use OpenTelemetry\Contrib\Grpc\GrpcTransportFactory;
use OpenTelemetry\Contrib\Otlp\OtlpUtil;
use OpenTelemetry\API\Common\Signal\Signals;
function initOpenTelemetry()
{
$resource = ResourceInfoFactory::emptyResource()->merge(ResourceInfo::create(Attributes::create([
ResourceAttributes::SERVICE_NAME => '<SERVICE_NAME>'
])));
$headers = [];
$transport = (new GrpcTransportFactory())->create('<COLLECTOR_ENDPOINT>' . OtlpUtil::method(Signals::TRACE), 'application/x-protobuf', $headers);
$spanExporter = new SpanExporter($transport);
$tracerProvider = TracerProvider::builder()
->addSpanProcessor(
(new BatchSpanProcessorBuilder($spanExporter))->build()
)
->setResource($resource)
->setSampler(new ParentBased(new AlwaysOnSampler()))
->build();
Sdk::builder()
->setTracerProvider($tracerProvider)
->setPropagator(TraceContextPropagator::getInstance())
->setAutoShutdown(true)
->buildAndRegisterGlobal();
}
?>
Step 6: Set environment variables and run app
Run application using your run command or the following generalized command (depending on framework you are using):
php -S localhost:8080 app.php
You can change the env vars value by referencing values from the following lookup table
| Environment Variable | Value |
|---|---|
| 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.php | you can replace this with the run command of your PHP application |
There are two ways to send data to SigNoz Cloud. You can containerize the images in both the cases.
Send traces directly to SigNoz Cloud
Step 1. Configure OpenTelemetry to run in Docker Container
Add the following in your Dockerfile.
...
# Install build tools, protobuf, unzip, git, curl
RUN apt-get update && apt-get install -y \
gcc \
make \
autoconf \
libprotobuf-dev \
protobuf-compiler \
unzip \
git \
curl \
&& apt-get clean \
&& rm -rf /var/lib/apt/lists/*
# Install Composer globally
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
...
# Install PHP extensions via PECL
RUN pecl install opentelemetry \
&& pecl install protobuf \
&& docker-php-ext-enable opentelemetry protobuf
...
# Environment variables
ENV OTEL_PHP_AUTOLOAD_ENABLED=true
ENV OTEL_SERVICE_NAME="<service_name>"
ENV OTEL_TRACES_EXPORTER="otlp"
ENV OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
ENV OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
ENV OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
ENV OTEL_PROPAGATORS="baggage,tracecontext"
...
- Set the
<region>to match your SigNoz Cloud region - Replace
<your-ingestion-key>with your SigNoz ingestion key <service_name>is name of your service
The above steps install OpenTelemetry dependencies directly inside the Docker container without altering composer.json of project & sets environment variables to export the traces.
Step 2. Run your Docker container
Here's how you can run your docker container:
docker build -t <image-name> . && docker run -d -p <host-port>:<container-port> <image-name>
Replace
<image-name>,<host-port>, and<container-port>with values for your application.-druns the container in detached mode-pmaps a host port to a container port
Step 3. Validate if your application is sending traces to SigNoz cloud by following the instructions here.
In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.
Send traces via OTel Collector binary
Step 1. Configure OpenTelemetry to run in Docker Container
Add the following in your Dockerfile.
# -------- Stage 1: Get OpenTelemetry Collector --------
FROM otel/opentelemetry-collector-contrib:0.131.0 AS otel
...
# Install build tools and deps
RUN apt-get update && apt-get install -y \
gcc \
make \
autoconf \
libprotobuf-dev \
protobuf-compiler \
unzip \
git \
curl \
&& apt-get clean \
&& rm -rf /var/lib/apt/lists/*
# Install Composer globally
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
...
# Install PECL extensions (opentelemetry + protobuf)
RUN pecl install opentelemetry \
&& pecl install protobuf \
&& docker-php-ext-enable opentelemetry protobuf
...
# Copy OpenTelemetry Collector binary + config from first stage
COPY --from=otel /otelcol-contrib /otelcol-contrib
COPY --from=otel /etc/otelcol-contrib /etc/otelcol-contrib
COPY config.yaml /etc/otelcol-contrib/config.yaml
# Expose ports (App + Collector)
EXPOSE <APP_PORT> 4317 4318
...
# Environment variables (point PHP to local Collector)
ENV OTEL_PHP_AUTOLOAD_ENABLED=true
ENV OTEL_SERVICE_NAME="<service_name>"
ENV OTEL_TRACES_EXPORTER="otlp"
ENV OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
ENV OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
ENV OTEL_PROPAGATORS="baggage,tracecontext"
# Run both Collector and PHP app in the same container
CMD sh -c "/otelcol-contrib --config=/etc/otelcol-contrib/config.yaml & <run_command>"
Make sure you have config.yaml in root of the application. This config.yaml should be copied from third step of this
- Replace
<run_command>with the command to run your application <service_name>is name of your service
Step 2. Run your Docker container
Run your docker container to start exporting.
docker build -t <image-name> . && docker run -d -p <host-port>:<container-port> <image-name>
Replace
<image-name>,<host-port>, and<container-port>with values for your application.-druns the container in detached mode-pmaps a host port to a container port
Step 3. You can validate if your application is sending traces to SigNoz cloud by following the instructions here.
In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.
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
brew install gcc make autoconf
Step 2: Build the extension
With our environment set up we can install the extension using PECL:
pecl install opentelemetry
pecl install protobuf
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/opentelemetry-auto-slim \
php-http/guzzle7-adapter \
open-telemetry/exporter-otlp
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=<self-host-ip> \
OTEL_PROPAGATORS=baggage,tracecontext \
php -S localhost:8080 app.php
- Set the
<self-host-ip>as the IP of Self-Hosted SigNoz. <service_name>is name of your service
Sample PHP Application
We have included a sample PHP application at Sample PHP App Github Repo,
