WordPress performance monitoring with OpenTelemetry and tracing

Last month, I spent about three days chasing a race condition in a custom REST API endpoint that only surfaced under heavy load. The standard query_monitor plugin gave me a snapshot, but it didn't show me how the request interacted with our external microservices. That’s when I realized we needed a more robust approach to WordPress performance monitoring.

If you’re running high-traffic sites, you’ve likely hit the wall where error_log debugging just doesn't cut it. To get real insights, you need distributed tracing. By integrating OpenTelemetry into your plugin architecture, you can track the entire lifecycle of a request as it traverses your system.

Why REST API monitoring matters

Most of us treat WordPress as a monolith, but modern plugins often act as glue for external services. When you use WordPress Performance: Asynchronous Database Write-Queues for REST APIs, you’re already decoupling parts of your system. The problem is that once you decouple, you lose visibility. You need to know if a delay is happening in your PHP execution, your database query, or a downstream API call.

We initially tried wrapping our core logic in simple microtime() logs. It was a disaster. It cluttered our logs and didn't provide context for concurrent requests. We needed a structured way to pass trace headers through the WordPress Request Lifecycle: A Deep Dive into Core Execution, which is why we moved to OpenTelemetry.

Implementing OpenTelemetry in WordPress

To get started, don't try to instrument everything at once. Focus on the rest_pre_dispatch and rest_post_dispatch hooks. These allow you to start a span when a request hits your endpoint and close it when the response is ready.

You’ll need the OpenTelemetry PHP SDK. I suggest using Composer to pull it into your plugin directory:

Bash
composer require open-telemetry/sdk open-telemetry/api

Once installed, you can create a singleton class to manage your tracer. Here’s a basic implementation pattern:

PHP
use OpenTelemetry\Trace\TracerProvider;

class Plugin_Tracer {
    private static $tracer;

    public static function init() {
        #6A9955">// Initialize your OTLP exporter here
        #6A9955">// Point it to your collector(e.g., Grafana Tempo)
    }

    public static function start_span($name) {
        return self::$tracer->spanBuilder($name)->startSpan();
    }
}

Integrating with REST API endpoints

The magic happens when you hook into the REST API. By injecting a span into your endpoint handler, you can measure exactly how long your business logic takes compared to the overhead of WordPress core.

PHP
add_filter('rest_pre_dispatch', function($result, $server, $request) {
    $span = Plugin_Tracer::start_span('rest_api_endpoint_' . $request->get_route());
    $request->set_param('_otel_span', $span);
    return $result;
}, 10, 3);

When the request finishes, pull the span from the request object, add any relevant attributes (like user IDs or cache hits), and end it. If you're managing complex infrastructure, you can even export these traces to a platform like Tempo, which I covered in Kubernetes Observability: Implementing Distributed Tracing with Tempo.

Trade-offs and Lessons Learned

The biggest hurdle we faced was overhead. If you instrument every single function, your site will slow down due to the sheer volume of trace data being generated. We saw latency increase by about 40ms per request when we enabled full instrumentation.

My advice? Sample your traces. Don't trace 100% of requests in production. Start with 1% or 5% and increase it only when you're actively debugging a specific issue. Also, ensure your OTLP exporter is non-blocking. If your tracing backend goes down, you don't want it to take your entire WordPress site with it.

FAQ

Does OpenTelemetry replace Query Monitor? No. Query Monitor is excellent for local development and immediate debugging. OpenTelemetry is for production observability, helping you visualize how requests behave in a distributed system.

Will this break my site if the tracing collector is down? It shouldn't, provided you use an asynchronous exporter. If your PHP process waits for the collector to acknowledge every span, your REST API will hang. Always configure your SDK to fail open.

How do I handle sensitive data in traces? Be careful with attributes. Never pass raw user passwords or PII into span attributes. Use a middleware function to sanitize your trace data before it hits the exporter.

Wrapping up

Implementing REST API monitoring with OpenTelemetry isn't a quick fix, but it's a game-changer for production stability. It moves you from "guessing why it's slow" to "seeing exactly where it's slow." I'm still experimenting with how to best correlate these traces with our database logs, but the visibility we have now is already miles ahead of where we were six months ago.