Metrics Reference#

Pipelock exposes Prometheus metrics at /metrics on the proxy listen port
(default 8888). All metric names are prefixed with pipelock_ (or
pipelock_learn_ for the observation-pipeline family).

Scrape Configuration#

# prometheus.yml
scrape_configs:
  - job_name: pipelock
    static_configs:
      - targets: ["pipelock:8888"]

For Kubernetes deployments using a PodMonitor:

apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: pipelock
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app: pipelock
  podMetricsEndpoints:
    - port: metrics
      path: /metrics
      interval: 30s

HTTP Request Metrics#

These track plain HTTP requests flowing through the proxy. HTTPS traffic
uses CONNECT tunnels (see below) and does not increment request counters.

CONNECT Tunnel Metrics#

In forward-proxy mode, HTTPS traffic uses CONNECT tunnels, which are opaque TCP
pipes that pipelock cannot inspect beyond the hostname. These are the primary
traffic metrics for forward-proxy deployments.

TLS Interception Metrics#

When tls_interception.enabled is true, pipelock performs TLS MITM on
CONNECT tunnels and records additional metrics for interception outcomes,
handshake latency, and per-request/response blocking.

Request Scanning Metrics#

Request body and header scanning detects secrets and prompt injection in POST/PUT/PATCH bodies,
form data, multipart uploads, and HTTP headers on forward-proxy traffic.

WebSocket Proxy Metrics#

WebSocket connections are upgraded from CONNECT tunnels when the target
matches a known WebSocket API host. Unlike opaque tunnels, pipelock can
inspect WebSocket frames for DLP and prompt injection.

Build Information#

Security Event Metrics#

These counters track enforcement actions. In a healthy deployment, all of
these should be zero or very low. Any sustained increase warrants
investigation.

Evidence Health Metrics#

These metrics summarize the live evidence pipeline. They are observability only:
they do not make traffic decisions, and a missing value means the evidence
health sampler is not measuring that fact in the current runtime.

The /stats endpoint also includes a nullable evidence_health object with
the same chain-head, sequence-gap, fsync, anchor, durability, and requirement
state. Treat null as "not measured," not as healthy.

Session Profiling Metrics#

Pipelock tracks per-session behavioral profiles. Sessions that deviate
from established patterns trigger anomalies and escalation events. Adaptive
enforcement can upgrade later requests based on that session state, so these
metrics are both observability and enforcement context.

Adaptive Enforcement Metrics#

Cross-Request Detection Metrics#

Cross-request detection tracks secrets split across multiple requests
using entropy budgets and fragment reassembly. These metrics indicate
active exfiltration attempts.

Airlock Metrics#

Request Policy Metrics#

Browser Shield Metrics#

Address Protection Metrics#

File Sentry Metrics#

Scan API Metrics#

The Scan API (/api/v1/scan) is an evaluation-plane endpoint for external
integrations. Disabled by default; set scan_api.listen to enable.

Reverse Proxy Metrics#

Mediation Envelope Metrics#

Signed Receipt Metrics#

Capture System Metrics#

Observation Pipeline Metrics (pipelock_learn_*)#

The observation pipeline records agent actions for the learn-and-lock behavioral
contract system. These metrics use the pipelock_learn_ prefix to keep alerting
on observation-pipeline health independent of core proxy alerts.

Conductor Metrics (enterprise build, pipelock_conductor_*)#

These metrics are only registered in the enterprise build
(-tags enterprise). They are absent from the standard binary. Each metric
name appears once in /metrics output regardless of how many followers are
enrolled; the per-follower audit transport emits into the same time series via
labels.

Counter Initialization#

Prometheus CounterVec metrics only appear in /metrics output after
their first increment. If you see a metric missing from a fresh instance,
it means that event type hasn't occurred yet, not that the metric is
broken. For example, pipelock_requests_total won't appear if all traffic
is HTTPS (CONNECT tunnels).

Observability Export#

Prometheus and JSON stats#

The /metrics endpoint serves all registered Prometheus metrics. A JSON
summary is available at /stats on the same port:

curl http://localhost:8888/stats | jq .

{
  "uptime_seconds": 3600.5,
  "requests": {
    "total": 42,
    "allowed": 40,
    "blocked": 2,
    "block_rate": 0.0476
  },
  "tunnels": 1523,
  "websockets": 0,
  "top_blocked_domains": [
    {"name": "evil.com", "count": 2}
  ],
  "top_scanners": [
    {"name": "dlp", "count": 2}
  ],
  "sessions": {
    "active": 3,
    "anomalies": 0,
    "escalations": 0,
    "top_anomalies": []
  },
  "agents": {
    "claude-code": {"allowed": 35, "blocked": 1, "tunnels": 1200},
    "cursor": {"allowed": 5, "blocked": 1, "tunnels": 323}
  },
  "evidence_health": null
}

The agents field is omitted when no agent-scoped traffic has been recorded.

OTLP export#

The emit.otlp configuration sends audit events as OTLP log records to
an OpenTelemetry-compatible collector. The endpoint is /v1/logs (not
/v1/traces). Pipelock does not currently emit distributed traces; all OTLP
export is log-based. Events are structured as LogRecord bodies with
pipelock.instance and event-specific key-value attributes.

See the SIEM Integration Guide for collector
configuration and the OTLP attribute schema.

SIEM / webhook events and signing#

Audit events emitted via webhook, syslog, and OTLP are not
individually signed. They are structured log records and are not
cryptographically authenticated at the transport layer.

Signed attestation is a separate feature: the flight recorder emits
Ed25519-signed, hash-chained action receipts stored as JSONL on disk.
Action receipts and SIEM events record the same enforcement decisions but
serve different purposes — receipts provide tamper-evident proof for
auditors and compliance workflows; SIEM events are for real-time alerting
and analysis. See receipt-verification.md
for receipt verification, and flight-recorder.md
for the chain model.

Grafana Dashboard#

An importable Grafana dashboard is included at
configs/grafana-dashboard.json.
Import it via Dashboards → Import → Upload JSON file in Grafana.

The bundled dashboard covers core traffic, TLS interception, security
event, WebSocket, adaptive enforcement, and Scan API panels. Newer families
(airlock, browser shield, observation pipeline, conductor) are registered
in Prometheus; operators can add panels for them using the metric names
in this document.

Alert Rules#

Example Prometheus alert rules are available at
examples/prometheus/pipelock-alerts.yaml.
See the SIEM Integration Guide for
Alertmanager routing and automated response patterns.

Go Runtime Metrics#

The standard Go runtime and process collectors are also registered on the
same Prometheus registry. These expose go_memstats_heap_alloc_bytes,
go_goroutines, process_resident_memory_bytes, and related metrics —
useful for capacity planning and for comparing against RSS in benchmarks.