OpenTelemetry
debt(d7/e5/b5/t3)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints indicate automated detection is 'no' and the tool listed is opentelemetry itself (not a linter/SAST). Misuse patterns — like using vendor SDKs directly, skipping auto-instrumentation, or sending telemetry directly to a backend — won't surface until code review or when observability gaps are noticed in production. No default linter catches these omissions.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix describes installing the SDK and contrib packages, configuring an OTLP exporter, deploying an OTel Collector, wiring auto-instrumentation, and adding custom spans. This is not a one-liner; it's a meaningful multi-file setup. Migrating away from a vendor SDK also touches every instrumentation call site, requiring a coordinated effort across the codebase.
Closest to 'persistent productivity tax' (b5). The applies_to scope covers web, cli, and queue-worker contexts — the full application surface. Every future developer adding new services, routes, or background jobs must understand and follow OTel patterns (span creation, context propagation, exporter config). However, once wired correctly, the abstraction largely stays out of daily work, so it doesn't fully reach the 'gravitational pull' of b7.
Closest to 'minor surprise (one edge case)' (t3). The misconception is well-documented and fairly intuitive once explained: developers assume they must pick a backend before instrumenting, but OTel decouples the two. This is a conceptual ordering mistake rather than a deep behavioral gotcha, and the correct mental model is easy to internalize. Common mistakes (skipping auto-instrumentation, sending directly to backend) are practical setup errors, not conceptual traps that contradict prior knowledge.
TL;DR
Explanation
OpenTelemetry: merged OpenCensus + OpenTracing. Three signals: Traces, Metrics, Logs. SDK: instrument code once, choose backend later. Collector: OTel Collector receives, processes, and exports telemetry — runs as a sidecar or agent. PHP: open-telemetry/opentelemetry-php, auto-instrumentation for HTTP/DB/Redis. Key concepts: Resource (service metadata), Exporter (sends to backend), Propagator (trace context across processes), Sampler (sampling decisions). OTLP protocol: the standard wire format. Auto-instrumentation: instrument frameworks without code changes (Laravel, Symfony contrib packages).
Common Misconception
Why It Matters
Common Mistakes
- Using vendor SDK directly — locks you in.
- Not installing auto-instrumentation packages — misses framework/HTTP/DB spans.
- Sending telemetry directly to backend — use OTel Collector for buffering and processing.
Code Examples
// Vendor-locked instrumentation:
$dd = new DatadogTracer();
$span = $dd->startSpan('query'); // Only works with Datadog// OpenTelemetry — vendor neutral:
use OpenTelemetry\API\Trace\TracerProviderInterface;
$span = $tracer->spanBuilder('db.query')
->setAttribute('db.statement', $sql)
->startSpan();
try { $result = $pdo->query($sql); }
finally { $span->end(); }
// Export to Jaeger today, Honeycomb tomorrow — no code change