sdk

sdk

SDK for go-faster applications. Implements automatic setup of observability and daemonization based on environment variables. Also automatically sets up GOMAXPROCS and GOMEMLIMIT.

Packages

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.

Example

Environment file

OTEL_LOG_LEVEL=debug
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_INSECURE=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317
OTEL_RESOURCE_ATTRIBUTES=service.name=go-faster.simon

# metrics exporter
OTEL_METRIC_EXPORT_INTERVAL=10000
OTEL_METRIC_EXPORT_TIMEOUT=5000

# pyroscope
PYROSCOPE_URL=http://127.0.0.1:4040
# should be same as service.name
PYROSCOPE_APP_NAME=go-faster.simon
PYROSCOPE_ENABLE=true

# use new metrics
OTEL_GO_X_DEPRECATED_RUNTIME_METRICS=false
# generate instance id
OTEL_GO_X_RESOURCE=true

Docker Compose

services:
  app:
    image: ghcr.io/go-faster/simon:0.6.1
    environment:
      - OTEL_LOG_LEVEL=debug
      - OTEL_EXPORTER_OTLP_PROTOCOL=grpc
      - OTEL_EXPORTER_OTLP_INSECURE=true
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://otelcol:4317
      - OTEL_GO_X_DEPRECATED_RUNTIME_METRICS=false
      - OTEL_GO_X_RESOURCE=true
      - OTEL_METRIC_EXPORT_INTERVAL=1000
      - OTEL_METRIC_EXPORT_TIMEOUT=500

Kubernetes

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: simon-client
  namespace: simon
spec:
  replicas: 1
  selector:
    matchLabels:
      app: simon-client
  template:
    metadata:
      labels:
        app: simon-client
    spec:
      containers:
        - name: ingest
          image: ghcr.io/go-faster/simon:0.6.1
          env:
            - name: OTEL_EXPORTER_OTLP_PROTOCOL
              value: "grpc"
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: "http://otel-collector.monitoring.svc.cluster.local:4317"
            - name: OTEL_LOG_LEVEL
              value: "debug"
            - name: OTEL_EXPORTER_OTLP_INSECURE
              value: "true"
            - name: OTEL_GO_X_DEPRECATED_RUNTIME_METRICS
              value: "false"
            - name: OTEL_METRIC_EXPORT_INTERVAL
              value: "1000"
            - name: OTEL_METRIC_EXPORT_TIMEOUT
              value: "500"

Reference

Metrics exporters

Trace exporters

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"
export OTEL_LOGS_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

Code coverage