Trace

With Treblle’s Trace feature, you can follow a single request’s entire journey, even when it travels across multiple APIs and services.

How Tracing Works

To link requests together, Treblle uses a unique identifier called a Trace ID. The Treblle SDKs automatically look for a header on the incoming request. If this header is present, its value is used to group the request with others that share the same ID. If the header is missing, you can also generate a new unique ID, starting a new trace. Your application is then responsible for propagating this ID to any subsequent API calls.

Here is an example of a Go middleware that handles the treblle-tag-id.

// This example is for documentation and assumes an upstream service has already
// generated a trace ID and passed it in the 'treblle-tag-id' header.

func treblleMiddleware(cfg config.Config) func(http.Handler) http.Handler {

    treblle.Configure(treblle.Configuration{
        SDK_TOKEN: cfg.TreblleToken,
        API_KEY:   cfg.TreblleAPIKey,
    })

    return func(next http.Handler) http.Handler {
        type contextKey string
        const traceIDKey = contextKey("traceID")

        handlerWithTreblle := treblle.Middleware(next)

        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            traceID := r.Header.Get("treblle-tag-id")
            w.Header().Set("treblle-tag-id", traceID)
            ctx := context.WithValue(r.Context(), traceIDKey, traceID)
            handlerWithTreblle.ServeHTTP(w, r.WithContext(ctx))
        })
    }
}

Best Practices for Trace IDs

• Generate a Unique ID: Start the trace by generating a unique ID (like a UUID or ULID) in your first service, or let a middleware do it for you.
• Propagate the ID: Pass this ID along to any subsequent API calls that are part of the same transaction or workflow.

Understanding the Trace View

The Trace page provides a comprehensive list of all traced request groups. You can switch between a List view (shown above) and a Table view for different perspectives.

Each trace in the list shows you:

• Trace ID: The unique identifier for the group of requests.
• Duration: The total time taken from the start of the first request to the end of the last one.
• Status: The overall status of the trace (e.g., Success, Failed), which helps you quickly spot problems.
• Requests: The total number of API calls in the trace.
• APIs: The number of unique APIs involved.
• Parent API: The first API that was called in the trace.

Mapping a Single Trace

When you click on a specific trace from the list, you’ll be taken to the Trace Details view. This view provides a chronological breakdown of every API request that is part of that trace.

In the example above, you can see a user workflow that consists of three separate API calls, all grouped under a single Trace ID. Let’s break down what this view tells us:

1. Request Mapping: The three requests—POST /auth/register, POST /posts, and GET /posts/history—are all part of a single logical transaction. They are mapped together using a unique Trace ID (982104ea-65c6-4bf5-8f87-f7b1622c376b in this case). This ID is generated by the first service and propagated in the headers of all subsequent requests in the chain. Treblle automatically groups them, giving you a complete picture of the user’s journey.

2. The Importance of Tracing: This unified view is crucial for several reasons:

   • End-to-End Visibility: Tracing provides a clear, end-to-end view of how requests flow through your system. Instead of analyzing isolated logs from different services, you can see the entire sequence of events in one place.
   • Rapid Debugging: If a step in the process fails, you can immediately see the context. For example, if the GET /posts/history call had returned an error, you could inspect the preceding POST /posts request to see what data was sent and if it completed successfully.
   • Performance Analysis: The view shows the total duration for the entire trace, as well as the individual load time for each request. This helps you pinpoint bottlenecks and understand which parts of your system are slow.
   • Understanding System Behavior: For complex systems, traces are an invaluable tool for understanding how different microservices or APIs interact to fulfill a user request. It documents the real-world behavior of your application.

Filtering and Sorting Traces

To help you find exactly what you’re looking for, the Trace page has powerful filtering and sorting tools.

Filtering

You can filter traces by:

• Status: Isolate successful, failed, or other request statuses.
• Duration: Find traces that are running faster or slower than a specific time range.
• APIs: Narrow down the list to traces that involve one or more specific APIs.

Sorting

You can sort the list of traces by:

• Trace ID
• Duration (ascending or descending)
• Created At (newest or oldest)