telemetry

README

Telemetry

This repository contains utilities for working with Open Telemetry. You can find a getting started guide with OpenTelemetry in Go on opentelemetry.io

Usage

Initialize the telemetry providers within main()

cfg := &telemetry.Config{
    ServiceName:    os.Getenv("OTEL_SERVICE_NAME"),
    Endpoint:       os.Getenv("OTEL_EXPORTER_OTLP_ENDPOINT"),
    Lambda:         true,
}

ctx, cleanup, err := telemetry.InitProviders(ctx, cfg)
if err != nil {
    // handle error
}

Example Lambda Setup

func main() {
    ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
	defer cancel()

    logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
    slog.SetDefault(logger)

    cfg := &telemetry.Config{
        ServiceName:    os.Getenv("OTEL_SERVICE_NAME"),
        Endpoint:       os.Getenv("OTEL_EXPORTER_OTLP_ENDPOINT"),
        Lambda:         true,
    }

    ctx, cleanup, err := telemetry.InitProviders(ctx, cfg)
    if err != nil {
        // handle error
    }

    adapter := primary.NewLambdaAdapter()

    // any remaining setup for lambda...

    lambda.StartWithOptions(
        otellambda.InstrumentHandler(adapter.HandleRequest,
            otellambda.WithTracerProvider(otel.GetTracerProvider()),
            otellambda.WithFlusher(otel.GetTracerProvider().(*trace.TracerProvider)),
            otellambda.WithPropagator(otel.GetTextMapPropagator()),
        ),
        lambda.WithContext(ctx),
        lambda.WithEnableSIGTERM(func() {
            cancel()
        }),
    )
}

Instrumentation

Applications can be manually instrumented or you can use any of the officially supported instrumentation libraries

Once providers are initialized, a tracer or meter can be retrieved from the context

tracer, err := telemetry.TracerFromContext(ctx)

meter, err := telemetry.MeterFromContext(ctx)

docs: https://opentelemetry.io/docs/languages/go/instrumentation/#metrics

Note: values returned by the functions above can be nil pointers, make sure to have proper validations before using them

To add custom spans within your application, the following can be done

ctx, span := tracer.Start(ctx, "Adapter.HandleRequest")
defer span.End()

docs: https://opentelemetry.io/docs/languages/go/instrumentation/#creating-spans

AWS SDK

Add the following after initialization to instrument the aws sdk

// init aws config
cfg, err := awsConfig.LoadDefaultConfig(ctx)
if err != nil {
    // handle error
}

// instrument all aws clients
otelaws.AppendMiddlewares(&cfg.APIOptions)

Host and Runtime Metrics

Add the following after initialization to instrument host and runtime metric collection

err = host.Start(host.WithMeterProvider(otel.GetMeterProvider()))
if err != nil {
    // handle error
}

err = runtime.Start(runtime.WithMeterProvider(otel.GetMeterProvider()), runtime.WithMinimumReadMemStatsInterval(time.Second))
if err != nil {
    // handle error
}

Documentation

Index

• func AddMeterContext(ctx context.Context, meter metric.Meter) context.Context
• func AddTracerContext(ctx context.Context, tracer trace.Tracer) context.Context
• func LogProviderFromContext(ctx context.Context) (*sdklog.LoggerProvider, error)
• func MeterFromContext(ctx context.Context) (metric.Meter, error)
• func TracerFromContext(ctx context.Context) (trace.Tracer, error)
• type CleanupFunc
  • func InitProviders(ctx context.Context, cfg *Config) (context.Context, CleanupFunc, error)
• type Config
• type DefaultResourceError
  • func (e DefaultResourceError) Error() string
• type GrpcConnError
  • func (e GrpcConnError) Error() string
• type LambdaResourceError
  • func (e LambdaResourceError) Error() string
• type LogExporterError
  • func (e LogExporterError) Error() string
• type LogProviderError
  • func (e LogProviderError) Error() string
