Export Telemetry via OpenTelemetry

Stream traces, metrics, and application logs directly to Datadog, Grafana Cloud, Honeycomb, New Relic, or internal OTel collectors with zero code modifications.

TracesMetricsLogs

Supported Telemetry Signals

Traces

Every API request, database transaction, cryptographic hash verification, and background worker job — linked into end-to-end distributed traces.

Metrics

Ingestion throughput, verification latencies, proof validation rates, and Celery queue depths — exported periodically via OTLP metrics.

Logs

Structured JSON logs with trace_id and span_id automatically injected, connecting raw server diagnostics to high-level agent decisions.

Step 01

Enable OTel with Environment Variables

Set these two variables in your deployment environment or .env file. All other exporter options have production-safe defaults.

.env

bash

OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://your-collector:4317

Network note: Ensure the collector endpoint is reachable from the Blocklog container. Use an internal DNS name or host IP rather than localhost when running in Docker.

Step 02

Inject Variables into Compose / ECS

Pass the collector target and service name to your Blocklog container definition.

docker-compose.yml

yaml

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

Step 03

Configure the OTel Collector Pipeline

Blocklog transmits data using standard OTLP over gRPC (port 4317) or HTTP (port 4318). Below is a production collector pipeline routing to Jaeger and Prometheus.

otel-collector-config.yaml

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]

Alternative: Grafana Agent (Alloy / River Syntax)

If your observability stack uses Grafana Cloud or self-hosted Tempo and Loki, configure Grafana Agent to receive OTLP signals natively:

grafana-agent.alloy

text

# 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]
  }
}

Environment Configuration Reference

.env.complete

bash

# 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

Variable	Default	Description
OTEL_ENABLED	false	Enables trace, metric, and log export pipelines.
OTEL_EXPORTER_OTLP_ENDPOINT	http://localhost:4317	Collector destination URL (gRPC: 4317, HTTP: 4318).
OTEL_SERVICE_NAME	blocklog	Service name tag emitted with all telemetry records.
OTEL_EXPORTER_PROTOCOL	grpc	Wire protocol: 'grpc' or 'http'.
OTEL_EXPORTER_OTLP_HEADERS	—	Optional header string (e.g. 'Authorization=Bearer <token>').
OTEL_TRACES_SAMPLE_RATE	1.0	Trace sampling ratio (1.0 = 100%, 0.1 = 10%).
OTEL_METRICS_EXPORT_INTERVAL_MS	60000	Metrics push cadence in milliseconds.

Signal Pipeline Reference

Signal	Exporter Type	Batch Processor	Default Cadence
Traces	OTLPSpanExporter	BatchSpanProcessor	On flush / 5 s max
Metrics	OTLPMetricExporter	PeriodicExportingMetricReader	60 s (configurable)
Logs	OTLPLogExporter	BatchLogRecordProcessor	On flush / 5 s max

Troubleshooting Telemetry Streams

No telemetry records appearing in your backend

Confirm OTEL_ENABLED=true is set and check container logs for connection refusal errors. Verify firewall rules allow outbound traffic to the specified collector port.

Traces arrive but metrics or logs are absent

Ensure your OpenTelemetry Collector configuration explicitly enables separate pipeline receivers for metrics and logs under service.pipelines.

High data volume and ingestion costs

Adjust OTEL_TRACES_SAMPLE_RATE to 0.1 (10% sampling) or 0.05 (5% sampling). Health check probes and internal pings are excluded from tracing by default.