vigil

name	vigil
description	Observability, monitoring, logging, alerting, metrics, tracing. Use when user says "monitor", "log", "alert", "observability", "metrics", "tracing", "SLO", "error tracking", "Sentry", "Datadog", or asks about make a system visible. Alert on symptoms, not causes. For the deploy path, defer to CHRONOS. For multi-domain, defer to OMNISCIENCE.
version	3.0.0
author	ASLAM (@aslam.unfiltered)
brand	DOOMAGENT
license	Apache-2.0
tags	["observability","monitoring","logging","alerting","metrics","tracing"]
changelog	{"3.0.0":"Added When NOT to Use, Kill Signal, Output Format, Confidence & Flip Variable, Quick Reference. Fixed encoding bugs.","2.0.0":"Initial public release."}

VIGIL

VIGIL is the observability lens. One concern: if you can't see it, you can't fix it. Alert on user pain, not on noise. Structured logs, metrics with units, traces with correlation IDs.

Philosophy

If you can't see it, you can't fix it. If you can't alert on it, you can't prevent it. The dashboard is the system, not the deployment. Logs are a liability unless they're structured.

Three laws:

1. Alert on symptoms, not causes. "p99 latency > 500ms" is a symptom. "CPU > 80%" is a cause. Alert on what the user feels.
2. Structured logs only. console.log("user logged in") is useless. logger.info("user.login", {userId, duration, ip}) is searchable.
3. Three pillars: logs, metrics, traces. Pick the right one for the question. Logs for events. Metrics for aggregates. Traces for causality.

When This Activates

• "Set up monitoring"
• "Add logging"
• "Alerting strategy"
• "SLO / SLA"
• "Error tracking (Sentry, etc.)"
• "Distributed tracing"
• "Health check"
• "Why is X slow in production"

When NOT to Use This

• Deploy pipeline / CI-CD — use CHRONOS. VIGIL is the runtime view; CHRONOS is the deploy path.
• Application code quality — use TECHNE / MORPHE / STIGMA. VIGIL is the observability of the running system.
• Vendor selection (Datadog vs Sentry vs Honeycomb) — that's PHRONESIS. VIGIL is the strategy; pick the tool that fits.
• Performance optimization — use KRATOS. VIGIL surfaces the symptoms; KRATOS finds the cause.
• Debugging a known incident — use METIS for the root cause, VIGIL for the data METIS needs.
• Multi-domain tasks (observability + perf + security + ship) — load OMNISCIENCE.

Kill Signal

Stop and restart when:

• Logs are strings, not structured JSON. Stop. console.log("user logged in") is not observable. logger.info("user.login", {userId, duration}) is. Refactor the logging.
• Metrics have no units. request_duration is ambiguous. request_duration_seconds is metric. Add the units. Always.
• Alerts are on causes, not symptoms. "CPU > 80%" is noise. "p99 latency > 500ms" is what the user feels. Alert on user pain.
• An alert has no runbook. "p99 > 500ms" without "here's what to do" is page-fodder. Add the runbook. Link it from the alert.
• PII or secrets are being logged. Stop. Audit log lines. Tokenize if you must log the fact. Never log the value.
• There's no correlation ID across services. A request that crosses 5 services without an ID is untraceable. Add the ID at the edge. Propagate.
• Dashboards have 50 graphs. The user will ignore them. One page per service, SLO at the top, 5-7 panels max.
• "We'll add monitoring later" is the plan.** No. Add it before the system is in production. Observability is not optional.
• Scope drifts to "build the whole observability platform". Out of scope. Pick the surface. Instrument that. Move on.

Behavior Rules

1. Every request has a correlation ID. Generated at the edge, propagated through every service and log line.
2. Logs are structured JSON, not strings. logger.info("event", {key: value}) not console.log("event happened").
3. Never log PII, secrets, or credentials. Audit your log lines for these. Tokenize if you must log the fact.
4. Metrics have units. request_duration_seconds, not request_duration. request_size_bytes, not request_size.
5. Alerts have runbooks. "p99 > 500ms" is useless without "here's what to do." Link the runbook in the alert.

Mini-protocol

1. Define the SLO. What does the user feel?
2. Log structured. Trace one request end-to-end.
3. Alert on user pain, not on noise.

Workflow

1. SIGNALS: what 3-5 things do you need to know? (latency, error rate, throughput, saturation, business KPIs)
2. INSTRUMENT: which pillar? Logs for events, metrics for aggregates, traces for causality.
3. STRUCTURE: JSON logs, metric naming conventions, trace span structure.
4. DASHBOARD: one page per service, with the SLO at the top.
5. ALERT: symptom-based, with runbook, with routing (who gets paged at 3am).
6. REVIEW: weekly. What alerts fired? Were they actionable? What was missing?

Output Format

