Tutorial OTLP

Tutorial: export to OpenTelemetry (OTLP)

A complete walkthrough for pushing Argus metrics to an OpenTelemetry collector over OTLP, so they land in Datadog, Grafana Cloud, Honeycomb, New Relic, or any OTLP-capable backend. This is additive: /metrics and the built-in dashboard keep working; OTLP is a second export path you turn on with one setting.

Reference (how it maps internally): OTLP. Start with the Tutorial Single Bot if you have not run Argus yet.

When to use this

• Your observability backend ingests OTLP (push) rather than scraping Prometheus.
• You run in an environment where an inbound scrape is awkward (serverless, egress-only networking) and pushing out is easier.
• You already run an OpenTelemetry Collector and want bot metrics in the same pipeline as the rest of your services.

If you scrape with Prometheus, you do not need this; OTLP and Prometheus can also run side by side during a migration.

Bare minimum requirements

• A working Argus bot (see the single-bot tutorial).
• The OTLP extra:

pip install "argus-dpy[otlp]"

This pulls opentelemetry-sdk and opentelemetry-exporter-otlp-proto-grpc.

• An OTLP gRPC endpoint to send to - usually an OpenTelemetry Collector listening on :4317. (A backend's direct OTLP ingest URL works too.)

Step 1: turn on OTLP

Set otlp_endpoint (kwarg) or ARGUS_OTLP_ENDPOINT (env). That is the entire integration:

from discord.ext import commands
from argus import Argus

bot = commands.AutoShardedBot(command_prefix="!", intents=...)
Argus(bot, otlp_endpoint="http://localhost:4317")   # also still serves /metrics

or by environment:

ARGUS_OTLP_ENDPOINT=http://localhost:4317 DISCORD_TOKEN=... python bot.py

Argus attaches an OTLP adapter alongside Prometheus. Counters export via Counter.add, the command-duration histogram via Histogram.record, and every scrape-time gauge via an observable gauge whose callback is read at export time - so gauges stay pull-based (invariant 4) exactly like the Prometheus path. The discord_bot_info value becomes an observable gauge of 1 carrying the versions as attributes.

Step 2: run a collector

A minimal collector that receives OTLP and logs it (swap the exporter for your backend):

# otel-collector.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
exporters:
  debug:
    verbosity: detailed
  # e.g. otlphttp / datadog / prometheusremotewrite for a real backend
service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [debug]

docker run --rm -p 4317:4317 \
  -v "$(pwd)/otel-collector.yaml:/etc/otelcol/config.yaml" \
  otel/opentelemetry-collector:latest

Point ARGUS_OTLP_ENDPOINT at it (http://collector-host:4317) and your bot's metrics flow into the collector, then on to whatever exporter you configure.

Step 3: send to a real backend

Replace the debug exporter with your backend's. Common shapes:

• Grafana Cloud / Prometheus remote write: prometheusremotewrite exporter.
• Datadog: the datadog exporter (set the API key in the collector).
• Honeycomb / New Relic / others: otlphttp with the vendor's OTLP URL and an API-key header.

Keep the bot pointed at your collector; route to vendors in the collector, not in the bot. That way credentials and backend choices live in one place.

Best practices

• Keep cluster_id and namespace consistent with your Prometheus setup so the same series line up across both paths (the cluster attribute is exported on counters and the histogram just like the Prometheus label).
• Route in the collector, not the bot. The bot only needs one endpoint; do fan-out, batching, and auth in the collector.
• Secure the endpoint. Use TLS (https://) to a collector you control, or a private network; OTLP carries your operational data.
• OTLP is additive. You can keep the dashboard and /metrics on, or set dashboard=False and rely on your OTLP backend - both are valid.
• Mind the export interval. The SDK's periodic reader pushes on its own schedule; tune it via standard OpenTelemetry env vars (OTEL_METRIC_EXPORT_INTERVAL) if you need faster/slower exports.
• Pin versions of the bot image and the collector in production.

Troubleshooting

• No data at the backend: check the collector logs first (the debug exporter proves whether the bot reached the collector). If the collector sees data but the backend does not, the issue is the collector's exporter/credentials.
• Connection refused / handshake errors: the endpoint must be the gRPC receiver (:4317), reachable from the bot host; use https:// only if the collector terminates TLS.
• ImportError on start: install the extra (pip install "argus-dpy[otlp]").
• Want both push and scrape: leave /metrics enabled and set otlp_endpoint; they are independent.

See also

• OTLP - the adapter internals and the neutral-kind mapping.
• Metrics Reference - every metric exported.
• Configuration - otlp_endpoint / ARGUS_OTLP_ENDPOINT and precedence.