# Case catalogue

The cases that come up in GFiber services and the level each one takes. If a case is not here, run the decision list in [levels.md](levels.md) and add a row.

## Work intake and results

| Case | Level | Note |
|------|-------|------|
| Request, batch or message arrived | INFO | counts and the values that identify the scope, such as alarm names, severities, OLT, HUT; no payload and no id list |
| Batch finished | INFO if ok, ERROR otherwise | one summary line with in, out, duration and status, written from a defer registered before any recover so a panic still produces it |
| Result of one work item | INFO | one per item, with its identifier and outcome; this is the line support greps for, and the one line that must never be demoted |
| Payload of the work item | DEBUG | or behind on-demand troubleshooting |
| Decision that ends the item | INFO | only when it is not already visible in that item's result message |
| Intermediate lookup or filter result | DEBUG | log the count at INFO if it matters, the members at DEBUG |
| Anything inside a loop over domain objects | DEBUG | plus one count after the loop |

## Rejections and failures

| Case | Level | Note |
|------|-------|------|
| Input malformed, null or failed validation | WARN | carry the identifiers that survived parsing, and the body size |
| Rejected for capacity or backpressure | WARN | one line per rejected request, never per item |
| No handler or policy matched the work | WARN | carry the identifiers, because no result line will be written |
| Upstream call failed, will be retried | DEBUG | the attempt is not yet a failure |
| Upstream call failed after retries | ERROR | carry the identifiers and the step that stopped |
| Some items succeeded, some failed | ERROR | on the summary line, with the split |
| Panic recovered | ERROR | log the recovered value and the stack, and keep serving |

## Service lifecycle

| Case | Level | Note |
|------|-------|------|
| Started, listeners bound, dependencies resolved | INFO | a handful of lines, once per process |
| Effective configuration | DEBUG | never secrets, tokens or credentials |
| Graceful shutdown | INFO | |
| Cannot start at all | FATAL | the only place FATAL is allowed |
| Database connection established | INFO | once at startup; per query is DEBUG |

## Background work

| Case | Level | Note |
|------|-------|------|
| Scheduled tick that found nothing to do | DEBUG | a tick every few seconds at INFO is one of the cheapest ways to burn retention |
| Scheduled tick that did work | INFO | one line with counts, not one per item |
| Kafka batch consumed | INFO | one summary per batch, same shape as an HTTP batch |
| One Kafka message processed | DEBUG | the per-item result line already covers what support needs |
| Message that cannot be parsed | ERROR | carry the message key and raise a metric; it will never parse, so it is lost work |
| Consumer rebalance or lag | none | leave it to the client library and to metrics |

## Keep out

| Case | Level | Note |
|------|-------|------|
| Health, liveness and readiness probes | none on success | probe traffic is constant; log only a failing probe |
| Every outbound HTTP request and response | DEBUG | rates and durations belong in metrics |
| Upstream returned an empty result | DEBUG | unless it changes the outcome, and then it belongs in the item's result message |
| Third-party library output | set it explicitly | do not let a dependency inherit DEBUG in production |
| Secrets, tokens, passwords | never | at any level |
| ONT serial, account id, hostname | not at INFO | on high-volume paths; fine in a bounded projection or at DEBUG |

If a line has to be INFO and is still too frequent, sample it: log one in N with the count of what was skipped. Demoting it to DEBUG removes it from production entirely, which is usually not the intent.

## Reference implementations

Read these before writing a new one; both were reviewed against this policy.

| What | Where |
|------|-------|
| Per-batch summary line, `key=value`, INFO on ok and ERROR otherwise | `gfiber-policy-executor`, `pkg/faultstatus/stats.go` |
| Per-alarm result line, the one support greps for | `gfiber-policy-executor`, `pkg/policies/executor.go` |
| Ingress line with counts, ids on a DEBUG companion | `gfiber-policy-executor`, `pkg/policies/executor.go` |
| Per-item result line from a defer, covering every failure path | `gfiber-ticketing-proxy`, `pkg/ticket/executor.go` |
| Rejection lines with a fixed reason vocabulary plus a counter | `gfiber-ticketing-proxy`, `pkg/ticket/routes.go` |