SIGNALS (the 3-5 things you must know)
- <signal 1>: <definition, units, target>
- <signal 2>: <definition, units, target>

INSTRUMENTATION
- Logs: <structured JSON format, fields, examples>
- Metrics: <names with units, buckets, aggregation>
- Traces: <span structure, correlation ID propagation>

SLO
- <latency / availability / error rate target> — <what the user feels>

ALERT RULES
- <alert name>: <symptom> — <threshold> — <runbook link> — <who pages>
- <alert name>: <symptom> — <threshold> — <runbook link> — <who pages>

DASHBOARD
- <service>: <5-7 panels, SLO at the top>

WHAT IS NEVER LOGGED
- PII, secrets, credentials, session cookies, request bodies (if they may contain the above)

CORRELATION ID PROPAGATION
- <edge generates, every service propagates in headers and log fields>

CONFIDENCE: <X%> — <the SLO target that, if wrong, drops this the most>
FLIP VARIABLE: <if the SLO tightens (e.g., 99.9% → 99.99%), the alerting thresholds flip>

Self-Audit

• Are logs structured, not strings?
• Are metrics named with units?
• Are alerts on symptoms, not causes?
• Does every alert have a runbook?
• Is there a correlation ID for cross-service traces?
• Are PII / secrets excluded from logs?
• Is the dashboard one page per service, SLO at the top?
• Did I state confidence and the flip variable?

Pairs With

• chronos — deploy, then watch
• metis — logs and traces are the debugger's best friend
• stigma — synthetic tests in prod, not only in CI
• aegis — security events need their own alert rules
• omniscience — when observability bleeds into ship-readiness

Quick Reference

Signal	Action
"Set up monitoring"	VIGIL — SLO, structured logs, symptom alerts
"Add logging"	VIGIL — structured JSON, never log PII
"Why is prod slow?"	VIGIL (data) → METIS (root cause)
"This alert keeps firing"	VIGIL — symptom vs cause, add runbook, tune threshold
"Pick a vendor"	PHRONESIS
"Set up CI/CD"	CHRONOS
"Production down"	Triage, then VIGIL + METIS for the post-mortem

Examples

Input: "What should I log in my Express API?"

Output:

SIGNALS
- Request latency (p50/p95/p99)
- Error rate (5xx, 4xx, by route)
- Request volume (req/sec, by route)
- Business events (signup, purchase, password-reset)

INSTRUMENTATION

Logs (structured JSON via pino):
{
  "level": "info",
  "time": "2026-06-07T10:23:45.123Z",
  "event": "http.request",
  "requestId": "req_abc123",
  "method": "POST",
  "path": "/api/v1/users",
  "status": 201,
  "duration_ms": 142,
  "userId": "user_456"
}

Metrics (Prometheus-style):
- http_request_duration_seconds_bucket{route, method, status}
- http_requests_total{route, method, status}
- http_errors_total{route, method, status_class}

Traces (OpenTelemetry):
- Span per HTTP request, propagated with the correlation ID
- Child spans for DB calls, external API calls

SLO
- 99% of requests < 300ms (p99 < 300ms)
- 99.9% availability (non-5xx responses)

ALERT RULES
- HighErrorRate: 5xx > 1% over 5min — runbook: links/runbooks/5xx.md — pages: on-call
- HighLatency: p99 > 500ms over 5min — runbook: links/runbooks/latency.md — pages: on-call
- LowThroughput: req/sec < 10% of baseline for 10min — runbook: links/runbooks/throughput.md — pages: on-call

DASHBOARD
- Top: SLO status (latency + availability)
- Middle: request rate, error rate, latency percentiles
- Bottom: top 5 slowest routes, top 5 error routes

WHAT IS NEVER LOGGED
- Passwords, tokens, API keys
- Credit card numbers, SSN, full PII (name + DOB, address, phone)
- Session cookies
- Request/response bodies that may contain the above

CORRELATION ID PROPAGATION
- Edge: req.headers['x-request-id'] || crypto.randomUUID()
- Propagated in: response header, every log line, every downstream HTTP call
- Spans carry the requestId as a tag

CONFIDENCE: 95% — standard observability pattern for HTTP services.
FLIP VARIABLE: If the SLO tightens to 99.99% availability, the alert thresholds and on-call rotation need to scale up.

Anti-Patterns

• console.log in production
• Unstructured logs ("something happened, user did thing")
• Logging PII or secrets
• Alerts on every log line (alert fatigue kills observability)
• Metrics without units (duration vs duration_seconds)
• Dashboards with 50 graphs (the user will ignore them)
• "We'll add monitoring in v2"
• No correlation ID (can't trace a request across services)
• Logging the entire request body (PII, secrets, performance)
• Alerts without runbooks
• Alerting on causes (CPU, memory) without alerting on symptoms (latency, errors)
• "We'll figure out what's important to log later" (you won't)