mav-bp-operability
Operability standards — logging, alerting, and observability as one discipline. Maverick's opinionated rules: error-only log levels (no info), structured JSON logs, alert-at-the-boundary, correlation
SKILL.mdskills/mav-bp-operability/SKILL.md
GitHubOperability Standards
Logging, alerting, and observability as one discipline: record what happened, demand attention when it matters, and make internal state diagnosable from outside. Logs record; alerts interrupt; metrics and traces correlate.
Maverick's Rules
Logging
- No
infolevel. If it matters in production it iswarnorerror; if it only helps during development it isdebug. Info-level logging is a noise dumping ground — this is Maverick's most-fought deviation from default LLM behaviour; hold the line. - Structured JSON only, to an aggregation service (stdout is fine when
the platform ships it — container log drivers, CloudWatch agents).
Required fields:
timestamp,level,message,service,context(putcorrelationIdand error details insidecontext). - Log errors once, at the boundary — never log-and-rethrow at every layer. Never log PII, tokens, or secrets.
- One logger module per service;
console.lognever ships.
Alerting
- Alert only on unrecoverable failures and threshold breaches, from the outermost error boundary (global handlers, health checks) — never inside low-level functions, loops, or retries.
- Severities are
critical(wake someone) /high(within the hour) /warning(next business day). Alert severities are not log levels — do not map one onto the other. - Every alert carries: severity, service, environment, impact-stating message ("checkout is down", not "error occurred"), scope, and a log pointer. Always log first, then alert.
- Deduplicate: first alert wins, cooldown window suppresses repeats.
- Frontend code never calls alerting services directly — report to an error-reporting service or a backend endpoint.
Observability
- Three pillars share identifiers: the trace/correlation id in a metric spike must find the requests and their logs.
- Request-driven services expose RED metrics (rate, errors, duration); no high-cardinality metric labels (user ids belong in traces/logs).
- Liveness checks the process only; readiness checks dependencies — conflating them causes cascading restarts.
- Use a standard instrumentation library (OpenTelemetry or equivalent), never hand-rolled collection.
Project Implementation Lookup
Check docs/maverick/skills/logging/SKILL.md,
docs/maverick/skills/alerting/SKILL.md, and
docs/maverick/skills/observability/SKILL.md for project-specific
implementations (library, transport, service names). If present, they
win on specifics. If missing, proceed with these standards and note the
gap in your summary — do not trigger skill generation mid-task.
Detecting Operability Issues in Code Review
| Pattern | Issue | Fix |
|---|---|---|
console.log(...) |
Unstructured, not centralised | Replace with logger.debug(...) or remove |
logger.info(...) |
Creates noise | Evaluate: is it warn, error, or debug? |
logger.error('Error') |
No context | Add contextual metadata |
catch (err) { logger.error(err) } then re-throws |
Duplicate logging | Log at the boundary only |
| Logging PII/secrets | Security risk | Mask or remove |
| Different loggers/alerters in different files | Inconsistency | Use single logger/alerter module |
try/catch that silently swallows |
Lost errors | Log or re-throw |
| Fatal error with no alert | Silent failure | Add alert at the error boundary |
| Alert inside a loop or retry | Alert flood | Move alert outside loop, add dedup |
| Alert with no context | Unactionable | Add service, error, scope, log pointer |
| Alert on expected conditions | Alert fatigue | Remove — only alert on unexpected failures |
| Alert but no log | Missing investigation trail | Always log before alerting |
| Frontend calling alerting service directly | Security risk | Route through backend API |
| No trace context propagation on outbound calls | Broken traces | Add middleware for automatic propagation |
| Liveness probe checking all dependencies | Cascading restarts | Liveness: process only; readiness: deps |
| High-cardinality metric labels (user/request ids) | Metric explosion, cost | Ids belong in traces and logs, not labels |
| No correlation ID in log entries | Cannot link logs to traces | Include trace ID in structured log context |
| SLO defined but not measured | False confidence | Instrument the SLI and track the target |