The linkerd stat command is your go-to for understanding how your services are performing within the Linkerd service mesh, but most people only scratch the surface of its capabilities.
Let’s see it in action. Imagine you have a few services: webapp, api, and database. You’ve deployed them and Linkerd is meshing them. To get a quick overview of all services, you’d run:
linkerd stat --all
This will output something like:
NAME | PODS | SUCCESS | RTS | RPTS/S | TOTAL | --- LATENCY --- | --- SUCCESS ---
webapp | 3/3 | 100.00% | 10ms| 500 | 2500 | 8ms (25%) | 100.00% (2500)
api | 2/2 | 99.95% | 5ms | 1000 | 5000 | 4ms (50%) | 99.95% (4997)
database | 1/1 | 100.00% | 2ms | 2000 | 10000 | 1ms (75%) | 100.00% (10000)
This table gives you a snapshot: the number of pods ready versus desired, the overall success rate, the median request time (RTS), requests per second (RPTS/S), total requests, and then breakdowns of latency and success by percentage.
Now, let’s drill down. You’re concerned about the api service. You can inspect it specifically:
linkerd stat api
This might show:
NAME | PODS | SUCCESS | RTS | RPTS/S | TOTAL | --- LATENCY --- | --- SUCCESS ---
webapp (dest) | 3/3 | 100.00% | 10ms | 500 | 2500 | 8ms (25%) | 100.00% (2500)
api | 2/2 | 99.95% | 5ms | 1000 | 5000 | 4ms (50%) | 99.95% (4997)
─ api-9d8c7d6b5a4f3e2d1c0a | 1/1 | 100.00% | 4ms | 500 | 2500 | 3ms (25%) | 100.00% (2500)
─ api-a1b2c3d4e5f6a7b8c9d0 | 1/1 | 99.90% | 6ms | 500 | 2500 | 5ms (75%) | 99.90% (2497)
Notice how linkerd stat api automatically shows you the upstream dependencies (webapp in this case) and the individual pods that make up the api service. This is where the real power lies. You can see that one of your api pods (api-a1b2c3d4e5f6a7b8c9d0) is experiencing a slightly higher latency and a lower success rate.
The problem this solves is understanding distributed system behavior. In a microservices architecture, tracing a request from end-to-end and identifying bottlenecks or failures can be incredibly difficult. Linkerd, by injecting a "transparent proxy" (the linkerd-proxy) into each pod, intercepts all inbound and outbound traffic. This proxy collects detailed metrics about each request (latency, success/failure, bytes transferred, etc.) and reports them to the Linkerd control plane. linkerd stat then queries this control plane data to provide a unified, service-centric view.
You can also filter by namespace. If your api service is in the production namespace, you’d use:
linkerd stat api --namespace production
Or even look at specific resources within a service, like a particular deployment:
linkerd stat deploy/api --namespace production
The RTS (request time) column is the median request latency. The percentages in parentheses next to the latency breakdown (e.g., 4ms (50%)) indicate the latency at that percentile. So, 4ms (50%) means 50% of requests to the api service completed in 4ms or less. The success percentages are crucial for identifying unhealthy services.
What most people don’t realize is that the linkerd-proxy itself is highly configurable and can be tuned for specific performance characteristics. For example, you can adjust the buffer sizes and timeouts for upstream connections directly in the proxy’s configuration. However, for most use cases, the defaults are well-tuned, and linkerd stat provides the necessary visibility without requiring deep proxy configuration knowledge.
The next step after inspecting service performance is often to dive into request tracing for a specific slow or failing request.