Metrics Reference#

Pipelock exposes Prometheus metrics at /metrics on the proxy listen port
(default 8888). All metric names are prefixed with pipelock_.

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

Session Profiling Metrics#

Pipelock tracks per-session behavioral profiles. Sessions that deviate
from established patterns trigger anomalies and escalation events. In v1,
escalation is observability-only (scoring and event emission); it does not
automatically change enforcement behavior (warn vs block).

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.

Scan API Metrics#

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

Address Protection Metrics#

File Sentry Metrics#

Adaptive Enforcement Metrics#

Reverse Proxy Metrics#

Capture System Metrics#

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

JSON Stats Endpoint#

Pipelock also exposes a JSON summary at /stats on the same port. This
provides a human-readable snapshot without needing Prometheus:

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

The agents field is omitted when no agent-scoped traffic has been recorded. Fresh deployments or single-profile setups without agent configuration will not include this key.

Grafana Dashboard#

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

The dashboard covers all 45 metric families across ten sections: fleet
overview, agent status table, traffic, connection details, TLS interception,
security events, WebSocket proxy, cross-request detection, adaptive
enforcement, and Scan API.

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.