Gateway Metrics

Prometheus-format message-flow metrics from the PraisonAI gateway

The gateway now ships in the praisonai-bot package. praisonai serve gateway still works exactly as documented here; for a standalone install see praisonai-bot Migration.

Scrape GET /metrics on the PraisonAI gateway to feed Prometheus — counters and gauges for every hop of the message flow, zero new dependencies.

from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful")
agent.start("Handle user messages while metrics export on GET /metrics")

curl -sH "Authorization: Bearer $PRAISONAI_GATEWAY_AUTH_TOKEN" http://localhost:8765/metrics

The user scrapes GET /metrics while messaging the gateway; counters and gauges record inbound, agent, and outbound hops.

Quick Start

1. Start the gateway with auth_token set

   gateway:
     host: "0.0.0.0"
     port: 8765
     auth_token: ${PRAISONAI_GATEWAY_AUTH_TOKEN}
   

   export PRAISONAI_GATEWAY_AUTH_TOKEN=secret
   praisonai gateway start --config gateway.yaml
   
2. Scrape the metrics endpoint

   curl -sH "Authorization: Bearer $PRAISONAI_GATEWAY_AUTH_TOKEN" \
     http://localhost:8765/metrics
   
3. Read the Prometheus exposition output

   # HELP channel_restarts_total Total channel restarts performed by supervision.
   # TYPE channel_restarts_total counter
   channel_restarts_total{channel="telegram"} 2.0
   # HELP messages_dispatched_total Total inbound messages dispatched to an agent run.
   # TYPE messages_dispatched_total counter
   messages_dispatched_total 184.0
   # HELP messages_inbound_total Total inbound messages received by the gateway.
   # TYPE messages_inbound_total counter
   messages_inbound_total 187.0
   # HELP outbound_failed_total Total outbound messages that failed delivery.
   # TYPE outbound_failed_total counter
   outbound_failed_total{channel="discord"} 1.0
   # HELP outbound_sent_total Total outbound messages successfully delivered.
   # TYPE outbound_sent_total counter
   outbound_sent_total{channel="telegram"} 184.0
   # HELP active_sessions Current number of active gateway sessions.
   # TYPE active_sessions gauge
   active_sessions 5.0
   # HELP channel_recoveries Total supervision recoveries per channel.
   # TYPE channel_recoveries gauge
   channel_recoveries{channel="telegram"} 2.0
   

---

How It Works

Gauges are sampled on every scrape — not pushed on a timer. The /metrics endpoint calls _refresh_metric_gauges() before rendering, so active_sessions and channel_recoveries always reflect the live gateway state.

---

Configuration Options

Authentication

The /metrics endpoint uses the same _check_auth gate as other operational endpoints (e.g. /info).

Method	How
Cookie session	Active browser session
Loopback bypass	Requests from 127.0.0.1 / ::1 bypass token check
Bearer token	Authorization: Bearer <token> header
Query param	?token=<token> (deprecated)

Returns 401 if token is required but missing; 403 on token mismatch.

If auth_token is not set in the gateway config, the endpoint is open to all callers. Set auth_token before binding to non-loopback addresses.

Counters

Name	Help
messages_inbound_total	Total inbound messages received by the gateway.
messages_dispatched_total	Total inbound messages dispatched to an agent run.
messages_duplicate_total	Total inbound messages dropped as duplicates.
outbound_sent_total	Total outbound messages successfully delivered.
outbound_failed_total	Total outbound messages that failed delivery.
approval_pending_total	Total approval requests created.
approval_decided_total	Total approval requests decided (allowed or denied).
channel_errors_total	Total channel errors observed by supervision.
channel_restarts_total	Total channel restarts performed by supervision.

Gauges

Name	Help
outbox_depth	Current number of messages pending outbound delivery.
approval_pending	Current number of approvals awaiting a decision.
active_sessions	Current number of active gateway sessions.
channel_recoveries	Total supervision recoveries per channel.

Labels: Counters and gauges accept an arbitrary labels dict (string→string). Channel-scoped metrics use labels={"channel": <name>}. Labels are rendered as sorted, deterministic name{a="b",c="d"} value.

---

Common Patterns

Recording a custom counter

from praisonai.gateway.server import WebSocketGateway

gateway = WebSocketGateway.from_config_file("gateway.yaml")

gateway.record_metric("messages_inbound_total", labels={"channel": "telegram"})

Fetching a JSON snapshot in tests

snap = gateway.metrics_snapshot()
# {"counters": {"messages_inbound_total{channel=\"telegram\"}": 1.0, ...},
#  "gauges":   {"active_sessions": 5.0, ...}}

Prometheus scrape config

scrape_configs:
  - job_name: praisonai-gateway
    metrics_path: /metrics
    bearer_token: ${PRAISONAI_GATEWAY_AUTH_TOKEN}
    static_configs:
      - targets: ["gateway.internal:8765"]

Using GatewayMetrics directly

from praisonai.bots import GatewayMetrics

metrics = GatewayMetrics()

metrics.inc("messages_inbound_total", labels={"channel": "telegram"})
metrics.set_gauge("active_sessions", 5.0)

print(metrics.counter_value("messages_inbound_total", labels={"channel": "telegram"}))
print(metrics.render_prometheus())

---

Best Practices

Set auth_token before binding to non-loopback

Always configure auth_token in gateway.yaml when your gateway binds to 0.0.0.0 or a public address. Without it, /metrics is open to the network.

Use a scrape interval of 5s or longer

Gauges are sampled on each scrape. Scraping more frequently than every 5 seconds wastes resources without adding useful resolution — gateway state changes at human timescales.

Alert on outbound_failed_total and channel_restarts_total

These two counters surface delivery problems immediately. Configure Prometheus alerting rules on their rates:

- alert: GatewayOutboundFailures
  expr: rate(outbound_failed_total[5m]) > 0
  for: 1m
- alert: GatewayChannelRestarts
  expr: rate(channel_restarts_total[5m]) > 0.1
  for: 2m

Don't depend on push frequency for gauges

active_sessions, outbox_depth, and approval_pending are point-in-time samples taken at scrape time — they are not time-averaged. Use them as snapshots, not as rate inputs.

---

Metrics show rates and totals; for per-turn latency and error spans, attach a hook via Gateway Tracing Hook.

Related

Bind-Aware Auth

The bind-aware loopback bypass (permissive on loopback by default) that also protects /metrics — understand how token auth and the loopback bypass work together.

Correlation IDs

Join ingress, session, and agent-run logs on one stable id per message.

Gateway Server

Multi-bot WebSocket gateway — the host that exposes /metrics.

BotOS

The full bot operating system layer above the gateway.

Hot-Reload Observability

Last reload outcome, watcher liveness, and config drift via health().

Tracing Hook

The other observability rail — per-stage OpenTelemetry spans alongside these counters.