Add documentation for OTEL_EXPORTER_OTLP_HEADERS

Co-authored-by: overtrue <[email protected]>

Author: Copilot

README.md

@@ -66,6 +66,9 @@ OTEL_TRACES_EXPORTER=console
 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
 OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
 
+# Optional: Add custom headers to OTLP exporter (e.g., for authentication)
+# OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-api-key,authorization=Bearer your-token"
+
 # Context propagation
 OTEL_PROPAGATORS=tracecontext,baggage
 ```
@@ -317,11 +320,58 @@ protected $middlewareGroups = [
 | `OTEL_TRACES_EXPORTER` | Trace exporter type | `otlp` | `console`, `otlp` |
 | `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP endpoint URL | `http://localhost:4318` | `https://api.honeycomb.io` |
 | `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP protocol | `http/protobuf` | `http/protobuf`, `grpc` |
+| `OTEL_EXPORTER_OTLP_HEADERS` | Custom headers for OTLP exporter (comma-separated) | `null` | `x-api-key=key123,authorization=Bearer token` |
 | `OTEL_PROPAGATORS` | Context propagators | `tracecontext,baggage` | `tracecontext,baggage,b3` |
 | `OTEL_TRACES_SAMPLER` | Sampling strategy | `parentbased_always_on` | `always_on`, `traceidratio` |
 | `OTEL_TRACES_SAMPLER_ARG` | Sampler argument | `null` | `0.1` |
 | `OTEL_RESOURCE_ATTRIBUTES` | Resource attributes | `null` | `key1=value1,key2=value2` |
 
+### Authentication with OTLP Exporters
+
+Many OpenTelemetry collectors and backends require authentication. You can add custom headers (like API keys or bearer tokens) to your OTLP exporter using the `OTEL_EXPORTER_OTLP_HEADERS` environment variable.
+
+#### Examples:
+
+**API Key Authentication:**
+```env
+OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-api-key-here"
+```
+
+**Bearer Token Authentication:**
+```env
+OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer your-token-here"
+```
+
+**Multiple Headers:**
+```env
+OTEL_EXPORTER_OTLP_HEADERS="x-api-key=key123,x-tenant-id=tenant456"
+```
+
+**Common SaaS Providers:**
+
+For **Honeycomb**:
+```env
+OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io
+OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=your-api-key"
+```
+
+For **New Relic**:
+```env
+OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.nr-data.net:4318
+OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+OTEL_EXPORTER_OTLP_HEADERS="api-key=your-new-relic-license-key"
+```
+
+For **Grafana Cloud**:
+```env
+OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp-gateway-prod-us-central-0.grafana.net/otlp
+OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+OTEL_EXPORTER_OTLP_HEADERS="authorization=Basic your-base64-encoded-credentials"
+```
+
+> **Note**: The `OTEL_EXPORTER_OTLP_HEADERS` variable accepts comma-separated `key=value` pairs. Make sure to properly escape values if they contain special characters.
+
 ## Testing
 
 ```bash

config/otel.php

@@ -14,6 +14,29 @@
      */
     'tracer_name' => env('OTEL_TRACER_NAME', 'overtrue.laravel-open-telemetry'),
 
+    /**
+     * OpenTelemetry SDK Configuration
+     *
+     * This package uses standard OpenTelemetry environment variables for configuration.
+     * These are automatically picked up by the OpenTelemetry PHP SDK:
+     *
+     * Core Variables:
+     * - OTEL_SERVICE_NAME: Name of your service (e.g., 'my-laravel-app')
+     * - OTEL_SERVICE_VERSION: Version of your service (e.g., '1.0.0')
+     * - OTEL_TRACES_EXPORTER: Trace exporter type ('console', 'otlp', etc.)
+     * - OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint URL (e.g., 'http://localhost:4318')
+     * - OTEL_EXPORTER_OTLP_PROTOCOL: OTLP protocol ('http/protobuf' or 'grpc')
+     * - OTEL_EXPORTER_OTLP_HEADERS: Custom headers for authentication (e.g., 'x-api-key=key123')
+     *   Format: comma-separated key=value pairs
+     *   Example: "x-api-key=abc123,authorization=Bearer token456"
+     * - OTEL_PROPAGATORS: Context propagators (e.g., 'tracecontext,baggage')
+     * - OTEL_TRACES_SAMPLER: Sampling strategy ('always_on', 'traceidratio', etc.)
+     * - OTEL_TRACES_SAMPLER_ARG: Sampler argument (e.g., '0.1' for 10% sampling)
+     * - OTEL_RESOURCE_ATTRIBUTES: Additional resource attributes (e.g., 'key1=value1,key2=value2')
+     *
+     * For more information, see: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/
+     */
+
     /**
      * Middleware Configuration
      */

examples/middleware_example.php

@@ -21,6 +21,9 @@
 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
 OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
 
+# Optional: Add authentication headers to OTLP exporter
+# OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-api-key"
+
 # Context propagation
 OTEL_PROPAGATORS=tracecontext,baggage
 
@@ -175,6 +178,10 @@ public function handle($request, Closure $next)
 OTEL_TRACES_EXPORTER=otlp
 OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.company.com:4318
 OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+
+# Add authentication headers for production collectors
+OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer production-token-here"
+
 OTEL_PROPAGATORS=tracecontext,baggage
 
 # Sampling configuration
@@ -239,3 +246,43 @@ public function createUser(array $userData)
     ],
 ],
 */
+
+// 11. Authenticating with OTLP Collectors
+/*
+Many OpenTelemetry backends require authentication headers. You can configure these
+using the OTEL_EXPORTER_OTLP_HEADERS environment variable:
+
+Format: comma-separated key=value pairs
+Example: OTEL_EXPORTER_OTLP_HEADERS="x-api-key=abc123,authorization=Bearer token456"
+
+Common SaaS Provider Examples:
+
+# Honeycomb
+OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io
+OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=your-api-key"
+
+# New Relic
+OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.nr-data.net:4318
+OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+OTEL_EXPORTER_OTLP_HEADERS="api-key=your-new-relic-license-key"
+
+# Grafana Cloud
+OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp-gateway-prod-us-central-0.grafana.net/otlp
+OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+OTEL_EXPORTER_OTLP_HEADERS="authorization=Basic base64-encoded-credentials"
+
+# Custom Collector with Bearer Token
+OTEL_EXPORTER_OTLP_ENDPOINT=https://your-collector.example.com:4318
+OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer your-secret-token"
+
+# Multiple Headers
+OTEL_EXPORTER_OTLP_ENDPOINT=https://your-collector.example.com:4318
+OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+OTEL_EXPORTER_OTLP_HEADERS="x-api-key=key123,x-tenant-id=tenant456,authorization=Bearer token789"
+
+Note: The OTEL_EXPORTER_OTLP_HEADERS variable is automatically recognized by the
+OpenTelemetry PHP SDK and requires no additional configuration in this package.
+*/
+