Monitoring & Observability

AxonFlow ships with a practical local observability stack so engineers can see policy activity, latency, token usage, and connector behavior while they build. In Community Docker Compose, Prometheus and Grafana are started by default.

That observability story matters because governed AI systems are hard to trust if platform teams cannot answer basic runtime questions:

• what is the request volume and latency trend?
• are policies blocking too much or too little?
• are connectors healthy?
• which workloads are driving token usage and cost?
• can we debug a bad workflow run without reconstructing everything by hand?

What the Platform Exposes

• GET /health on the Agent (:8080)
• GET /health on the Orchestrator (:8081)
• GET /prometheus on both services for native Prometheus scraping
• GET /metrics on both services for JSON/debug-style metrics output
• Grafana on :3000
• Prometheus on :9090

Health Endpoints

Agent

curl -s http://localhost:8080/health | jq .

Typical fields:

{
  "status": "healthy",
  "service": "axonflow-agent",
  "version": "5.4.0",
  "capabilities": [],
  "sdk_compatibility": {}
}

Orchestrator

curl -s http://localhost:8081/health | jq .

Typical fields:

{
  "status": "healthy",
  "service": "axonflow-orchestrator",
  "version": "5.4.0",
  "components": {
    "policy_engine": true,
    "llm_router": true,
    "response_processor": true,
    "audit_logger": true,
    "workflow_engine": true
  }
}

Use these endpoints for:

• container and load-balancer health checks
• readiness probes
• fast smoke tests after config changes

Health checks are useful, but they are not enough by themselves. Mature teams pair them with request, policy, token, and connector metrics so they can see both availability and behavior.

Prometheus Scraping

Prometheus scraping should target /prometheus, not /metrics.

scrape_configs:
  - job_name: 'axonflow-agent'
    static_configs:
      - targets: ['YOUR_AGENT_HOST:8080']
    metrics_path: /prometheus
    scrape_interval: 15s

  - job_name: 'axonflow-orchestrator'
    static_configs:
      - targets: ['YOUR_ORCHESTRATOR_HOST:8081']
    metrics_path: /prometheus
    scrape_interval: 15s

The local Docker Compose file already provisions this for you via config/prometheus-local.yml.

For shared or longer-lived environments, teams usually keep the same scrape pattern but send the data to their existing Prometheus and Grafana estate rather than relying only on a laptop-local stack.

High-Value Metrics

These are the metrics the bundled community dashboard uses today:

Metric	Description
axonflow_agent_requests_total	Agent request volume
axonflow_agent_blocked_requests_total	Agent-side blocks
axonflow_agent_policy_evaluations_total	Agent policy evaluations
axonflow_agent_request_duration_milliseconds_bucket	Agent latency histogram
axonflow_gateway_precheck_requests_total	Gateway pre-check traffic
axonflow_gateway_precheck_duration_milliseconds_bucket	Gateway pre-check latency
axonflow_gateway_llm_tokens_total	Gateway token tracking
axonflow_gateway_llm_cost_usd_total	Gateway cost tracking
axonflow_orchestrator_llm_calls_total	Orchestrator provider traffic
axonflow_orchestrator_request_duration_milliseconds_bucket	Orchestrator latency
axonflow_connector_calls_total	MCP connector traffic
axonflow_connector_duration_milliseconds_bucket	Connector latency
axonflow_connector_errors_total	Connector error counts
axonflow_orchestrator_requests_total	Orchestrator request volume
axonflow_orchestrator_blocked_requests_total	Orchestrator-side blocks
axonflow_orchestrator_policy_evaluations_total	Orchestrator policy evaluations
axonflow_gateway_audit_requests_total	Gateway audit call volume
axonflow_gateway_audit_duration_milliseconds	Gateway audit latency
axonflow_gateway_audit_queued_total	Queued audit entries (async mode)
axonflow_gateway_audit_fallback_total	Audit entries written to disk fallback
axonflow_circuit_trips_total	Circuit breaker trip events (Enterprise)
axonflow_circuit_blocked_requests_total	Requests blocked by circuit breaker (Enterprise)

Logs

AxonFlow logs are useful for runtime debugging, especially when you are validating new policies, providers, or MCP connectors.

docker compose logs -f axonflow-agent
docker compose logs -f axonflow-orchestrator
docker compose logs -f prometheus
docker compose logs -f grafana

What to Watch First

