sdk

README

sdk

SDK for go-faster applications. Implements automatic setup of observability and daemonization based on environment variables.

Packages

Package	Description
autometer	Automatic OpenTelemetry MeterProvider from environment
autotracer	Automatic OpenTelemetry TracerProvider from environment
profiler	Explicit pprof routes
zctx	context.Context and tracing support for zap
gold	Golden files in tests
app	Automatic setup observability and run daemon

Environment variables

[!WARNING] The pprof listener is disabled by default and should be explicitly enabled by PPROF_ADDR.

[!IMPORTANT]
For configuring OpenTelemetry exporters, see OpenTelemetry exporters documentation.

Metrics and pprof can be served from same address if needed, set both addresses to the same value.

Name	Description	Example	Default
AUTOMAXPROCS	Use automaxprocs	0	1
AUTOMAXPROCS_MIN	Minimum GOMAXPROCS to use	2	1
OTEL_RESOURCE_ATTRIBUTES	OTEL Resource attributes	service.name=app
OTEL_SERVICE_NAME	OTEL Service name	app	unknown_service
OTEL_EXPORTER_OTLP_PROTOCOL	OTLP protocol to use	http	grpc
OTEL_PROPAGATORS	OTEL Propagators	none	tracecontext,baggage
PPROF_ROUTES	List of enabled pprof routes	cmdline,profile	See below
PPROF_ADDR	Enable pprof and listen on addr	0.0.0.0:9010	N/A
OTEL_LOG_LEVEL	Log level	debug	info
METRICS_ADDR	Prometheus addr (fallback)	localhost:9464	Prometheus addr
OTEL_METRICS_EXPORTER	Metrics exporter to use	prometheus	otlp
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL	Metrics OTLP protocol to use	http	grpc
OTEL_EXPORTER_PROMETHEUS_HOST	Host of prometheus addr	0.0.0.0	localhost
OTEL_EXPORTER_PROMETHEUS_PORT	Port of prometheus addr	9090	9464
OTEL_TRACES_EXPORTER	Traces exporter to use	otlp	otlp
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL	Traces OTLP protocol to use	http	grpc

Metrics exporters

Value	Description
otlp	OTLP exporter (default)
prometheus	Prometheus exporter
none	No exporter

Trace exporters

Value	Description
otlp	OTLP exporter (default)
none	No exporter

Defaults

By default, OpenTelemetry SDK tries localhost:4318 OTLP endpoint, assuming collector is running on the localhost.

If that is not true, following errors can be seen in the logs:

{"error": "failed to upload metrics: Post \"https://localhost:4318/v1/metrics\": dial tcp 127.0.0.1:4318: connect: connection refused"}

{"error": "failed to upload traces: Post \"https://localhost:4318/v1/traces\": dial tcp 127.0.0.1:4318: connect: connection refused"}

To fix that, configure exporters accordingly. For example, this will disable both metrics and traces exporters:

export OTEL_TRACES_EXPORTER="none"
export OTEL_METRICS_EXPORTER="none"

To enable Prometheus exporter, set OTEL_METRICS_EXPORTER=prometheus and OTEL_EXPORTER_PROMETHEUS_HOST and OTEL_EXPORTER_PROMETHEUS_PORT accordingly.

export OTEL_METRICS_EXPORTER="prometheus"
export OTEL_EXPORTER_PROMETHEUS_HOST="0.0.0.0"
export OTEL_EXPORTER_PROMETHEUS_PORT="9090"

Routes for pprof

List of enabled pprof routes

Name: PPROF_ROUTES

Default: profile,symbol,trace,goroutine,heap,threadcreate,block

TODO

• Use slog
• Pyroscope compat

Code coverage