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
Directories
¶
| Path | Synopsis |
|---|---|
|
Package app implements OTEL, prometheus, graceful shutdown and other common application features for go-faster projects.
|
Package app implements OTEL, prometheus, graceful shutdown and other common application features for go-faster projects. |
|
Package autometer provides an OpenTelemetry MeterProvider creation function.
|
Package autometer provides an OpenTelemetry MeterProvider creation function. |
|
Package autotracer provides an OpenTelemetry TracerProvider creation function.
|
Package autotracer provides an OpenTelemetry TracerProvider creation function. |
|
cmd
|
|
|
Package gold implements golden files.
|
Package gold implements golden files. |
|
Package otelenv provides helpers for working with OTEL_RESOURCE_ATTRIBUTES.
|
Package otelenv provides helpers for working with OTEL_RESOURCE_ATTRIBUTES. |
|
Package profiler implements pprof routes.
|
Package profiler implements pprof routes. |
|
Package zapotel provides OpenTelemetry logs exporter zap core implementation.
|
Package zapotel provides OpenTelemetry logs exporter zap core implementation. |
|
Package zctx is a context-aware zap logger.
|
Package zctx is a context-aware zap logger. |