Zipkin Example: Tracing a Request Through a Distributed System

Understanding a Zipkin Example in Practice

A Zipkin example typically starts with a client request entering a system and ends when that request's work is fully recorded. In between, Zipkin assigns a unique trace ID and collects spans—units of work—with timestamps, annotations, and metadata that show how long each service took and where latency appeared. The example below follows a common web request through multiple services and highlights the data Zipkin captures at each stage.

Anatomy of a Zipkin Trace

Every Zipkin example trace contains a root span and one or more child spans, linked by the same trace ID. Each span records a start time, duration, and a set of annotations such as cs (client sent), sr (server received), ss (server sent), and cr (client received). In a well-structured Zipkin example, these annotations make it easy to calculate network latency and service processing time without manual log parsing.

Step-by-Step Zipkin Example: A Web Request

Consider a typical three-tier application where a browser calls an API gateway, which forwards the request to a user service, and the user service calls a database. The Zipkin example below summarizes what the trace might look like:

• Span 1 (gateway): cs at T0, sr at T1, processing ends at T2, cr at T3. Duration covers network plus gateway logic.
• Span 2 (user-service): cs at T1, sr at T1+Δ, database call at T2, ss at T2+Δ2, cr shortly after.
• Span 3 (database): Shows the query execution window, often as a child of the user-service span.

When visualized in the Zipkin UI, these spans appear as a timeline where the length of each bar represents duration. A slow span stands out immediately, making it easier to pinpoint bottlenecks.

Instrumenting Your Code for a Zipkin Example

To produce a Zipkin example from your own application, you add a tracing library such as Brave (Java), zipkin-javascript, or the OpenTelemetry Zipkin exporter. The library creates spans around outbound HTTP calls, database queries, or message queue operations. You configure the exporter with the Zipkin server URL, and each request generates a trace ID that propagates through headers like X-B3-TraceId, X-B3-SpanId, and X-B3-ParentSpanId.

Minimal Brave Java Setup

In a Spring Boot application, adding the brave-starter-zipkin dependency and setting spring.zipkin.base-url to your Zipkin server address is often sufficient. The library auto-instruments RestTemplate, WebClient, and database clients, so the resulting Zipkin example requires no manual span creation for common I/O paths.

Node.js with zipkin-javascript

For Node.js, the zipkin-javascript library lets you define a tracer and wrap http and express middleware. Each request gets a trace ID that flows through headers to downstream services. When the request completes, spans are reported to the Zipkin collector endpoint.

Reading a Zipkin Example UI

The Zipkin UI shows traces in a dependency graph and a timeline view. In the timeline view, each span is colored by service and grouped by trace ID. You can click a span to see annotations, binary annotations (key-value tags), and the parent-child relationship. A practical Zipkin example often includes tags such as http.status_code, http.path, and error flags that help you filter traces by failure or high latency.

Common Patterns in a Zipkin Example

Most Zipkin examples share a few patterns: asynchronous messaging spans that show queue publish and consume times, fan-out spans where one request fans into several parallel downstream calls, and error spans marked with a binary annotation indicating the exception type. Recognizing these patterns helps you interpret traces quickly, even when the services are unfamiliar.

When a Zipkin Example Is Not Enough

A Zipkin example is powerful for latency analysis and dependency mapping, but it does not capture logs or metrics by default. For full observability, pair Zipkin with centralized logging and a metrics system such as Prometheus. The trace ID can be included in log entries to correlate a slow span with the exact log lines that explain why the work took longer than expected.