Getting Started

Minimal Setup

Install the package:
```
composer require open-telemetry/sdk
```

Enable autoloading (recommended for most projects): Add to your .env:

OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_SERVICE_NAME="your-app-name"
OTEL_EXPORTER=otlp
OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"

First use case:

require 'vendor/autoload.php';

// Tracing
$tracer = \OpenTelemetry\API\Globals::tracerProvider()->getTracer('your-service');
$span = $tracer->spanBuilder('example-span')->startSpan();
$span->end();

// Metrics
$meter = \OpenTelemetry\API\Globals::meterProvider()->getMeter('your-service');
$counter = $meter->createCounter('example-counter');
$counter->add(1, ['key' => 'value']);

Key Entry Points

Tracing: \OpenTelemetry\API\Globals::tracerProvider()
Metrics: \OpenTelemetry\API\Globals::meterProvider()
Logs: \OpenTelemetry\API\Globals::loggerProvider()
SDK Builder: \OpenTelemetry\SDK\Telemetry\Sdk

Where to Look First

Implementation Patterns

Core Workflows

1. Tracing Workflow

// Create a tracer
$tracer = \OpenTelemetry\API\Globals::tracerProvider()->getTracer('your-service');

// Start a span
$span = $tracer->spanBuilder('operation-name')
    ->setAttribute('key', 'value')
    ->startSpan();

// Add events
$span->addEvent('event-name', ['details' => 'value']);

// End the span
$span->end();

2. Metrics Workflow

// Create a meter
$meter = \OpenTelemetry\API\Globals::meterProvider()->getMeter('your-service');

// Counter
$counter = $meter->createCounter('requests');
$counter->add(1, ['method' => 'GET']);

// Histogram
$histogram = $meter->createHistogram('response_time');
$histogram->record(150, ['endpoint' => '/api']);

// Gauge
$gauge = $meter->createGauge('active_connections');
$gauge->record(42, ['type' => 'database']);

3. Logging Workflow

$logger = \OpenTelemetry\API\Globals::loggerProvider()->getLogger('your-service');
$logger->emit([
    'body' => 'Log message',
    'severityText' => 'INFO',
    'severityNumber' => \OpenTelemetry\SemConv\Logs\SeverityNumber::INFO,
    'attributes' => ['key' => 'value']
]);

Integration Patterns

1. HTTP Client Integration (Guzzle Example)

use OpenTelemetry\Instrumentation\Guzzle\GuzzleInstrumentation;

$client = new \GuzzleHttp\Client();
$instrumentation = new GuzzleInstrumentation();
$instrumentation->instrument($client);

2. Middleware for Framework Integration (Laravel Example)

// app/Providers/AppServiceProvider.php
public function boot()
{
    $this->app->makeWith(\OpenTelemetry\Instrumentation\Laravel\OpenTelemetryServiceProvider::class);
}

3. Custom Span Processor

use OpenTelemetry\SDK\Trace\SpanProcessor\SpanProcessorInterface;

class CustomSpanProcessor implements SpanProcessorInterface
{
    public function onStart(\OpenTelemetry\API\Trace\Span $span): void
    {
        // Custom logic on span start
    }

    public function onEnd(\OpenTelemetry\API\Trace\Span $span): void
    {
        // Custom logic on span end
    }
}

// Register with SDK builder
$sdk = (new \OpenTelemetry\SDK\Telemetry\Sdk())
    ->setSpanProcessor(new CustomSpanProcessor());

4. Configuration via Environment Variables

# Tracing
OTEL_TRACES_SAMPLER=always_on
OTEL_TRACES_EXPORTER=otlp
OTEL_TRACES_EXPORTER_OTLP_ENDPOINT=http://collector:4318

# Metrics
OTEL_METRICS_EXPORTER=otlp
OTEL_METRICS_EXPORTER_OTLP_ENDPOINT=http://collector:4317

# Logging
OTEL_LOGS_EXPORTER=otlp
OTEL_LOGS_EXPORTER_OTLP_ENDPOINT=http://collector:4317

5. SDK Builder Pattern

$sdk = (new \OpenTelemetry\SDK\Telemetry\Sdk())
    ->setTracerProvider(
        (new \OpenTelemetry\SDK\Trace\TracerProvider())
            ->addSpanProcessor(new \OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor(
                new \OpenTelemetry\SDK\Trace\Export\BatchSpanProcessor(
                    new \OpenTelemetry\SDK\Trace\Export\ConsoleSpanExporter()
                )
            ))
    )
    ->setMeterProvider(
        (new \OpenTelemetry\SDK\Metrics\MeterProvider())
            ->registerObserver(new \OpenTelemetry\SDK\Metrics\Export\PeriodicExportingMetricObserver(
                new \OpenTelemetry\SDK\Metrics\Export\ConsoleMetricExporter(),
                5000 // 5 seconds
            ))
    );

\OpenTelemetry\API\Globals::setTracerProvider($sdk->getTracerProvider());
\OpenTelemetry\API\Globals::setMeterProvider($sdk->getMeterProvider());

Common Use Cases

1. Distributed Tracing

// Extract context from incoming request
$context = \OpenTelemetry\API\Trace\propagation\TraceContextPropagator::getInstance()
    ->extract(
        \OpenTelemetry\API\Common\Instrumentation\GlobalInstrumentation::getContext(),
        $_SERVER
    );

// Inject context into outgoing request
$carrier = [];
\OpenTelemetry\API\Trace\propagation\TraceContextPropagator::getInstance()
    ->inject($context, $carrier);

2. Auto-Instrumentation

// Enable auto-instrumentation for HTTP clients
\OpenTelemetry\Instrumentation\AutoInstrumentation::registerAutoInstrumentations([
    \OpenTelemetry\Instrumentation\Guzzle\GuzzleInstrumentation::class,
    \OpenTelemetry\Instrumentation\Symfony\HttpClient\SymfonyHttpClientInstrumentation::class,
]);

3. Resource Detection

$sdk = (new \OpenTelemetry\SDK\Telemetry\Sdk())
    ->setResource(
        \OpenTelemetry\SDK\Resource\ResourceInfo::createDefault()
            ->merge(
                \OpenTelemetry\SDK\Resource\ResourceDetector::detect()
            )
    );

Gotchas and Tips

Common Pitfalls

1. Autoloading Issues

Problem: Autoloading fails silently if environment variables are missing.
Solution: Always check OTEL_PHP_AUTOLOAD_ENABLED and required variables.
Debug: Use OTEL_PHP_AUTOLOAD_DEBUG=true to see autoloading attempts.

2. Span Context Propagation

Problem: Context not properly propagated between services.

Solution: Ensure all services use the same propagator:

\OpenTelemetry\API\Trace\propagation\TraceContextPropagator::getInstance();

Tip: Use OTEL_PROPAGATION_FORMAT=tracecontext for W3C Trace Context.

3. Sampling Configuration

Problem: Too many spans being collected.

Solution: Configure sampling properly:

OTEL_TRACES_SAMPLER=traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1 # Sample 10% of traces

Tip: Use AlwaysRecordSampler for development:

$sampler = new \OpenTelemetry\SDK\Trace\Sampling\AlwaysRecordSampler();

4. Metric Observer Configuration

Problem: Metrics not being exported.

Solution: Ensure observer is properly registered:

$meterProvider = new \OpenTelemetry\SDK\Metrics\MeterProvider();
$meterProvider->registerObserver(
    new \OpenTelemetry\SDK\Metrics\Export\PeriodicExportingMetricObserver(
        new \OpenTelemetry\SDK\

Sdk Laravel Package