telemetry

README

Telemetry

This package can be used for building observable applications in Go. It aims to unify the three pillars of observability in one single package that is easy-to-use and hard-to-misuse.

This package leverages the OpenTelemetry API. OpenTelemetry is a great initiative that has brought all different standards and APIs for observability under one umbrella. However, due to the requirements for interoperability with existing systems, OpenTelemetry is highly abstract and complex. Many packages, configurations, and options make the developer experience not so pleasant. Furthermore, due to the changing nature of this project, OpenTelemetry specification changes often so does the Go library for OpenTelemetry. Currently, the tracing API is stable, the metric API is in alpha stage, and the logging API is frozen.

IMHO, this is not how a single unified observability API should be. Hopefully, many of these issues will go away once all APIs reache to v1.0.0. This package intends to provide a very minimal and yet practical API for observability by hiding the complexity of configuring and using OpenTelemetry API.

A probe encompasses a logger, meter, and tracer. It offers a unified developer experience for building observable applications.

The Three Pillars of Observability

Logging

Logs are used for auditing purposes (sometimes for debugging with limited capabilities). When looking at logs, you need to know what to look for ahead of time (known unknowns vs. unknown unknowns). Since log data can have any arbitrary shape and size, they cannot be used for real-time computational purposes. Logs are hard to track across different and distributed processes. Logs are also very expensive at scale.

Metrics

Metrics are regular time-series data with low and fixed cardinality. They are aggregated by time. Metrics are used for real-time monitoring purposes. Using metrics we can implement SLIs (service-level indicators), SLOs (service-level objectives), and automated alerts. Metrics are very good at taking the distribution of data into account. Metrics cannot be used with high-cardinality data.

Tracing

Traces are used for debugging and tracking requests across different processes and services. They can be used for identifying performance bottlenecks. Due to their very data-heavy nature, traces in real-world applications need to be sampled. Insights extracted from traces cannot be aggregated since they are sampled. In other words, information captured by one trace does not tell anything about how this trace is compared against other traces, and what is the distribution of data.

Quick Start

You can find basic examples here.

Options

Most options can be set through environment variables. This lets SRE people change how the observability pipeline is configured without making any code changes. Options set explicity in the code will override those set by environment variables.

Environment Variable	Description
PROBE_NAME	The name of service or application.
PROBE_VERSION	The version of service or application.
PROBE_TAG_*	Each variable prefixed with PROBE_TAG_ represents a tag for the service or application.
PROBE_LOGGER_ENABLED	Whether or not to create a logger (boolean).
PROBE_LOGGER_LEVEL	The verbosity level for the logger (debug, info, warn, error, or none).
PROBE_PROMETHEUS_ENABLED	Whether or not to configure and create a Prometheus meter (boolean).
PROBE_OPENTELEMETRY_METER_ENABLED	Whether or not to configure and create an OpenTelemetry Collector meter (boolean).
PROBE_OPENTELEMETRY_TRACER_ENABLED	Whether or not to configure and create an OpenTelemetry Collector tracer (boolean).
PROBE_OPENTELEMETRY_COLLECTOR_ADDRESS	The address to OpenTelemetry collector (i.e. localhost:55680).

Documentation

• Logging
  • go.uber.org/zap
• Metrics
  • Metrics API
  • go.opentelemetry.io/otel/metric
• Tracing
  • Tracing API
  • go.opentelemetry.io/otel/trace
• OpenTelemetry
  • Collector Configuration
  • Collector Architecture

Documentation

Overview

Package telemetry can be used for implementing observability using OpenTelemetry API. It aims to unify the three pillars of observability in one single package that is easy-to-use and hard-to-misuse. It offers a unified developer experience for implementing observability.

Index