When a team is adopting AxonFlow, the most useful first signals are:

• request latency on agent and orchestrator
• blocked vs allowed traffic
• gateway pre-check latency
• connector errors and latency
• token usage and estimated LLM cost

Those signals tell you whether the control plane is trustworthy enough for real workloads.

What This Gives Senior Engineers

For senior and staff engineers, observability is one of the strongest review criteria because it answers whether AxonFlow is just enforcing controls or also making them operable.

If the platform can show:

• latency
• block rates
• token and cost movement
• connector health
• audit-driven operational signals

then it is much easier to justify as the control plane for a serious AI application rather than a thin wrapper around provider APIs.

Community vs Higher Tiers

Community already gives teams enough observability to validate production behavior. Evaluation and Enterprise matter when organizations need longer retention, enterprise integrations, broader governance workflows, and procurement-friendly rollout.

Enterprise Monitoring Model

Enterprise monitoring spans more than service uptime. Operators usually need visibility across runtime health, portal-backed operations, usage and cost behavior, deployment progress, node/license state where available, and approval or workflow activity.

The enterprise monitoring model has three layers:

Runtime metrics

The Agent and Orchestrator expose Prometheus metrics for request volume, policy activity, latency, provider calls, connector activity, audit behavior, and circuit-breaker events. These are the same runtime signals engineers use in Community, but they matter more when multiple teams share the platform.

Portal-backed operational APIs

The customer portal adds operational signals through protected APIs such as:

• GET /api/v1/license/status
• GET /api/v1/nodes
• GET /api/v1/nodes/status
• GET /api/v1/usage
• GET /api/v1/usage/summary
• GET /api/v1/deployments/upgrades
• GET /api/v1/deployments/upgrade/{upgradeID}

These APIs are not a replacement for runtime metrics. They answer operational questions that metrics alone usually cannot answer, such as license posture, deployment progress, node visibility, and usage summaries.

Grafana provisioning

Enterprise deployments can provision Grafana organizations and dashboards based on deployment mode. The dashboard set is mode-aware, not a single fixed list for every Enterprise deployment.

Deployment-Mode Differences

SaaS and In-VPC deployments should not be monitored as if they expose the same operational surface.

Area	SaaS	In-VPC
Runtime metrics	Tenant-scoped operational view	Broader customer-controlled environment visibility
Node APIs	Node-level visibility is intentionally limited	Node usage and license-capacity views can be available
Platform-wide usage	Not generally exposed to tenants	Requires the relevant platform-wide usage permission
Dashboards	Common runtime dashboards plus SaaS tenant view	Common runtime dashboards plus platform and node views

The important design point is simple: the same AxonFlow runtime concepts apply, but visibility changes with deployment ownership.

Dashboard And API Pairings

The strongest enterprise operators pair dashboards with APIs:

• use runtime dashboards together with GET /api/v1/deployments/upgrade/{upgradeID} during rollouts
• use usage dashboards together with GET /api/v1/usage/summary when investigating cost or demand shifts
• use node and license views together in In-VPC mode when planning capacity
• use audit and execution views when investigating approval pauses, workflow failures, or governance events

That pairing gives teams a better incident story than static dashboard screenshots alone.

Deployment-Time Monitoring Workflow

During an upgrade:

1. verify GET /health
2. track upgrade state through the deployment-upgrade API when available
3. watch runtime metrics and error rates
4. confirm connector and provider paths still work
5. validate usage, license, and portal views after the rollout

Do not treat "upgrade request accepted" as proof that the platform is healthy. The useful standard is post-upgrade behavior across runtime, portal, provider, connector, and monitoring surfaces.

Alerting Priorities

Enterprise alerting should usually prioritize:

1. service unavailability
2. sustained request failure
3. connector or provider failure spikes
4. circuit-breaker trips
5. deployment failures or stalled upgrades
6. abnormal usage or license pressure

Next Steps

• Grafana Dashboard
• Token Usage
• Deployment Overview

Operational Readiness Checklist

Before relying on this page in a production rollout, pair it with the core operations docs:

• Deployment Mode Matrix for self-hosted, Evaluation, Enterprise, SaaS, and In-VPC fit
• Failure Modes And Recovery for degraded-provider, connector, approval, and runtime behavior
• Capacity Planning for sizing and growth signals
• Community vs Evaluation vs Enterprise for limits, support surfaces, and upgrade triggers