Open Telemetry Operations Php Laravel Package

Getting Started

Before writing a line of code, confirm three things: PHP 8.1+, open-telemetry/sdk ^1.x, and a GCP project with the Cloud Trace API and Cloud Logging API enabled plus Application Default Credentials available to the process.

composer require affordablemobiles/open-telemetry-operations-php

Where to look first:

1. The README's usage snippet — this package predates Laravel auto-discovery and ships no service provider, so the README is the only wiring guide.
2. src/ for the span exporter (a SpanExporterInterface implementation, typically *CloudTraceExporter), the Monolog handler/formatter for Cloud Logging, and any trace-context propagator.
3. composer.json for the exact open-telemetry/* version constraints — mismatches with your app's SDK version are the most common install failure.

First use case: don't start with middleware. Write a throwaway Artisan command that builds a TracerProvider with a SimpleSpanProcessor and the package exporter, creates one span, ends it, and calls $provider->shutdown(). Run it, then check the Cloud Trace console. This isolates auth, project-ID, and payload-shape problems from HTTP lifecycle problems before you add either.

Implementation Patterns

• Dedicated service provider. Bind TracerProviderInterface and TracerInterface as singletons in a TelemetryServiceProvider registered in config/app.php (or bootstrap/providers.php on Laravel 11). Use BatchSpanProcessor in production and SimpleSpanProcessor locally so you see spans immediately while debugging.
• Request middleware. Start a server span at the top of the global stack, extract inbound context, set http.request.method, url.path, http.response.status_code, and end the span in a finally block. Register it before TrimStrings/SubstituteBindings so the span covers the full request.
• Log correlation. Route Monolog through the package's Cloud Logging handler so every record carries logging.googleapis.com/trace, logging.googleapis.com/spanId, and logging.googleapis.com/trace_sampled, pulled from the currently active span. This is what makes the "View Trace" link work from a log line in the GCP console.
• Queue jobs. Capture trace context at dispatch time and re-attach it on the worker; otherwise job spans start orphaned traces and the request → job link is lost. A small JobDispatched/JobProcessing listener pair is usually enough.
• Console and scheduler. Wrap Illuminate\Console\Events\CommandStarting/CommandFinished to create a root span per command, which covers scheduled tasks with no extra effort.
• Sampling consistency. Set the sampler once at the SDK level (ParentBased(TraceIdRatioBased)) and let both the exporter and the log formatter read the same trace_sampled flag. Divergent sampling produces logs that point at traces that were never exported.
• Flush on terminate. Register $provider->shutdown() (or forceFlush()) in a Terminating listener, and again in the Octane worker's terminating hook. Without it, BatchSpanProcessor drops everything in its queue on every request.

Gotchas and Tips

• No auto-discovery. Unlike first-party Laravel packages, nothing registers itself. Budget real time for wiring; don't assume php artisan vendor:publish will do anything.
• Lost spans in Octane. The batch processor holds spans in memory per worker. If you never flush, or flush in the wrong lifecycle hook, long-running workers silently lose traces. This is the single biggest failure mode.
• Context leakage under Octane. Singletons survive across requests. Reset scope and baggage at the start of each request (Scope::detach() plus clearing baggage), or span trees will nest under a previous request's parent.
• Local dev auth. ADC is usually absent on a laptop. Gate the exporter behind an env flag and fall back to a no-op or console exporter so php artisan serve doesn't scream credential errors on every request.
• Explicit project ID. ADC-derived project detection is unreliable in multi-project orgs; set the project from GOOGLE_CLOUD_PROJECT rather than relying on the default.
• Log/trace link format is strict. logging.googleapis.com/trace must be projects/{project}/traces/{32-hex-id}. A truncated or mismatched ID breaks the console jump with no error.
• Header mismatch. GCP load balancers and Cloud Run emit X-Cloud-Trace-Context (TRACE_ID/SPAN_ID;o=1), not W3C traceparent. If you only parse the W3C header, every inbound production request starts a new trace.
• Cardinality. Don't put raw URLs, user IDs, or SQL text in span names or attributes. Cloud Trace groups and bills by span name; high-cardinality names make the console unusable.
• Monolog major version. Handler constructor signatures differ between Monolog 2 and 3 (the $processors argument position). Pin your Monolog major and verify the handler instantiates before deploying.
• Package maturity. One star, zero dependents, a single release from April 2024. Pin the exact version, wrap the exporter behind your own interface, and keep open-telemetry/exporter-otlp pointed at Google's OTLP endpoint as a swap-out plan if the package stalls.
• Testing. Never exercise the real exporter in tests. Use the SDK's InMemorySpanExporter and assert against finished spans.
• Exceptions in context. OTel's recordException() needs a Throwable; PSR-3 context cannot hold objects. Flatten exception data (class, message, code) before handing it to the logging handler or it will throw.