trace

package
v0.18.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 21, 2023 License: MIT Imports: 17 Imported by: 0

README

trace: Simple Request Tracing

Build Status Go Reference

Overview

Package trace provides request tracing functionality that follows the OpenTelemetry specification. The package is designed to be used in conjunction with Goa. In particular it is aware of the Goa RequestID HTTP and gRPC middlewares and adds both the Goa service name and current request ID to the span attributes.

The package uses an adaptive sampler that is configured to sample at a given maximum number of request per seconds (2 per default). Using a time based rate rather than e.g. a fixed percentage rate allows the sampler to adapt to the load of the service.

Usage

The following example shows how to use the package. It implements an illustrative main function for a fictional service svc implemented in the package github.com/repo/services/svc

package main

import (
        "context"

        "goa.design/clue/log"
        "goa.design/clue/trace"
        goahttp "goa.design/goa/v3/http"

        "github.com/repo/services/svc"
        httpsvrgen "github.com/repo/services/svc/gen/http/svc/server"
        grpcsvrgen "github.com/repo/services/svc/gen/grpc/svc/server"
        svcgen "github.com/repo/services/svc/gen/svc"
)

func main() {
        // Initialize the log context
        ctx := log.With(log.Context(context.Background()), "svc", svcgen.ServiceName)
        // Create the service (user code)
        svc := svc.New(ctx)
        // Wrap the service with Goa endpoints
        endpoints := svcgen.NewEndpoints(svc)

        // Create HTTP server
        mux := goahttp.NewMuxer()
        httpsvr := httpsvrgen.New(endpoints, mux, goahttp.RequestDecoder, goahttp.ResponseEncoder, nil, nil)
        httpsvrgen.Mount(mux, httpsvr)

        // ** Initialize context for tracing **
        conn, err := grpc.DialContext(ctx, "localhost:6831") // Remote span collector address
        if err != nil {
                log.Error(ctx, "unable to connect to span collector", "err", err)
                os.Exit(1)
        }
        ctx = trace.Context(ctx, svcgen.ServiceName, trace.WithGRPCExporter(conn))

        // ** Trace HTTP requests **
        handler := trace.HTTP(ctx)(mux)

        // Create gRPC server
        grpcsvr := grpcsvrgen.New(endpoints, nil)

        // ** Trace gRPC requests **
        u := trace.UnaryServerTrace(ctx)
        s := trace.StreamServerTrace(ctx)
        pbsvr := grpc.NewServer(grpc.UnaryInterceptor(u), grpc.StreamInterceptor(s))

        // ...
}
Making Requests to Downstream Dependencies

For tracing to work appropriately all clients to downstream dependencies must be configured using the appropriate trace package function.

For HTTP dependencies the trace package provides a Client function that can be used to configure a http.RoundTripper to trace all requests made through it. Client panics if the context hasn't be initialized with trace.Context.

// Create a tracing HTTP client
c := &http.Client{Transport: trace.Client(ctx, http.DefaultTransport)}

For gRPC dependencies the trace package provides the UnaryClientTrace and StreamClientTrace interceptors that can be used when making gRPC calls. These functions will create a span for the current request if it is traced. Example:

// Create a tracing client for gRPC unary calls
conn, err := grpc.Dial(url, grpc.WithUnaryInterceptor(UnaryClientTrace(ctx)))

// Create a tracing client for gRPC stream calls
conn, err := grpc.Dial(url, grpc.WithStreamInterceptor(StreamClientTrace(ctx)))
Creating Additional Spans

Once configured the trace package automatically creates spans for a sample of incoming requests. The function IsTraced can be used to determine if the current request is being traced.

The trace package also provides a StartSpan function that can be used to create a new child span. The caller must also call EndSpan when the span is complete. Both functions do nothing if the current request is not being traced or the context has not been initialized with trace.Context.

func (s *svc) DoSomething(ctx context.Context, req *svcgen.DoSomethingRequest) (*svcgen.DoSomethingResponse, error) {
        // ...
        // Create a child span to measure the time taken to run an intensive
        // operation.
        ctx = trace.StartSpan(ctx, "DoSomethingIntense")
        DoSomethingIntense(ctx)
        trace.EndSpan(ctx)
        // ...
}
Adding Attributes to Spans

Attributes decorate spans and add contextual information to the trace. By default this package adds the following attributes to HTTP requests:

  • http.scheme: The HTTP scheme (http or https).
  • http.host: The host name of the request if available in the Host field.
  • http.flavor: The flavor of the request (1.0, 1.1 or 2).
  • http.method: The HTTP method of the request.
  • http.target: The URI of the request.
  • http.client_id: The client IP present in the X-Forwarded-For header if any.
  • http.user_agent: The user agent of the request if any.
  • http.request_content_length: The length of the request body if any.
  • enduser.id: The request basic auth username if any.
  • net.transport: One of ip_tcp, ip_udp, ip, unix or other.
  • net.peer.ip, net.peer.name, net.peer.port: The IP address, port and name of the remote peer if available in the request RemoteAddr field.
  • net.host.ip, net.host.name, net.host.port: The IP address, port and name of the remote host if available in the request Host field, the request Host header or the request URL.

and the following attributes to gRPC requests:

  • rpc.system: always set to grpc.
  • rpc.service: The gRPC service name.
  • rpc.method: The gRPC method name.
  • net.peer.ip, net.peer.port: The IP address and port of the remote peer.

Service method logic can add attributes when creating new spans via the WithAttributes option. Custom attributes can also be added later on with SetSpanAttributes. SetSpanAttributes does nothing if the request is not traced or the context not initialized with trace.Context.

// Create a child span with attributes
ctx = trace.StartSpan(ctx, "DoSomething", trace.WithAttributes(
        "key1", "value1",
        "key2", "value2",
))

// Add a custom attribute to the current span
trace.SetSpanAttributes(ctx, "custom_attribute", "value")
Adding Events

The AddEvent function makes it possible to attach events to a span. Events are useful to trace operations that are too fast to have their own span. For example, the completion of an asynchronous operation. Attributes can be added to the event to add contextual information. AddEvent does nothing if the request is not traced or the context not initialized with trace.Context.

// Add an event to the current span
trace.AddEvent(ctx, "operation completed", "operation_id", operationID, "status", status)
Span Status And Error

The Succeed, Fail and RecordError functions can be used to set the status and error of a span. The status indicates the success or failure of the operation. The error is used to record the error that occurred if any. Note that recording an error does not automatically change the status of the span. The functions do nothing if the request is not traced or the context not initialized with trace.Context. The default status of a completed span is success.

// Set the status of the current span to success (default)
trace.Succeed(ctx)

// Record an error in the current span and set the status to failure
trace.RecordError(ctx, err)
trace.Fail(ctx, "operation failed")

Documentation

Index

Constants

View Source 
const (
	// InstrumentationLibraryName is the name of the instrumentation library.
	InstrumentationLibraryName = "goa.design/clue"

	// AttributeRequestID is the name of the span attribute that contains the
	// request ID.
	AttributeRequestID = "request.id"
)

Variables

This section is empty.

Functions

func AddEvent 

func AddEvent(ctx context.Context, name string, keyvals ...string)

AddEvent records an event with the given name and attributes in the current span if any.

func Client 

func Client(ctx context.Context, t http.RoundTripper, opts ...otelhttp.Option) http.RoundTripper

Client returns a roundtripper that wraps t and creates spans for each request. It panics if the context hasn't been initialized with Context.

func Context 

func Context(ctx context.Context, svc string, opts ...TraceOption) (context.Context, error)

Context initializes the context so it can be used to create traces.

func ContinueRemoteTrace added in v0.7.0 

func ContinueRemoteTrace(ctx context.Context, name string, traceID [16]byte, keyvals ...string) context.Context

ContinueRemoteTrace initializes the tracing context with the given remote trace ID and starts a new server span. See StartTrace for usage.

func EndSpan 

func EndSpan(ctx context.Context)

End ends the current span if any.

func EndTrace added in v0.7.0 

func EndTrace(ctx context.Context)

EndTrace ends the last trace started by StartTrace.

func Fail 

func Fail(ctx context.Context, msg string)

Fail sets the status of the current span to failed and attaches the failure message.

func HTTP 

func HTTP(ctx context.Context) func(http.Handler) http.Handler

HTTP returns a tracing middleware that uses a parent based sampler (i.e. traces if the parent request traces) and an adaptive root sampler (i.e. when there is no parent uses a target number of requests per second to trace). The implementation leverages the OpenTelemetry SDK and can thus be configured to send traces to an OpenTelemetry remote collector. It is aware of the Goa RequestID middleware and will use it to propagate the request ID to the trace. HTTP panics if the context hasn't been initialized with Context.

Example: 

     // Connect to remote trace collector.
     conn, err := grpc.DialContext(ctx, collectorAddr,
         grpc.WithTransportCrendentials(insecure.Credentials()))
     if err != nil {
         log.Error(ctx, err)
         os.Exit(1)
     }
     // Initialize context for tracing
     ctx := trace.Context(ctx, svcgen.ServiceName, trace.WithGRPCExporter(conn))
     // Mount middleware
	handler := trace.HTTP(ctx)(mux)

func IsTraced 

func IsTraced(ctx context.Context) bool

IsTraced returns true if the current request is traced.

func Log added in v0.1.0 

func Log(ctx context.Context) (kvs []log.KV)

Log is a log key/value pair generator function that can be used to log trace and span IDs. Example: 

ctx := log.Context(ctx, WithFunc(trace.Log))
log.Printf(ctx, "message")

Output: traceID=<trace-id> spanID=<span-id> message

func RecordError 

func RecordError(ctx context.Context, err error)

RecordError records err as an exception span event for the current span if any. An additional call to SetStatus is required if the Status of the Span should be set to Error, as this method does not change the Span status.

func SetSpanAttributes 

func SetSpanAttributes(ctx context.Context, keyvals ...string)

SetSpanAttributes adds the given attributes to the current span if any. keyvals must be a list of alternating keys and values. It overwrites any existing attributes with the same key.

func SpanID 

func SpanID(ctx context.Context) string

SpanID returns the span ID of the current span if any, empty string otherwise.

func StartSpan 

func StartSpan(ctx context.Context, name string, keyvals ...string) context.Context

StartSpan starts a new span with the given name and attributes and stores it in the returned context if the request is traced, does nothing otherwise. keyvals must be a list of alternating keys and values.

func StartTrace added in v0.7.0 

func StartTrace(ctx context.Context, name string, keyvals ...string) context.Context

StartTrace starts a new trace and initializes the context with it. In general traces should be managed by HTTP middlewares and gRPC interceptors created via the HTTP, UnaryServerInterceptor and StreamServerInterceptor methods. This function is intended to be used by code running outside of network requests for example workers that initiate request threads. The context must be initialized with Context. EndTrace must be called by the client in the same goroutine. Not calling EndTrace may cause resource leaks.

func StreamClientInterceptor 

func StreamClientInterceptor(traceCtx context.Context) grpc.StreamClientInterceptor

StreamClientInterceptor returns an OpenTelemetry StreamClientInterceptor. It panics if the context has not been initialized with Context.

func StreamServerInterceptor 

func StreamServerInterceptor(traceCtx context.Context) grpc.StreamServerInterceptor

StreamServerInterceptor returns an OpenTelemetry StreamServerInterceptor. It panics if the context has not been initialized with Context.

func Succeed 

func Succeed(ctx context.Context)

Succeed sets the status of the current span to success if any.

func TraceID 

func TraceID(ctx context.Context) string

TraceID returns the trace ID of the current span if any, empty string otherwise.

func TraceProvider added in v0.5.0 

func TraceProvider(ctx context.Context) trace.TracerProvider

TraceProvider returns the underlying otel trace provider.

func UnaryClientInterceptor 

func UnaryClientInterceptor(traceCtx context.Context) grpc.UnaryClientInterceptor

UnaryClientInterceptor returns an OpenTelemetry UnaryClientInterceptor. It panics if the context has not been initialized with Context.

func UnaryServerInterceptor 

func UnaryServerInterceptor(traceCtx context.Context) grpc.UnaryServerInterceptor

UnaryServerInterceptor returns an OpenTelemetry UnaryServerInterceptor. It panics if the context has not been initialized with Context.

Types

type TraceOption 

type TraceOption func(ctx context.Context, opts *options) error

TraceOption is a function that configures a provider.

func WithDisabled 

func WithDisabled() TraceOption

WithDisabled disables tracing, not for use in production.

func WithExporter added in v0.5.0 

func WithExporter(exporter sdktrace.SpanExporter) TraceOption

WithExporter sets the exporter to use.

func WithGRPCExporter added in v0.5.0 

func WithGRPCExporter(conn *grpc.ClientConn) TraceOption

func WithMaxSamplingRate 

func WithMaxSamplingRate(rate int) TraceOption

WithMaxSamplingRate sets the maximum sampling rate in requests per second.

func WithParentSamplerOptions added in v0.7.0 

func WithParentSamplerOptions(samplerOptions ...sdktrace.ParentBasedSamplerOption) TraceOption

WithParentSamplerOptions to set the options for sdktrace.ParentBased sampler.

func WithPropagator added in v0.6.0 

func WithPropagator(propagator propagation.TextMapPropagator) TraceOption

WithPropagator sets the otel propagators

func WithResource added in v0.7.0 

func WithResource(res *resource.Resource) TraceOption

WithResource sets the underlying opentelemetry resource.

func WithSampleSize 

func WithSampleSize(size int) TraceOption

WithSampleSize sets the number of requests between two adjustments of the sampling rate.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.