PHP Auto Instrumentation

KloudMate natively supports OpenTelemetry (OTel) for auto-instrumenting PHP applications. Because OpenTelemetry actively maintains robust auto-instrumentation agents for PHP, we rely on their standard process to ensure you always have the most up-to-date and compatible tracing capabilities.

Tip

For a detailed, step-by-step tutorial covering both Slim and Laravel, see the Instrument a PHP App guide.

Routing Data to KloudMate

To send auto-instrumented data to KloudMate, you only need to configure the OpenTelemetry agent with KloudMate’s OTLP endpoint and your API key using environment variables.

When running your PHP application, provide the following environment variables (or set them in your environment configuration):

export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel.kloudmate.com:4318"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=YOUR_API_KEY"
export OTEL_SERVICE_NAME="your-php-service-name"

Replace YOUR_API_KEY with your actual KloudMate API key.

Setup Instructions

For the actual installation and usage instructions of the OpenTelemetry PHP auto-instrumentation extension, please refer to the official OpenTelemetry documentation.

View Official OpenTelemetry PHP Zero-code Instrumentation Docs →

Laravel

This section provides step-by-step instructions to integrate OpenTelemetry zero-code instrumentation into an existing Laravel application and route the data to KloudMate.

Prerequisites

• PHP 8.0+ (PHP 8.2 recommended)
• Composer installed
• An existing Laravel application
• A running KloudMate Agent or OTLP-compatible backend

Step 1: Install the OpenTelemetry PHP Extension

Zero-code instrumentation requires the opentelemetry PHP extension to intercept and instrument PHP function calls automatically.

Linux (Ubuntu/Debian)

sudo apt-get install php-dev php-pear
sudo pecl install opentelemetry

macOS

pecl install opentelemetry

Enable the Extension

Add the following line to your php.ini file:

extension=opentelemetry.so

Tip: Find your php.ini location by running php --ini.

Verify Installation

php -m | grep opentelemetry

You should see opentelemetry in the output.

Step 2: Install OpenTelemetry Packages via Composer

Run the following commands in your Laravel project root directory:

composer require open-telemetry/opentelemetry-auto-laravel
composer require open-telemetry/sdk
composer require open-telemetry/exporter-otlp
composer require open-telemetry/api

What each package does

Package	Purpose
open-telemetry/opentelemetry-auto-laravel	Automatic zero-code instrumentation hooks for Laravel
open-telemetry/sdk	OpenTelemetry SDK for trace/metric/log export
open-telemetry/exporter-otlp	OTLP protocol exporter to send data to collectors/agents
open-telemetry/api	OpenTelemetry API contracts

Step 3: Configure Environment Variables

Add the following variables to your Laravel .env file:

# ============================================
# OpenTelemetry Configuration
# ============================================

# Enable auto-instrumentation (REQUIRED)
OTEL_PHP_AUTOLOAD_ENABLED=true

# Service identification
OTEL_SERVICE_NAME=my-laravel-app
OTEL_SERVICE_VERSION=1.0.0

# Exporter configuration
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.kloudmate.com:4318
OTEL_EXPORTER_OTLP_HEADERS="Authorization=YOUR_API_KEY"
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

# Also export logs and metrics (optional)
OTEL_LOGS_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp

# Resource attributes
OTEL_RESOURCE_ATTRIBUTES=deployment.environment=development,host.name=localhost

Replace YOUR_API_KEY with your actual KloudMate API key.

Important Notes

Variable	Description
OTEL_PHP_AUTOLOAD_ENABLED=true	Critical. Enables the auto-loader to register instrumentations automatically.
OTEL_SERVICE_NAME	Name that identifies your application in the observability backend.
OTEL_EXPORTER_OTLP_ENDPOINT	URL of your KloudMate OTLP endpoint.
OTEL_EXPORTER_OTLP_HEADERS	Your KloudMate API key for authentication.
OTEL_EXPORTER_OTLP_PROTOCOL	http/protobuf (default) or grpc. Must match what your collector supports.

Docker to Host Machine (KM Agent on Host)

If your Laravel app runs in Docker and the KM Agent runs on the host machine, use:

OTEL_EXPORTER_OTLP_ENDPOINT=http://host.docker.internal:4318

Note: Ensure your KM Agent is listening on 0.0.0.0 (all interfaces), not just 127.0.0.1, otherwise the container cannot reach it.

Step 4: Understanding Zero-Code Instrumentation

The opentelemetry-auto-laravel package uses the opentelemetry PHP extension to automatically instrument your application without any code changes.

What gets automatically instrumented

• HTTP Requests — Incoming requests to controllers and middleware
• Database Queries — Eloquent and Query Builder operations
• Cache Operations — Redis, Memcached, and file cache calls
• Queue Jobs — Job dispatching and processing (sync, database, redis drivers)
• Exceptions & Errors — Automatic error tracking and stack traces
• Outgoing HTTP Requests — Guzzle HTTP client calls

What you do NOT need to do

• No manual span creation
• No middleware additions
• No controller modifications
• No service provider registration
• No use statements or imports

Step 5: Verify the Integration

1. Confirm the PHP Extension is Active

php artisan tinker

Inside Tinker, run:

echo extension_loaded('opentelemetry') ? 'YES' : 'NO';

Expected output: YES

2. Generate Some Traffic

Make a request to your application:

curl http://localhost:8000/

Or visit any route in your browser.

3. Check Your Observability Backend

• If using KM Agent — check the agent logs or the KloudMate dashboard.
• If using OTel Collector — check the collector container/service logs.
• If using Jaeger / Tempo / Zipkin — open the UI and search for traces with your service name (OTEL_SERVICE_NAME).

You should see traces, spans, and metadata automatically captured from your Laravel app.

Optional: Fine-Tuning & Debugging

Disable Specific Instrumentations

If you want to disable Laravel auto-instrumentation:

OTEL_PHP_DISABLED_INSTRUMENTATIONS=laravel

Switch to gRPC Protocol

OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.kloudmate.com:4317

Enable Debug Logging

If traces are not appearing, enable SDK debug mode:

OTEL_LOG_LEVEL=debug

Add Custom Resource Attributes

OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production,host.name=prod-server-01,service.namespace=my-org

Quick Reference: Minimal Configuration

The absolute minimum required to get zero-code instrumentation working with KloudMate:

OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_SERVICE_NAME=my-laravel-app
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.kloudmate.com:4318
OTEL_EXPORTER_OTLP_HEADERS="Authorization=YOUR_API_KEY"

Summary

Step	Action
1	Install the opentelemetry PHP extension via pecl
2	Install opentelemetry-auto-laravel + SDK + Exporter via Composer
3	Add OTEL_* environment variables to your .env file
4	Ensure your KloudMate Agent / Collector is running and accessible
5	Run your application — instrumentation is fully automatic

That’s it! Zero-code instrumentation means zero code changes in your application.