tracer

func (*Tracer) GetCarrier ¶

func (t *Tracer) GetCarrier(ctx context.Context) map[string]string

GetCarrier extracts the current trace context from a context object and returns it as a map that can be transmitted across service boundaries. This is essential for distributed tracing to maintain trace continuity across different services.

This method extracts W3C Trace Context headers, which follow the standard format for distributed tracing propagation. Using standardized headers ensures compatibility with other services and observability tools in your infrastructure that support the W3C Trace Context specification.

When a trace spans multiple services (e.g., a web service calling a database service), the trace context must be passed between these services to maintain a unified trace. This method facilitates this by extracting that context into a format that can be added to HTTP headers, message queue properties, or other inter-service communication.

Parameters:

• ctx: The context containing the current trace information

Returns:

• map[string]string: A map containing the trace context headers

The returned map typically includes:

• "traceparent": Contains trace ID, span ID, and trace flags
• "tracestate": Contains vendor-specific trace information (if present)

Example:

// Extract trace context for an outgoing HTTP request
func makeHttpRequest(ctx context.Context, url string) (*http.Response, error) {
    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
    if err != nil {
        return nil, err
    }

    // Get trace headers from context
    traceHeaders := tracer.GetCarrier(ctx)

    // Add trace headers to the outgoing request
    for key, value := range traceHeaders {
        req.Header.Set(key, value)
    }

    // Make the request with trace context included
    return http.DefaultClient.Do(req)
}

func (*Tracer) SetCarrierOnContext ¶

func (t *Tracer) SetCarrierOnContext(ctx context.Context, carrier map[string]string) context.Context

SetCarrierOnContext extracts trace information from a carrier map and injects it into a context. This is the complement to GetCarrier and is typically used when receiving requests or messages from other services that include trace headers.

This method is crucial for maintaining distributed trace continuity across service boundaries. When a service receives a request from another service that includes trace context headers, this method allows the receiving service to continue the existing trace rather than starting a new one. This creates a complete end-to-end view of the request's journey through your distributed system.

The method works with standard W3C Trace Context headers, ensuring compatibility across different services and observability systems. It handles extracting trace IDs, span IDs, and other trace context information from the carrier map and properly initializing the context for continuation of the trace.

Parameters:

• ctx: The base context to inject trace information into
• carrier: A map containing trace headers (like those from HTTP requests or message headers)

Returns:

• context.Context: A new context with the trace information from the carrier injected into it

The carrier map typically contains the following trace context headers:

• "traceparent": Contains trace ID, span ID, and trace flags
• "tracestate": Contains vendor-specific trace information (if present)

Example:

// Extract trace context from an incoming HTTP request
func httpHandler(w http.ResponseWriter, r *http.Request) {
    // Extract headers from the request
    headers := make(map[string]string)
    for key, values := range r.Header {
        if len(values) > 0 {
            headers[key] = values[0]
        }
    }

    // Create a context with the trace information
    ctx := tracer.SetCarrierOnContext(r.Context(), headers)

    // Use this traced context for processing the request
    // Any spans created with this context will be properly connected to the trace
    result, err := processRequest(ctx, r)
    // ...
}

func (*Tracer) StartSpan ¶

func (t *Tracer) StartSpan(ctx context.Context, name string) (context.Context, Span)

StartSpan creates a new span with the given name and returns an updated context containing the span, along with a Span interface. This is the primary method for creating spans to trace operations in your application.

The created span becomes a child of any span that exists in the provided context. If no span exists in the context, a new root span is created. This automatically builds a hierarchy of spans that reflects the structure of your application's operations.

Parameters:

• ctx: The parent context, which may contain a parent span
• name: A descriptive name for the operation being traced (e.g., "http-request", "db-query")

Returns:

• context.Context: A new context containing the created span
• Span: An interface to interact with the span, which must be ended when the operation completes

Best practices:

• Use descriptive, consistent naming conventions for spans
• Create spans for operations that are significant for performance or debugging
• For operations with sub-operations, create a parent span for the overall operation and child spans for each sub-operation
• Always defer span.End() immediately after creating the span

Example:

func processRequest(ctx context.Context, req Request) (Response, error) {
    // Create a span for this operation
    ctx, span := tracer.StartSpan(ctx, "process-request")
    // Ensure the span is ended when the function returns
    defer span.End()

    // Add context information to the span
    span.SetAttributes(map[string]interface{}{
        "request.id": req.ID,
        "request.type": req.Type,
        "user.id": req.UserID,
    })

    // Perform the operation, using the context with the span
    result, err := performWork(ctx, req)
    if err != nil {
        // Record the error on the span
        span.RecordError(err)
        return Response{}, err
    }

    return result, nil
}