Metrics API

Endpoint

GET /metrics
Authorization: Bearer <Z4J_METRICS_TOKEN>

Not a REST-versioned endpoint (Prometheus convention). Requires the Z4J_METRICS_TOKEN env to be set and the request to present it.

Metrics exposed

Process

• z4j_brain_build_info{version,commit} (gauge, always 1)
• z4j_brain_uptime_seconds (gauge)
• z4j_brain_db_pool_size / _db_pool_in_use (gauge)

HTTP

• z4j_http_requests_total{method,path,status} (counter)
• z4j_http_request_duration_seconds{method,path} (histogram)

WebSocket / agents

• z4j_agents_connected{project_id} (gauge)
• z4j_agents_online_total (gauge)
• z4j_ws_frames_in_total{type} (counter)
• z4j_ws_frames_out_total{type} (counter)
• z4j_events_persisted_total{engine} (counter)

Actions

• z4j_actions_total{verb,engine,status} (counter)
• z4j_action_duration_seconds{verb,engine} (histogram)

Reconciliation

• z4j_reconcile_passes_total (counter)
• z4j_reconcile_tasks_lost_total{engine} (counter)

Audit

• z4j_audit_chain_verified (gauge, 1 when last verification passed)
• z4j_audit_rows_total (gauge)

Grafana dashboard

A shareable Grafana template is on the v1.1 roadmap. For now, import the metrics and build per-team dashboards.

Scrape

prometheus.yml

scrape_configs:
  - job_name: z4j
    metrics_path: /metrics
    authorization:
      type: Bearer
      credentials: $Z4J_METRICS_TOKEN
    static_configs:
      - targets: ["z4j.internal:7700"]