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"),
}

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

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

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

• type CleanupFunc
  • func InitProviders(ctx context.Context, cfg *Config) (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 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

Types

type CleanupFunc

type CleanupFunc func(context.Context)

func InitProviders

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

InitProviders initializes trace and metric providers

type Config

type Config struct {
	ServiceName        string
	OtelEndpoint       string
	TlsConfig          *tls.Config
	Lambda             bool
	Insecure           bool
	EnableSpanProfiles 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 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