• type LoggerCtxKey
• type MeterCtxKey
• type MeterError
  • func (e MeterError) Error() string
• type MetricExporterError
  • func (e MetricExporterError) Error() string
• type ResourceEnvError
  • func (e ResourceEnvError) Error() string
• type ResourceMergeError
  • func (e ResourceMergeError) Error() string
• type SdkResourceError
  • func (e SdkResourceError) Error() string
• type ShutdownFuncs
• type TraceExporterError
  • func (e TraceExporterError) Error() string
• type TracerCtxKey
• type TracerError
  • func (e TracerError) Error() string

Functions

func AddMeterContext

func AddMeterContext(ctx context.Context, meter metric.Meter) context.Context

AddMeterContext adds the meter to the context

func AddTracerContext

func AddTracerContext(ctx context.Context, tracer trace.Tracer) context.Context

AddTracerContext adds the tracer to the context

func LogProviderFromContext

func LogProviderFromContext(ctx context.Context) (*sdklog.LoggerProvider, error)

LogProviderFromContext checks the context for a logger provider. The returned value can be nil

func MeterFromContext

func MeterFromContext(ctx context.Context) (metric.Meter, error)

MeterFromContext checks the context for a meter. The returned value can be nil

func TracerFromContext

func TracerFromContext(ctx context.Context) (trace.Tracer, error)

TracerFromContext checks the context for a tracer. The returned value can be nil

Types

type CleanupFunc

type CleanupFunc func(context.Context)

func InitProviders

func InitProviders(ctx context.Context, cfg *Config) (context.Context, CleanupFunc, error)

InitProviders initializes trace and metric providers, and adds a tracer and meter to the context

type Config

type Config struct {
	ServiceName  string
	OtelEndpoint string
	TlsConfig    *tls.Config
	Lambda       bool
}

type DefaultResourceError

type DefaultResourceError struct {
	// contains filtered or unexported fields
}

func (DefaultResourceError) Error

func (e DefaultResourceError) Error() string

type GrpcConnError

type GrpcConnError struct {
	// contains filtered or unexported fields
}

func (GrpcConnError) Error

func (e GrpcConnError) Error() string

type LambdaResourceError

type LambdaResourceError struct {
	// contains filtered or unexported fields
}

func (LambdaResourceError) Error

func (e LambdaResourceError) Error() string

type LogExporterError

type LogExporterError struct {
	// contains filtered or unexported fields
}

func (LogExporterError) Error

func (e LogExporterError) Error() string

type LogProviderError

type LogProviderError struct{}

func (LogProviderError) Error

func (e LogProviderError) Error() string

type LoggerCtxKey

type LoggerCtxKey struct{}

type MeterCtxKey

type MeterCtxKey struct{}

type MeterError

type MeterError struct{}

func (MeterError) Error

func (e MeterError) Error() string

type MetricExporterError

type MetricExporterError struct {
	// contains filtered or unexported fields
}

func (MetricExporterError) Error

func (e MetricExporterError) Error() string

type ResourceEnvError

type ResourceEnvError struct {
	// contains filtered or unexported fields
}

func (ResourceEnvError) Error

func (e ResourceEnvError) Error() string

type ResourceMergeError

type ResourceMergeError struct {
	// contains filtered or unexported fields
}

func (ResourceMergeError) Error

func (e ResourceMergeError) Error() string

type SdkResourceError

type SdkResourceError struct {
	// contains filtered or unexported fields
}

func (SdkResourceError) Error

func (e SdkResourceError) Error() string

type ShutdownFuncs

type ShutdownFuncs []func(context.Context) error

type TraceExporterError

type TraceExporterError struct {
	// contains filtered or unexported fields
}

func (TraceExporterError) Error

func (e TraceExporterError) Error() string

type TracerCtxKey

type TracerCtxKey struct{}

type TracerError

type TracerError struct{}

func (TracerError) Error

func (e TracerError) Error() string