BLOCKLOG

Observability

Export Telemetry via OpenTelemetry

Blocklog can push traces, metrics, and logs to any OpenTelemetry-compatible backend — Grafana, Jaeger, Datadog, Honeycomb, or your own collector. Two environment variables are all it takes to enable it.

TracesMetricsLogs

What Blocklog exports

Traces

Every API request, database query, cache operation, and background job — linked across services into full end-to-end traces.

Metrics

Request rates, error rates, latency histograms, and log ingestion counts — exported on a 60-second interval by default.

Logs

Structured application logs with trace_id and span_id injected automatically, so every log line links back to a trace.

Step 1

Enable OTel with two variables

Set these in your environment, .env file, or deployment config. Everything else has a working default.

.env
OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://your-collector:4317
ℹ
Your collector must be reachable from the Blocklog process. Use a hostname or IP that resolves inside your network — localhost won't work inside Docker unless you set network_mode: host.

Step 2

Pass variables to your deployment

If you run Blocklog via Docker Compose, add the variables to your service definition.

docker-compose.yml
services:
  blocklog:
    image: blocklog/blocklog:latest
    environment:
      OTEL_ENABLED: "true"
      OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
      OTEL_SERVICE_NAME: "blocklog"

Step 3

Configure your collector

Blocklog sends data over OTLP. Your collector needs an OTLP receiver on port 4317 (gRPC) or 4318 (HTTP). Below is a minimal OpenTelemetry Collector config that forwards everything to Jaeger.

otel-collector-config.yaml
# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  # Replace with your backend — Jaeger, Datadog, Honeycomb, etc.
  otlp/jaeger:
    endpoint: jaeger:4317
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlp/jaeger]
    metrics:
      receivers: [otlp]
      exporters: [otlp/jaeger]
    logs:
      receivers: [otlp]
      exporters: [otlp/jaeger]

Replace the exporters block with your backend. The OTel Collector supports Datadog, Honeycomb, Prometheus, Loki, and dozens more out of the box.

Using Grafana Agent?

If your stack is Grafana Cloud or a self-hosted Grafana + Tempo + Loki setup, point Blocklog at your Grafana Agent instead. The agent accepts OTLP natively and routes signals to the right backend automatically.

grafana-agent.yaml
# grafana-agent.yaml (River syntax)
otelcol.receiver.otlp "default" {
  grpc { endpoint = "0.0.0.0:4317" }
  http { endpoint = "0.0.0.0:4318" }

  output {
    traces  = [otelcol.exporter.otlp.tempo.input]
    metrics = [otelcol.exporter.prometheus.default.input]
    logs    = [otelcol.exporter.loki.default.input]
  }
}

All configuration variables

.env
# Endpoint — where your collector is listening
OTEL_EXPORTER_OTLP_ENDPOINT=http://your-collector:4317

# Protocol — "grpc" (default) or "http"
OTEL_EXPORTER_PROTOCOL=grpc

# Auth header, if your collector requires it
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <token>

# Sampling — fraction of traces to record (0.0–1.0, default 1.0)
OTEL_TRACES_SAMPLE_RATE=0.2

# How often metrics are pushed, in milliseconds (default 60000)
OTEL_METRICS_EXPORT_INTERVAL_MS=60000
VariableDefaultDescription
OTEL_ENABLEDfalseSet to true to enable all three signal pipelines.
OTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:4317OTLP collector endpoint. Use port 4317 for gRPC, 4318 for HTTP.
OTEL_SERVICE_NAMEblocklogService name that appears in your tracing backend.
OTEL_EXPORTER_PROTOCOLgrpcTransport protocol — grpc or http.
OTEL_EXPORTER_OTLP_HEADERS—Comma-separated auth headers. e.g. "Authorization=Bearer token".
OTEL_TRACES_SAMPLE_RATE1.0Fraction of traces to record. 0.2 = 20 %, 1.0 = all.
OTEL_METRICS_EXPORT_INTERVAL_MS60000How often metrics are pushed to the collector, in milliseconds.

Signal pipeline reference

SignalExporterBatchingDefault cadence
TracesOTLPSpanExporterBatchSpanProcessorOn flush / 5 s max
MetricsOTLPMetricExporterPeriodicExportingMetricReader60 s (configurable)
LogsOTLPLogExporterBatchLogRecordProcessorOn flush / 5 s max

Troubleshooting

No data appearing in my backend

Confirm OTEL_ENABLED=true is set and that Blocklog's logs show no connection errors on startup. Check that your collector is reachable at the configured endpoint and that the protocol (gRPC vs HTTP) matches the collector's listener.

Traces arrive but metrics or logs are missing

Make sure your collector config has separate pipeline entries for metrics and logs. The OpenTelemetry Collector does not route signals automatically — each must be declared explicitly in the service.pipelines block.

Too much data / high cardinality

Lower OTEL_TRACES_SAMPLE_RATE to reduce trace volume (e.g. 0.1 for 10%). Health and metrics endpoints are excluded from tracing by default.