• func ContextWithLogger(ctx context.Context, logger Logger) context.Context
• func ContextWithMeter(ctx context.Context, meter metric.Meter) context.Context
• func ContextWithTracer(ctx context.Context, tracer trace.Tracer) context.Context
• func ContextWithUUID(ctx context.Context, uuid string) context.Context
• func MeterFromContext(ctx context.Context) metric.Meter
• func Set(p Probe)
• func TracerFromContext(ctx context.Context) trace.Tracer
• func UUIDFromContext(ctx context.Context) (string, bool)
• type Level
• type Logger
  • func LoggerFromContext(ctx context.Context) Logger
• type Option
  • func WithLogger(level string) Option
  • func WithMetadata(name, version string, tags map[string]string) Option
  • func WithOpenTelemetry(meterEnabled, tracerEnabled bool, collectorAddress string, ...) Option
  • func WithPrometheus() Option
• type Probe
  • func Get() Probe
  • func NewProbe(opts ...Option) Probe
  • func NewVoidProbe() Probe

Functions

func ContextWithLogger

func ContextWithLogger(ctx context.Context, logger Logger) context.Context

ContextWithLogger returns a new context that holds a reference to a logger.

func ContextWithMeter

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

ContextWithMeter returns a new context that holds a reference to a meter.

func ContextWithTracer

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

ContextWithTracer returns a new context that holds a reference to a tracer.

func ContextWithUUID

func ContextWithUUID(ctx context.Context, uuid string) context.Context

ContextWithUUID creates a new context with a uuid.

func MeterFromContext

func MeterFromContext(ctx context.Context) metric.Meter

MeterFromContext returns a meter set on a context. If no meter found on the context, the singleton meter will be returned!

func Set

func Set(p Probe)

Set sets the singleton probe.

func TracerFromContext

func TracerFromContext(ctx context.Context) trace.Tracer

TracerFromContext returns a tracer set on a context. If no tracer found on the context, the singleton tracer will be returned!

func UUIDFromContext

func UUIDFromContext(ctx context.Context) (string, bool)

UUIDFromContext retrieves a uuid from a context.

Types

type Level

type Level int

Level is the logging level.

const (
	LevelNone Level = iota
	LevelError
	LevelWarn
	LevelInfo
	LevelDebug
)

Logging level

type Logger

type Logger interface {
	Level() Level
	SetLevel(level string)
	With(kv ...interface{}) Logger
	Debug(message string, kv ...interface{})
	Debugf(format string, args ...interface{})
	Info(message string, kv ...interface{})
	Infof(format string, args ...interface{})
	Warn(message string, kv ...interface{})
	Warnf(format string, args ...interface{})
	Error(message string, kv ...interface{})
	Errorf(format string, args ...interface{})
	Close() error
}

Logger is a levelled structured logger. It is concurrently safe to be used by multiple goroutines.

func LoggerFromContext

func LoggerFromContext(ctx context.Context) Logger

LoggerFromContext returns a logger set on a context. If no logger found on the context, the singleton logger will be returned!

type Option

type Option func(*options)

Option is used for configuring a probe.

func WithLogger

func WithLogger(level string) Option

WithLogger is the option for enabling the logger.

func WithMetadata

func WithMetadata(name, version string, tags map[string]string) Option

WithMetadata is the option for specifying and reporting metadata. All arguments are optional.

func WithOpenTelemetry

func WithOpenTelemetry(meterEnabled, tracerEnabled bool, collectorAddress string, collectorCredentials credentials.TransportCredentials) Option

WithOpenTelemetry is the option for enabling OpenTelemetry Collector. collectorCredentials is optional. If not specified, the connection will be insecure. The default collector address is localhost:55680.

func WithPrometheus

func WithPrometheus() Option

WithPrometheus is the option for enabling Prometheus.

type Probe

type Probe interface {
	http.Handler
	Name() string
	Logger() Logger
	Meter() metric.Meter
	Tracer() trace.Tracer
	Close(context.Context) error
}

Probe encompasses a logger, meter, and tracer.

func Get

func Get() Probe

Get returns the singleton probe.

func NewProbe

func NewProbe(opts ...Option) Probe

NewProbe creates a new probe.

func NewVoidProbe

func NewVoidProbe() Probe

NewVoidProbe creates a new no-op probe.