From 861bff73b6e98e2b21e3766d80af5ac803553874 Mon Sep 17 00:00:00 2001 From: Ansh Garhewal Date: Fri, 5 Jun 2026 20:31:32 +0530 Subject: [PATCH 1/3] php apm to add laravel docs --- .../auto-instrumentation/php.mdx | 227 ++++++++++ .../manual-instrumentation/php.mdx | 2 +- src/content/docs/guides/index.mdx | 2 +- src/content/docs/guides/opentelemetry/php.mdx | 426 +++++++++++++++--- 4 files changed, 597 insertions(+), 60 deletions(-) diff --git a/src/content/docs/docs/apm-and-tracing/auto-instrumentation/php.mdx b/src/content/docs/docs/apm-and-tracing/auto-instrumentation/php.mdx index 03661f8d..ee29901d 100644 --- a/src/content/docs/docs/apm-and-tracing/auto-instrumentation/php.mdx +++ b/src/content/docs/docs/apm-and-tracing/auto-instrumentation/php.mdx @@ -26,3 +26,230 @@ export OTEL_SERVICE_NAME="your-php-service-name" 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 →**](https://opentelemetry.io/docs/zero-code/php/) + +## 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) + +```bash +sudo apt-get install php-dev php-pear +sudo pecl install opentelemetry +``` + +#### macOS + +```bash +pecl install opentelemetry +``` + +#### Enable the Extension + +Add the following line to your `php.ini` file: + +```ini +extension=opentelemetry.so +``` + +> **Tip:** Find your `php.ini` location by running `php --ini`. + +#### Verify Installation + +```bash +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: + +```bash +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: + +```ini +# ============================================ +# 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: + +```ini +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 + +```bash +php artisan tinker +``` + +Inside Tinker, run: + +```php +echo extension_loaded('opentelemetry') ? 'YES' : 'NO'; +``` + +Expected output: `YES` + +#### 2. Generate Some Traffic + +Make a request to your application: + +```bash +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: + +```ini +OTEL_PHP_DISABLED_INSTRUMENTATIONS=laravel +``` + +#### Switch to gRPC Protocol + +```ini +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: + +```ini +OTEL_LOG_LEVEL=debug +``` + +#### Add Custom Resource Attributes + +```ini +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: + +```ini +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. diff --git a/src/content/docs/docs/apm-and-tracing/manual-instrumentation/php.mdx b/src/content/docs/docs/apm-and-tracing/manual-instrumentation/php.mdx index dbe33138..bdfd68eb 100644 --- a/src/content/docs/docs/apm-and-tracing/manual-instrumentation/php.mdx +++ b/src/content/docs/docs/apm-and-tracing/manual-instrumentation/php.mdx @@ -37,4 +37,4 @@ OpenTelemetry is continuously evolving. For the most up-to-date SDK instructions --- **Looking for a step-by-step tutorial?** -Check out our [Instrument a PHP App](../../../../guides/opentelemetry/php/) guide to see how to manually instrument a simple PHP application. +Check out our [Instrument a PHP App](../../../../guides/opentelemetry/php/) guide to see how to auto-instrument a PHP application using OpenTelemetry zero-code instrumentation. diff --git a/src/content/docs/guides/index.mdx b/src/content/docs/guides/index.mdx index 2ef51ff8..ba86fc90 100644 --- a/src/content/docs/guides/index.mdx +++ b/src/content/docs/guides/index.mdx @@ -15,7 +15,7 @@ Walkthroughs for sending application logs directly to KloudMate. ## OpenTelemetry Instrumentation Tutorials -Step-by-step tutorials on how to manually instrument sample applications from scratch using the OpenTelemetry SDKs. +Step-by-step tutorials on how to instrument sample applications from scratch using OpenTelemetry zero-code and SDK instrumentation. - [Instrument a Node.js App](/guides/opentelemetry/node-js/) - [Instrument a Python App](/guides/opentelemetry/python/) diff --git a/src/content/docs/guides/opentelemetry/php.mdx b/src/content/docs/guides/opentelemetry/php.mdx index f1a4f13e..36f5992b 100644 --- a/src/content/docs/guides/opentelemetry/php.mdx +++ b/src/content/docs/guides/opentelemetry/php.mdx @@ -1,21 +1,27 @@ --- title: "Instrument a PHP App" -description: "Learn how to instrument a sample PHP application with OpenTelemetry to send data to KloudMate." +description: "Learn how to instrument sample PHP applications (Slim and Laravel) with OpenTelemetry to send data to KloudMate." --- -In this guide, we will walk you through the process of setting up and using OpenTelemetry in PHP. You will learn how to instrument a simple PHP application to produce traces, metrics, and logs and export them to KloudMate. -**Step 1: Prerequisites** +import { Tabs, TabItem } from '@astrojs/starlight/components'; -OpenTelemetry requires PHP 8.0+ for automatic instrumentation. Before moving forward ensure that you have the following installed: +This guide walks you through the process of instrumenting **PHP applications** using **zero-code OpenTelemetry** for collecting traces, metrics, and logs with KloudMate. Zero-code instrumentation enables you to capture telemetry from many popular libraries and frameworks without modifying your application code. -- [PHP 8.0+](https://www.php.net/) +## Prerequisites + +- PHP 8.0+ (PHP 8.2 recommended for Laravel) - [PECL](https://pecl.php.net/) -- [composer](https://getcomposer.org/) +- [Composer](https://getcomposer.org/) +- KloudMate workspace API key (used to authorize telemetry ingestion) + +## Example Application -**Step 2: Install PHP and setup the app** -**** -1\. Create a dice-rolling application +For demonstration, we'll use a simple Slim and Laravel application. You can adapt the same instructions for any other supported framework. +### 1. Create a Project Directory + + + ```bash mkdir && cd @@ -26,8 +32,22 @@ composer init \ --require slim/psr7:"^1" composer update ``` + + +```bash +composer create-project laravel/laravel my-laravel-app +cd my-laravel-app +``` + +Or use an existing Laravel application. + + -2\. Write the application code. Create an index.php file in the \ folder and add the following code. The following sample code simulates a dice rolling game that rolls a dice and returns a random number in the range of one to six: +### 2. Create the Application + + + +Create an `index.php` file in the `` folder and add the following code. The sample code simulates a dice rolling game that returns a random number from 1 to 6: ```php get('/rolldice', function (Request $request, Response $response) { $app->run(); ``` + + +If you created a new Laravel app, it already includes a default welcome route. You can also add a simple test route in `routes/web.php`: + +```php +json(['result' => random_int(1, 6)]); +}); ``` + + - 2\. Use PECL to build the OpenTelemetry PHP extension. +### 3. Run the Application -```txt -pecl install opentelemetry + + +```bash +php -S localhost:8080 ``` - The result of the above command - -```txt -Build process completed successfully -Installing '/usr/lib/php/20230831/opentelemetry.so' -install ok: channel://pecl.php.net/opentelemetry-1.1.0 -configuration option "php_ini" is not set to php.ini location -You should add "extension=opentelemetry.so" to php.ini +Verify that the application is running by visiting `localhost:8080/rolldice` in your browser. + + +```bash +php artisan serve ``` -3\. Enable the OpenTelemetry PHP extension. If the `Extension opentelemetry enabled in php.ini` message is returned in the previous step, skip this step. +Verify that the application is running by visiting `localhost:8000/rolldice` in your browser. + + -Add the following code to the `/etc/php//cli/php.ini` file: +## Step 3: Install the OpenTelemetry PHP Extension -```txt -[opentelemetry] -extension=opentelemetry.so +Zero-code instrumentation requires the `opentelemetry` PHP extension to intercept and instrument PHP function calls automatically. + +### Linux (Ubuntu/Debian) + +```bash +sudo apt-get install php-dev php-pear +sudo pecl install opentelemetry ``` -4\. Verify whether the OpenTelemetry PHP extension is built and enabled. +### macOS + +```bash +pecl install opentelemetry +``` -Method 1: +### Enable the Extension -`php -m | grep opentelemetry` +Add the following line to your `php.ini` file: -Expected output: +```ini +extension=opentelemetry.so +``` -`opentelemetry` +> **Tip:** Find your `php.ini` location by running `php --ini`. -5\. Add additional dependencies required for OpenTelemetry SDK for PHP to perform automatic instrumentation on the dice-rolling application. +### Verify Installation -```txt -pecl install grpc +```bash +php -m | grep opentelemetry ``` -The above command will run for an extended period of time. +You should see `opentelemetry` in the output. -After successful completion run the below command +## Step 4: Install OpenTelemetry Packages -```txt + + +```bash composer config allow-plugins.php-http/discovery false composer require \ open-telemetry/sdk \ @@ -112,26 +150,298 @@ composer require \ open-telemetry/opentelemetry-auto-slim ``` -6\. Set environment variables and run the app +You may also need to install the gRPC extension if not already present: + +```bash +pecl install grpc +``` + + +Run the following commands in your Laravel project root directory: + +```bash +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 -```txt -env OTEL_PHP_AUTOLOAD_ENABLED=true \ - OTEL_SERVICE_NAME=myapp \ - OTEL_TRACES_EXPORTER=otlp \ - OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \ - OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.kloudmate.com:4318 \ - OTEL_EXPORTER_OTLP_HEADERS="Authorization=" \ - OTEL_PROPAGATORS=baggage,tracecontext \ - php -S localhost:8080 +| 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 5: Configure Environment Variables + +Set the following environment variables to configure KloudMate OTLP endpoint and service metadata. + + + +```bash +export OTEL_PHP_AUTOLOAD_ENABLED=true +export OTEL_SERVICE_NAME=my-php-app +export OTEL_TRACES_EXPORTER=otlp +export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.kloudmate.com:4318 +export OTEL_EXPORTER_OTLP_HEADERS="Authorization=" +export OTEL_PROPAGATORS=baggage,tracecontext ``` -Replace ``with your API key +Replace `` with your KloudMate API key. + + +Add the following variables to your Laravel `.env` file: -*** +```ini +# ============================================ +# OpenTelemetry Configuration +# ============================================ - +# Enable auto-instrumentation (REQUIRED) +OTEL_PHP_AUTOLOAD_ENABLED=true -*Source URL for the example application:* [Getting Started with OpenTelemetry PHP](https://opentelemetry.io/docs/languages/php/getting-started/) +# 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=" +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 `` with your 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: + +```ini +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 6: Run Your Application with Auto-Instrumentation + + + +```bash +php -S localhost:8080 +``` + +Visit `localhost:8080/rolldice` in your browser. You should see spans on the Traces page in your KloudMate account. + + +```bash +php artisan serve +``` + +Visit `localhost:8000/rolldice` in your browser. You should see spans on the Traces page in your KloudMate account. + + + +## Step 7: Verify the Integration + +### 1. Confirm the PHP Extension is Active + + + +```bash +php -m | grep opentelemetry +``` + +Expected output: `opentelemetry` + + +```bash +php artisan tinker +``` + +Inside Tinker, run: + +```php +echo extension_loaded('opentelemetry') ? 'YES' : 'NO'; +``` + +Expected output: `YES` + + + +### 2. Generate Some Traffic + +Make requests to your application routes to generate telemetry data. + +### 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. + +You should see traces, spans, and metadata automatically captured from your app. + +## Step 8: Sending Telemetry to an OpenTelemetry Collector + +In most production deployments, it's beneficial to use an OpenTelemetry Collector. Follow these steps to configure and run a local collector. + +1. Create a file named `otel-collector-config.yaml` in the `/tmp/` directory and save the following configuration: + +```yaml +receivers: + otlp: + protocols: + grpc: + endpoint: 0.0.0.0:4317 + +exporters: + debug: + verbosity: detailed + + otlphttp: + endpoint: https://otel.kloudmate.com:4318 + headers: + Authorization: + +processors: + batch: + send_batch_size: 5000 + timeout: 10s + +service: + pipelines: + traces: + receivers: [otlp] + exporters: [debug, otlphttp] + processors: [batch] + + metrics: + receivers: [otlp] + exporters: [debug, otlphttp] + processors: [batch] + + logs: + receivers: [otlp] + exporters: [debug, otlphttp] + processors: [batch] +``` + +:::note +The `otlphttp` exporter in the config, along with the KloudMate API key as the `Authorization` header, will send the data from the collector to KloudMate. +::: + +2. Run the following Docker command to start the collector: + +```bash +docker run -p 4317:4317 \ + -v /tmp/otel-collector-config.yaml:/etc/otel-collector-config.yaml \ + otel/opentelemetry-collector:latest \ + --config=/etc/otel-collector-config.yaml +``` + +3. Update your application environment variables to point to the local collector: + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 +export OTEL_EXPORTER_OTLP_PROTOCOL=grpc +``` + +4. Run the application again. By default, it will export traces and metrics over OTLP/gRPC to the collector running on `localhost:4317`. + +## Optional: Fine-Tuning & Debugging + +### Disable Specific Instrumentations + +If you want to disable auto-instrumentation: + + + +```ini +OTEL_PHP_DISABLED_INSTRUMENTATIONS=slim +``` + + +```ini +OTEL_PHP_DISABLED_INSTRUMENTATIONS=laravel +``` + + + +### Switch to gRPC Protocol + +```ini +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: + +```ini +OTEL_LOG_LEVEL=debug +``` + +### Add Custom Resource Attributes + +```ini +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: + +```ini +OTEL_PHP_AUTOLOAD_ENABLED=true +OTEL_SERVICE_NAME=my-app +OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.kloudmate.com:4318 +OTEL_EXPORTER_OTLP_HEADERS="Authorization=" +``` + +Replace `` with your KloudMate API key. + +## Summary + +| Step | Action | +|------|--------| +| 1 | Install the `opentelemetry` PHP extension via `pecl` | +| 2 | Install framework-specific auto-instrumentation packages via Composer | +| 3 | Add `OTEL_*` environment variables to your configuration | +| 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. + +--- + +*Source URL for the example application:* [Getting Started with OpenTelemetry PHP](https://opentelemetry.io/docs/languages/php/getting-started/) +For more details and advanced configurations, refer to the official OpenTelemetry documentation: +- [Zero-Code Instrumentation for PHP](https://opentelemetry.io/docs/zero-code/php/) +- [OpenTelemetry PHP Documentation](https://opentelemetry.io/docs/languages/php/) From 6394b76b9fd2ea8ae6d9d061e01db0d14f1a120e Mon Sep 17 00:00:00 2001 From: Ansh Garhewal Date: Fri, 5 Jun 2026 20:47:38 +0530 Subject: [PATCH 2/3] php apm to add laravel docs fix --- .../auto-instrumentation/php.mdx | 235 +----------------- 1 file changed, 11 insertions(+), 224 deletions(-) diff --git a/src/content/docs/docs/apm-and-tracing/auto-instrumentation/php.mdx b/src/content/docs/docs/apm-and-tracing/auto-instrumentation/php.mdx index ee29901d..898b66d6 100644 --- a/src/content/docs/docs/apm-and-tracing/auto-instrumentation/php.mdx +++ b/src/content/docs/docs/apm-and-tracing/auto-instrumentation/php.mdx @@ -21,235 +21,22 @@ export OTEL_SERVICE_NAME="your-php-service-name" *Replace `YOUR_API_KEY` with your actual KloudMate API key.* -## Setup Instructions +## Framework Guides -For the actual installation and usage instructions of the OpenTelemetry PHP auto-instrumentation extension, please refer to the official OpenTelemetry documentation. +For detailed, step-by-step instructions on instrumenting your PHP application, choose your framework below: -[**View Official OpenTelemetry PHP Zero-code Instrumentation Docs →**](https://opentelemetry.io/docs/zero-code/php/) +- [Instrument a PHP App — Slim & Laravel](../../../../guides/opentelemetry/php/) -## Laravel +More framework-specific guides (Symfony, WordPress, etc.) will be added soon. -This section provides step-by-step instructions to integrate **OpenTelemetry zero-code instrumentation** into an existing Laravel application and route the data to KloudMate. +## Official Documentation -### Prerequisites +For the most up-to-date SDK instructions, advanced configurations, and a full list of supported auto-instrumentation packages, refer to the official OpenTelemetry documentation: -- PHP 8.0+ (PHP 8.2 recommended) -- Composer installed -- An existing Laravel application -- A running KloudMate Agent or OTLP-compatible backend +- [**OpenTelemetry PHP Zero-code Instrumentation Docs**](https://opentelemetry.io/docs/zero-code/php/) +- [OpenTelemetry PHP Documentation](https://opentelemetry.io/docs/languages/php/) +- [PHP Instrumentation Repository](https://github.com/open-telemetry/opentelemetry-php) -### Step 1: Install the OpenTelemetry PHP Extension +## Manual Instrumentation -Zero-code instrumentation requires the `opentelemetry` PHP extension to intercept and instrument PHP function calls automatically. - -#### Linux (Ubuntu/Debian) - -```bash -sudo apt-get install php-dev php-pear -sudo pecl install opentelemetry -``` - -#### macOS - -```bash -pecl install opentelemetry -``` - -#### Enable the Extension - -Add the following line to your `php.ini` file: - -```ini -extension=opentelemetry.so -``` - -> **Tip:** Find your `php.ini` location by running `php --ini`. - -#### Verify Installation - -```bash -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: - -```bash -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: - -```ini -# ============================================ -# 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: - -```ini -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 - -```bash -php artisan tinker -``` - -Inside Tinker, run: - -```php -echo extension_loaded('opentelemetry') ? 'YES' : 'NO'; -``` - -Expected output: `YES` - -#### 2. Generate Some Traffic - -Make a request to your application: - -```bash -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: - -```ini -OTEL_PHP_DISABLED_INSTRUMENTATIONS=laravel -``` - -#### Switch to gRPC Protocol - -```ini -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: - -```ini -OTEL_LOG_LEVEL=debug -``` - -#### Add Custom Resource Attributes - -```ini -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: - -```ini -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. +If you need custom spans, metrics, or logs beyond what auto-instrumentation provides, refer to the [PHP Manual Instrumentation](../manual-instrumentation/php/) docs. From 19078472775703ce777762ef02a7075c5b95f92e Mon Sep 17 00:00:00 2001 From: Ansh Garhewal Date: Fri, 5 Jun 2026 20:50:42 +0530 Subject: [PATCH 3/3] php apm to add laravel docs fix --- .../auto-instrumentation/php.mdx | 239 ++++++++++++- src/content/docs/guides/opentelemetry/php.mdx | 318 ++++++++++++++++++ 2 files changed, 546 insertions(+), 11 deletions(-) diff --git a/src/content/docs/docs/apm-and-tracing/auto-instrumentation/php.mdx b/src/content/docs/docs/apm-and-tracing/auto-instrumentation/php.mdx index 898b66d6..43ba9e99 100644 --- a/src/content/docs/docs/apm-and-tracing/auto-instrumentation/php.mdx +++ b/src/content/docs/docs/apm-and-tracing/auto-instrumentation/php.mdx @@ -7,6 +7,10 @@ sidebar: 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](../../../../guides/opentelemetry/php/) 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. @@ -21,22 +25,235 @@ export OTEL_SERVICE_NAME="your-php-service-name" *Replace `YOUR_API_KEY` with your actual KloudMate API key.* -## Framework Guides +## 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 →**](https://opentelemetry.io/docs/zero-code/php/) + +## 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) + +```bash +sudo apt-get install php-dev php-pear +sudo pecl install opentelemetry +``` + +#### macOS + +```bash +pecl install opentelemetry +``` + +#### Enable the Extension + +Add the following line to your `php.ini` file: + +```ini +extension=opentelemetry.so +``` + +> **Tip:** Find your `php.ini` location by running `php --ini`. + +#### Verify Installation + +```bash +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: + +```bash +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: + +```ini +# ============================================ +# 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: + +```ini +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 -For detailed, step-by-step instructions on instrumenting your PHP application, choose your framework below: +- No manual span creation +- No middleware additions +- No controller modifications +- No service provider registration +- No `use` statements or imports -- [Instrument a PHP App — Slim & Laravel](../../../../guides/opentelemetry/php/) +### Step 5: Verify the Integration -More framework-specific guides (Symfony, WordPress, etc.) will be added soon. +#### 1. Confirm the PHP Extension is Active -## Official Documentation +```bash +php artisan tinker +``` + +Inside Tinker, run: + +```php +echo extension_loaded('opentelemetry') ? 'YES' : 'NO'; +``` + +Expected output: `YES` + +#### 2. Generate Some Traffic + +Make a request to your application: + +```bash +curl http://localhost:8000/ +``` -For the most up-to-date SDK instructions, advanced configurations, and a full list of supported auto-instrumentation packages, refer to the official OpenTelemetry documentation: +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: + +```ini +OTEL_PHP_DISABLED_INSTRUMENTATIONS=laravel +``` + +#### Switch to gRPC Protocol + +```ini +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: + +```ini +OTEL_LOG_LEVEL=debug +``` + +#### Add Custom Resource Attributes + +```ini +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: + +```ini +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" +``` -- [**OpenTelemetry PHP Zero-code Instrumentation Docs**](https://opentelemetry.io/docs/zero-code/php/) -- [OpenTelemetry PHP Documentation](https://opentelemetry.io/docs/languages/php/) -- [PHP Instrumentation Repository](https://github.com/open-telemetry/opentelemetry-php) +### Summary -## Manual Instrumentation +| 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 | -If you need custom spans, metrics, or logs beyond what auto-instrumentation provides, refer to the [PHP Manual Instrumentation](../manual-instrumentation/php/) docs. +That's it! Zero-code instrumentation means **zero code changes** in your application. diff --git a/src/content/docs/guides/opentelemetry/php.mdx b/src/content/docs/guides/opentelemetry/php.mdx index 36f5992b..2e50057e 100644 --- a/src/content/docs/guides/opentelemetry/php.mdx +++ b/src/content/docs/guides/opentelemetry/php.mdx @@ -439,6 +439,324 @@ That's it! Zero-code instrumentation means **zero code changes** in your applica --- +## Laravel + +This section provides a dedicated, step-by-step walkthrough for instrumenting a **Laravel** application with OpenTelemetry zero-code instrumentation and sending data to KloudMate. + +### Prerequisites + +- PHP 8.0+ (PHP 8.2 recommended) +- [Composer](https://getcomposer.org/) +- An existing Laravel application +- KloudMate workspace API key + +### Step 1: Create or Use an Existing Laravel App + +If you don't have an existing app, create one: + +```bash +composer create-project laravel/laravel my-laravel-app +cd my-laravel-app +``` + +Add a simple test route in `routes/web.php` to generate traffic later: + +```php +json(['result' => random_int(1, 6)]); +}); +``` + +### Step 2: Install the OpenTelemetry PHP Extension + +Zero-code instrumentation requires the `opentelemetry` PHP extension. + +#### Linux (Ubuntu/Debian) + +```bash +sudo apt-get install php-dev php-pear +sudo pecl install opentelemetry +``` + +#### macOS + +```bash +pecl install opentelemetry +``` + +#### Enable the Extension + +Add the following line to your `php.ini` file: + +```ini +extension=opentelemetry.so +``` + +> **Tip:** Find your `php.ini` location by running `php --ini`. + +#### Verify Installation + +```bash +php -m | grep opentelemetry +``` + +You should see `opentelemetry` in the output. + +### Step 3: Install OpenTelemetry Packages via Composer + +Run the following commands in your Laravel project root directory: + +```bash +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 4: Configure Environment Variables + +Add the following variables to your Laravel `.env` file: + +```ini +# ============================================ +# 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=" +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 `` with your 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: + +```ini +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 5: 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 6: Run the Application + +```bash +php artisan serve +``` + +Visit `localhost:8000/rolldice` in your browser. You should see spans on the Traces page in your KloudMate account. + +### Step 7: Verify the Integration + +#### 1. Confirm the PHP Extension is Active + +```bash +php artisan tinker +``` + +Inside Tinker, run: + +```php +echo extension_loaded('opentelemetry') ? 'YES' : 'NO'; +``` + +Expected output: `YES` + +#### 2. Generate Some Traffic + +Make requests to your application routes to generate telemetry data. + +#### 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. + +You should see traces, spans, and metadata automatically captured from your Laravel app. + +### Step 8: Sending Telemetry to an OpenTelemetry Collector + +In most production deployments, it's beneficial to use an OpenTelemetry Collector. Follow these steps to configure and run a local collector. + +1. Create a file named `otel-collector-config.yaml` in the `/tmp/` directory and save the following configuration: + +```yaml +receivers: + otlp: + protocols: + grpc: + endpoint: 0.0.0.0:4317 + +exporters: + debug: + verbosity: detailed + + otlphttp: + endpoint: https://otel.kloudmate.com:4318 + headers: + Authorization: + +processors: + batch: + send_batch_size: 5000 + timeout: 10s + +service: + pipelines: + traces: + receivers: [otlp] + exporters: [debug, otlphttp] + processors: [batch] + + metrics: + receivers: [otlp] + exporters: [debug, otlphttp] + processors: [batch] + + logs: + receivers: [otlp] + exporters: [debug, otlphttp] + processors: [batch] +``` + +:::note +The `otlphttp` exporter in the config, along with the KloudMate API key as the `Authorization` header, will send the data from the collector to KloudMate. +::: + +2. Run the following Docker command to start the collector: + +```bash +docker run -p 4317:4317 \ + -v /tmp/otel-collector-config.yaml:/etc/otel-collector-config.yaml \ + otel/opentelemetry-collector:latest \ + --config=/etc/otel-collector-config.yaml +``` + +3. Update your application environment variables to point to the local collector: + +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 +export OTEL_EXPORTER_OTLP_PROTOCOL=grpc +``` + +4. Run the application again. By default, it will export traces and metrics over OTLP/gRPC to the collector running on `localhost:4317`. + +### Optional: Fine-Tuning & Debugging + +#### Disable Specific Instrumentations + +If you want to disable Laravel auto-instrumentation: + +```ini +OTEL_PHP_DISABLED_INSTRUMENTATIONS=laravel +``` + +#### Switch to gRPC Protocol + +```ini +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: + +```ini +OTEL_LOG_LEVEL=debug +``` + +#### Add Custom Resource Attributes + +```ini +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: + +```ini +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=" +``` + +Replace `` with your KloudMate 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 | + +--- + *Source URL for the example application:* [Getting Started with OpenTelemetry PHP](https://opentelemetry.io/docs/languages/php/getting-started/) For more details and advanced configurations, refer to the official OpenTelemetry documentation: