tracing

import "github.com/go-coldbrew/tracing"

Package tracing provides distributed tracing for Go applications. It offers features such as collecting performance data, identifying where requests spend most of their time, and segmenting requests.

Traces are created and exported via OpenTelemetry. The core package configures the OTEL tracer provider at startup, sending traces to any OTLP-compatible backend (Jaeger, Grafana Tempo, Honeycomb, etc.) or New Relic.

Index

• Constants
• func ClientSpan(operationName string, ctx context.Context) (context.Context, oteltrace.Span)
• func CloneContextValues(parent context.Context) context.Context
• func GRPCTracingSpan(operationName string, ctx context.Context) context.Context
• func MergeContextValues(parent context.Context, main context.Context) context.Context
• func MergeParentContext(parent context.Context, main context.Context) context.Context
• func NewContextWithParentValues(parent context.Context) context.Context
• type Span
  • func NewDatastoreSpan(ctx context.Context, datastore, operation, collection string) (Span, context.Context)
  • func NewExternalSpan(ctx context.Context, name string, url string) (Span, context.Context)
  • func NewHTTPExternalSpan(ctx context.Context, name string, url string, hdr http.Header) (Span, context.Context)
  • func NewInternalSpan(ctx context.Context, name string) (Span, context.Context)

Constants

SupportPackageIsVersion1 is a compile-time assertion constant. Downstream packages reference this to enforce version compatibility.

const SupportPackageIsVersion1 = true

func ClientSpan

func ClientSpan(operationName string, ctx context.Context) (context.Context, oteltrace.Span)

ClientSpan starts a new client span linked to the existing spans if any are found in the context. The returned context should be used in place of the original.

func CloneContextValues

func CloneContextValues(parent context.Context) context.Context

Deprecated: Use NewContextWithParentValues instead.

func GRPCTracingSpan

func GRPCTracingSpan(operationName string, ctx context.Context) context.Context

GRPCTracingSpan starts a new server span from incoming gRPC metadata. The returned context should be used in place of the original.

func MergeContextValues

func MergeContextValues(parent context.Context, main context.Context) context.Context

MergeContextValues merged the given main context with a parent context, Cancel/Deadline etc are used from the main context and values are looked in both the contexts can be use to merge a parent context with a new context, the new context will have the values from both the contexts

func MergeParentContext

func MergeParentContext(parent context.Context, main context.Context) context.Context

Deprecated: Use MergeContextValues instead.

func NewContextWithParentValues

func NewContextWithParentValues(parent context.Context) context.Context

NewContextWithParentValues clones a given context values and returns a new context obj which is not affected by Cancel, Deadline etc can be used to pass context values to a new context which is not affected by the parent context cancel/deadline etc from parent

type Span

Span defines an interface for implementing a tracing span. Consumers use this to create and annotate spans without coupling to a specific tracing backend.

type Span interface {
    // End ends the span, can also use Finish()
    End()
    // Finish ends the span, can also use End()
    Finish()
    // SetTag sets a tag on the span, can be used to add custom attributes
    SetTag(key string, value any)
    // SetQuery sets the query on the span, can be used to add query for datastore spans
    SetQuery(query string)
    // SetError sets the error on the span
    SetError(err error) error
}

func NewDatastoreSpan

func NewDatastoreSpan(ctx context.Context, datastore, operation, collection string) (Span, context.Context)

NewDatastoreSpan starts a span for tracing data store actions. This is used to trace actions against a data store, for example, a database query or a redis call.

Example

package main

import (
	"context"

	"github.com/go-coldbrew/tracing"
)

func main() {
	ctx := context.Background()

	// Create a span for a database operation
	span, ctx := tracing.NewDatastoreSpan(ctx, "postgres", "SELECT", "users")
	defer span.End()

	// Run your query — the span records datastore, operation, and collection
	_ = ctx
}

func NewExternalSpan

func NewExternalSpan(ctx context.Context, name string, url string) (Span, context.Context)

NewExternalSpan starts a span for tracing external actions. This is used to trace actions against an external service.

Example

package main

import (
	"context"

	"github.com/go-coldbrew/tracing"
)

func main() {
	ctx := context.Background()

	// Create a span for an external service call
	span, ctx := tracing.NewExternalSpan(ctx, "payment-gateway", "/charge")
	defer span.End()

	// Make the external call — the span tracks the dependency
	_ = ctx
}

func NewHTTPExternalSpan

func NewHTTPExternalSpan(ctx context.Context, name string, url string, hdr http.Header) (Span, context.Context)

NewHTTPExternalSpan starts a span for tracing external HTTP actions. It also injects trace propagation headers so the external service can correlate the call back to this service.

func NewInternalSpan

func NewInternalSpan(ctx context.Context, name string) (Span, context.Context)

NewInternalSpan starts a span for tracing internal actions. This is used to trace actions within the same service, for example, a function call.

Example

package main

import (
	"context"

	"github.com/go-coldbrew/tracing"
)

func main() {
	ctx := context.Background()

	// Create a span for internal business logic
	span, ctx := tracing.NewInternalSpan(ctx, "processOrder")
	defer span.End()

	// Your logic here — the span tracks duration and errors
	_ = ctx
}

Generated by gomarkdoc