Monitoring & Observability

RelayCore provides Prometheus-native metrics, structured audit logs, SSE real-time event streams, and health status snapshots — ready for integration with existing monitoring stacks.

Metrics Endpoints

Endpoint	Format	Description
`GET /api/v1/metrics`	JSON	Structured metrics snapshot
`GET /api/v1/metrics/prometheus`	Prometheus text	Standard Prometheus scrape format
`/_relay/metrics`	JSON	In-proxy embedded metrics
`/_relay/metrics/prometheus`	Prometheus text	Embedded Prometheus format

Core Metrics

Flow Metrics

Metric	Type	Description
`relaycore_flows_total`	Counter	Total flows processed
`relaycore_flows_in_memory`	Gauge	Current flows in memory
`relaycore_flows_dropped`	Counter	Flows dropped due to backpressure
`relaycore_flow_events_lagged_total`	Counter	Event broadcast lag events

Intercept Metrics

`relaycore_intercepts_pending`	Gauge	Pending intercepts awaiting UI
`relaycore_oldest_intercept_age_ms`	Gauge	Oldest unhandled intercept age
`relaycore_ws_pending_messages`	Gauge	Pending WebSocket messages

Rule & Script Metrics

`relaycore_rule_exec_errors`	Counter	Rule execution errors
`script_hook_duration_us{hook}`	Histogram	Per-hook execution duration (µs)
`script_hook_invocations_total{hook}`	Counter	Cumulative hook invocations
`script_hook_errors_total{hook}`	Counter	Cumulative hook errors
`script_fetch_total{target,status}`	Counter	relay.fetch call count

Audit Metrics

`relaycore_audit_events_total`	Counter	Total audit events
`relaycore_audit_events_failed`	Counter	Failed audit recordings
`relaycore_audit_events_lagged_total`	Counter	Audit broadcast lag events

Prometheus Configuration

# prometheus.yml
scrape_configs:
  - job_name: "relaycore"
    static_configs:
      - targets: ["127.0.0.1:8082"]
    metrics_path: "/api/v1/metrics/prometheus"
    scrape_interval: 15s

Health Check

# Status snapshot
curl http://127.0.0.1:8082/api/v1/status

# Response
{
  "phase": "Running",
  "is_running": true,
  "port": 8080,
  "uptime_seconds": 3600,
  "last_error": null
}

Lifecycle phases: Created → Starting → Running → Stopping → Stopped (Failed for crashes)

SSE Event Stream

GET /api/v1/events pushes real-time updates via Server-Sent Events:

Event Type	Description
`flow`	New or updated flow
`ws-message`	WebSocket message update
`http-body`	HTTP request/response body update
`audit`	Audit event (rule change, intercept, etc.)
`lifecycle`	Proxy lifecycle change
`lagged`	Event channel lag warning

# Subscribe via curl
curl -N http://127.0.0.1:8082/api/v1/events

# JavaScript EventSource
const es = new EventSource("http://127.0.0.1:8082/api/v1/events");
es.addEventListener("flow", (e) => console.log(JSON.parse(e.data)));

Audit System

Audit logs track all control-plane operations and cannot be disabled:

Event Type	Trigger
`rule_changed`	Rule add/delete/modify
`intercept_resolved`	Intercept resolved (continue/drop/modify)
`script_reloaded`	Script loaded or reloaded
`policy_updated`	Policy changed (redaction etc.)

Audit actors: runtime / http / tauri / probe / cli

# Query recent 50 audit events
curl "http://127.0.0.1:8082/api/v1/audit?limit=50"

# Filter by type
curl "http://127.0.0.1:8082/api/v1/audit?kind=rule_changed&limit=20"

Grafana Integration

The benchmarks/grafana/ directory contains a ready-to-use Grafana Dashboard JSON. Pair with Prometheus for a complete monitoring panel.