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

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.

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 (/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#

Airlock Metrics#

Browser Shield 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 bundled dashboard focuses on the core traffic, TLS interception, security
event, WebSocket, adaptive enforcement, and Scan API panels. Newer metric
families such as airlock and browser shield are exposed in Prometheus even if
you add your own panels for them.

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.