telemetry

README

go-telemetry - OTEL HTTP Telemetry

Documentation

Official godoc documentation (with examples) can be found at the Package Registry.

Usage

Add Package Dependency

go get -u github.com/poly-gun/go-telemetry

Import and Implement

main.go

package main

func main() {
    return
}

• Please refer to the code examples for additional usage and implementation details.
• See https://pkg.go.dev/github.com/poly-gun/go-telemetry for additional documentation.

Contributions

See the Contributing Guide for additional details on getting started.

Task-Board

• Create a Resource Detector for Kubernetes Telemetry.

Documentation

Index

• func Interrupt(ctx context.Context, cancel context.CancelFunc, ...) chan os.Signal
• func Setup(ctx context.Context, options ...Variadic) (shutdown func(context.Context) error)
• type Logs
• type Metrics
• type Settings
  • func Options() *Settings
• type Tracer
• type Variadic
• type Zipkin

Examples

• Interrupt

Functions

func Interrupt

func Interrupt(ctx context.Context, cancel context.CancelFunc, shutdown func(context.Context) error) chan os.Signal

Interrupt is a graceful interrupt + signal handler for the telemetry pipeline.

Example

package main

import (
	"context"
	"fmt"
	"io"
	"os"
	"syscall"
	"time"

	telemetry "github.com/poly-gun/go-kubernetes-telemetry"
)

func main() {
	const service = "example-service"
	const version = "0.0.0"

	_ = os.Setenv("OTEL_RESOURCE_ATTRIBUTES", fmt.Sprintf("service.name=%s,service.version=%s", service, version))

	ctx, cancel := context.WithCancel(context.Background())

	// Telemetry Setup + Cancellation Handler
	shutdown := telemetry.Setup(ctx, func(options *telemetry.Settings) {
		options.Zipkin.Enabled = false // disabled during testing

		options.Tracer.Local = true
		options.Metrics.Local = true
		options.Logs.Local = true

		options.Metrics.Writer = io.Discard // prevent output from filling the test logs
	})

	listener := telemetry.Interrupt(ctx, cancel, shutdown)

	time.Sleep(5 * time.Second)

	listener <- syscall.SIGTERM

	<-ctx.Done()

	fmt.Println("Telemetry Shutdown Complete")

}

Output:

Telemetry Shutdown Complete

func Setup

func Setup(ctx context.Context, options ...Variadic) (shutdown func(context.Context) error)

Setup bootstraps the OpenTelemetry pipeline. If it does not return an error, make sure to call shutdown for proper cleanup.

Types

type Logs

type Logs struct {
	// Logs represents [otlploghttp.Option] configurations.
	//
	// Defaults:
	//
	// 	- otlploghttp.WithInsecure()
	// 	- otlploghttp.WithEndpoint("http://zipkin.istio-system.svc.cluster.local:9411")
	Options []otlploghttp.Option

	// Debugger configures an additional [stdoutlog.Exporter] if not nil. Defaults nil.
	Debugger *stdoutlog.Exporter

	// Local will prevent an external log exporter from getting used as a processor. If true, forces [Logs.Debugger] configuration. Default is false.
	Local bool

	// Writer is an optional [io.Writer] for usage when [Logs.Local] or [Logs.Debugger] options are configured. Defaults to [os.Stdout].
	Writer io.Writer
}

type Metrics

type Metrics struct {
	// Options represents [otlpmetrichttp.Option] configurations.
	//
	// Defaults:
	//
	// 	- otlpmetrichttp.WithInsecure()
	//	- otlpmetrichttp.WithEndpoint("opentelemetry-collector.observability.svc.cluster.local:4318")
	Options []otlpmetrichttp.Option

	// Debugger configures an additional [metric.Exporter] if not nil. Defaults nil.
	Debugger metric.Exporter

	// Local will prevent an external metrics provider from getting used. If true, forces [Metrics.Debugger] configuration. Default is false.
	Local bool

	// Writer is an optional [io.Writer] for usage when [Metrics.Local] or [Metrics.Debugger] options are configured. Defaults to [os.Stdout].
	Writer io.Writer
}

type Settings

type Settings struct {
	// Zipkin represents a zipkin collector.
	Zipkin *Zipkin

	// Tracer represents [otlptracehttp.Option] configurations.
	Tracer *Tracer

	// Metrics represents [otlpmetrichttp.Option] configurations.
	Metrics *Metrics

	// Logs represents [otlploghttp.Option] configurations.
	Logs *Logs

	// Propagators ...
	//
	// Defaults:
	//
	//	- [propagation.TraceContext]
	//	- [propagation.Baggage]
	Propagators []propagation.TextMapPropagator
}

func Options

func Options() *Settings

type Tracer

type Tracer struct {
	// Options represents [otlptracehttp.Option] configurations.
	//
	// Defaults:
	//
	// 	- otlptracehttp.WithInsecure()
	// 	- otlptracehttp.WithEndpoint("opentelemetry-collector.observability.svc.cluster.local:4318")
	Options []otlptracehttp.Option

	// Debugger configures an additional [stdouttrace.Exporter] if not nil. Defaults nil.
	Debugger *stdouttrace.Exporter

	// Local will prevent an external tracer from getting used as a provider. If true, forces [Tracer.Debugger] configuration. Default is false.
	Local bool

	// Writer is an optional [io.Writer] for usage when [Tracer.Local] or [Tracer.Debugger] options are configured. Defaults to [os.Stdout].
	Writer io.Writer
}

Tracer represents a tracer configuration for OpenTelemetry.

type Variadic

type Variadic func(options *Settings)

type Zipkin

type Zipkin struct {
	// URL - Zipkin collector url - defaults to "http://opentelemetry-collector.observability.svc.cluster.local:9441".
	URL string

	// Enabled will enable the Zipkin collector. Default is true.
	Enabled bool
}

Zipkin represents the configuration for a Zipkin collector. URL specifies the Zipkin collector URL, defaulting to "http://opentelemetry-collector.observability.svc.cluster.local:9441". Enabled determines if the Zipkin collector is active. Default is true.