APM — Application Performance Monitoring
debt(d7/e5/b5/t5)
Closest to 'only careful code review or runtime testing' (d7). The absence of APM is not something a compiler or linter catches. The listed tools (Datadog, New Relic, Blackfire) are the APM agents themselves, not detection tools for misuse. Whether APM is misconfigured (e.g., no sampling, not deployed to production) is only discoverable through manual review of infrastructure config or by noticing performance issues in production. detection_hints.automated is 'no'.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix says 'Install APM agent, configure sampling rate, set up dashboards, review weekly for N+1 patterns.' This is not a one-line fix — it involves installing a PHP extension, configuring it across environments, setting up dashboards, and establishing ongoing review processes. It touches deployment config, php.ini/docker configs, and potentially application code for custom instrumentation. Not architectural rework, but a meaningful cross-file operational effort.
Closest to 'persistent productivity tax' (b5). APM applies to both web and CLI contexts and once installed becomes a persistent operational concern — sampling rates need tuning, dashboards need maintenance, agents need version updates, and the 5-10% overhead (per common_mistakes) must be managed. It's not architecture-defining (b7+) but it does impose an ongoing tax across multiple work streams: deployment, monitoring, performance review cycles.
Closest to 'notable trap (a documented gotcha most devs eventually learn)' (t5). The misconception field states 'APM replaces logging and metrics' — this is a well-documented but common trap where developers believe APM is a complete observability solution and neglect logs and metrics. Additionally, common_mistakes include running without sampling (100% trace rate causing expensive overhead) and only using APM in dev but not production. These are traps that competent developers do fall into but eventually learn about.
TL;DR
Explanation
APM = auto-instrumentation + profiling + transaction tracing in one product. Unlike OpenTelemetry (code instrumentation), APM agents install at the PHP extension level and instrument automatically. Capabilities: distributed traces, code-level profiling (which PHP function is slow?), DB query analysis (N+1 detection), external service latency, error tracking. PHP APM: Datadog APM (ddtrace extension), New Relic (newrelic extension), Blackfire (profiler, not APM), Elastic APM (PHP agent). SaaS vs self-hosted: Datadog/New Relic are SaaS (expensive), Elastic/Jaeger are self-hosted. APM complements OpenTelemetry — many APMs now export OTLP.
Common Misconception
Why It Matters
Common Mistakes
- No APM in production — only monitoring in dev.
- High APM overhead without sampling — some APMs add 5-10% overhead.
- Not configuring APM sampling — 100% trace rate is expensive.
Code Examples
// Manually timing every operation:
$start = microtime(true);
$result = $pdo->query($sql);
$duration = microtime(true) - $start;
Log::info('Query time', ['ms' => $duration * 1000]);// Datadog APM — auto-instruments PDO:
// Install: composer require datadog/dd-trace-php
// PHP ext: dd-trace.so
// All PDO queries automatically traced with query, duration, error
// Dashboard shows slow queries, N+1 patterns, error traces
// Zero code changes required