Skip to main content
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).
MethodHow
Cookie sessionActive browser session
Loopback bypassRequests from 127.0.0.1 / ::1 bypass token check
Bearer tokenAuthorization: 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

NameHelp
messages_inbound_totalTotal inbound messages received by the gateway.
messages_dispatched_totalTotal inbound messages dispatched to an agent run.
messages_duplicate_totalTotal inbound messages dropped as duplicates.
outbound_sent_totalTotal outbound messages successfully delivered.
outbound_failed_totalTotal outbound messages that failed delivery.
approval_pending_totalTotal approval requests created.
approval_decided_totalTotal approval requests decided (allowed or denied).
channel_errors_totalTotal channel errors observed by supervision.
channel_restarts_totalTotal channel restarts performed by supervision.

​
Gauges

NameHelp
outbox_depthCurrent number of messages pending outbound delivery.
approval_pendingCurrent number of approvals awaiting a decision.
active_sessionsCurrent number of active gateway sessions.
channel_recoveriesTotal 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

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.
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.
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
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.

Bind-Aware Auth

The same _check_auth / loopback model used by /metrics — understand how token auth and 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.

Tracing Hook

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