Troubleshooting by symptom
Start by recording the component revision, relevant configuration names, time range, structured refusal code, and last known successful boundary. Keep private keys, session tokens, and sensitive raw observations out of shared reports.
| Symptom | Guide |
|---|---|
| Agent fails to start or reload configuration | Agent foundation |
| Agent cannot enroll or certificate fails | Enrollment and TLS |
| Accepted events do not appear | Ingestion and storage |
| Consumer lag keeps growing | Lag and state recovery |
| Rules do not fire or incidents do not appear | Detection |
| Events or detections look duplicated | Duplicates |
| API unavailable, forbidden, or session lost | API and migration |
| Spool grows, collector missing, frontend cannot connect | Unimplemented paths |
A successful TLS handshake, durable ACK, committed writer position, query result, detection, and alert are different milestones. Use the event lifecycle to decide which one stopped advancing.
Do not disable verification, retimestamp records, skip offsets, delete state, or widen security limits before understanding the cause. The existing observability surfaces are designed to make those boundaries visible.
Source evidence
Reviewed against the source baseline. Seagull-backend-v2/internal/ingest/http.go · Seagull-backend-v2/internal/broker/consumer.go · Seagull-agent-v2/cmd/seagull-agent/main.go.