firstsignal 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. firstsignal-0.2.0/LICENSE +21 -0
  2. firstsignal-0.2.0/PKG-INFO +303 -0
  3. firstsignal-0.2.0/README.md +270 -0
  4. firstsignal-0.2.0/firstsignal/__init__.py +4 -0
  5. firstsignal-0.2.0/firstsignal/__main__.py +6 -0
  6. firstsignal-0.2.0/firstsignal/_compat.py +27 -0
  7. firstsignal-0.2.0/firstsignal/ai.py +163 -0
  8. firstsignal-0.2.0/firstsignal/analyzer.py +143 -0
  9. firstsignal-0.2.0/firstsignal/cli.py +477 -0
  10. firstsignal-0.2.0/firstsignal/collectors.py +131 -0
  11. firstsignal-0.2.0/firstsignal/html.py +28 -0
  12. firstsignal-0.2.0/firstsignal/memory.py +226 -0
  13. firstsignal-0.2.0/firstsignal/parsing.py +119 -0
  14. firstsignal-0.2.0/firstsignal/patterns.py +267 -0
  15. firstsignal-0.2.0/firstsignal/redact.py +47 -0
  16. firstsignal-0.2.0/firstsignal/reporter.py +203 -0
  17. firstsignal-0.2.0/firstsignal/settings.py +82 -0
  18. firstsignal-0.2.0/firstsignal/viewer.html +482 -0
  19. firstsignal-0.2.0/firstsignal/watch.py +149 -0
  20. firstsignal-0.2.0/firstsignal.egg-info/PKG-INFO +303 -0
  21. firstsignal-0.2.0/firstsignal.egg-info/SOURCES.txt +38 -0
  22. firstsignal-0.2.0/firstsignal.egg-info/dependency_links.txt +1 -0
  23. firstsignal-0.2.0/firstsignal.egg-info/entry_points.txt +3 -0
  24. firstsignal-0.2.0/firstsignal.egg-info/requires.txt +11 -0
  25. firstsignal-0.2.0/firstsignal.egg-info/top_level.txt +1 -0
  26. firstsignal-0.2.0/pyproject.toml +75 -0
  27. firstsignal-0.2.0/setup.cfg +4 -0
  28. firstsignal-0.2.0/tests/test_ai.py +101 -0
  29. firstsignal-0.2.0/tests/test_analyzer.py +102 -0
  30. firstsignal-0.2.0/tests/test_cli.py +138 -0
  31. firstsignal-0.2.0/tests/test_collectors.py +127 -0
  32. firstsignal-0.2.0/tests/test_compat.py +57 -0
  33. firstsignal-0.2.0/tests/test_html.py +46 -0
  34. firstsignal-0.2.0/tests/test_memory.py +146 -0
  35. firstsignal-0.2.0/tests/test_packs.py +111 -0
  36. firstsignal-0.2.0/tests/test_parsing.py +44 -0
  37. firstsignal-0.2.0/tests/test_redact.py +32 -0
  38. firstsignal-0.2.0/tests/test_reporter.py +77 -0
  39. firstsignal-0.2.0/tests/test_settings.py +57 -0
  40. firstsignal-0.2.0/tests/test_watch.py +235 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 AutoShiftOps
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,303 @@
1
+ Metadata-Version: 2.4
2
+ Name: firstsignal
3
+ Version: 0.2.0
4
+ Summary: Read-only incident triage for logs: journalctl, Docker, Kubernetes and files, mapped to the Four Golden Signals.
5
+ Author: AutoShiftOps
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://firstsignal.autoshiftops.com/
8
+ Project-URL: Repository, https://github.com/AutoShiftOps/firstsignal
9
+ Project-URL: Issues, https://github.com/AutoShiftOps/firstsignal/issues
10
+ Keywords: incident-response,sre,logs,triage,observability,kubernetes
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: System Administrators
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: System :: Logging
20
+ Classifier: Topic :: System :: Monitoring
21
+ Requires-Python: >=3.10
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: rich>=13.0
25
+ Requires-Dist: tomli>=2.0; python_version < "3.11"
26
+ Provides-Extra: dev
27
+ Requires-Dist: pytest>=7.4; extra == "dev"
28
+ Requires-Dist: pytest-cov>=4.1; extra == "dev"
29
+ Requires-Dist: ruff>=0.6; extra == "dev"
30
+ Requires-Dist: bandit>=1.7; extra == "dev"
31
+ Requires-Dist: build>=1.0; extra == "dev"
32
+ Dynamic: license-file
33
+
34
+ <p align="center">
35
+ <a href="https://firstsignal.autoshiftops.com/"><img src="https://raw.githubusercontent.com/AutoShiftOps/firstsignal/main/docs/brand/firstsignal-banner.png" alt="firstsignal: the loudest error is rarely the first one" width="820"></a>
36
+ </p>
37
+
38
+ # firstsignal
39
+
40
+ > Formerly **incopilot**. The `incopilot` command, `INCOPILOT_*` variables, `incopilot.toml` and `~/.incopilot` history still work for one release.
41
+
42
+ Read-only incident triage for logs. One command collects logs from **systemd, Docker, Kubernetes or a file**, maps what it finds to the **Four Golden Signals**, and writes a report with the order things went wrong and safe checks to run next.
43
+
44
+ [![CI](https://github.com/AutoShiftOps/firstsignal/actions/workflows/ci.yml/badge.svg)](https://github.com/AutoShiftOps/firstsignal/actions/workflows/ci.yml)
45
+ ![python](https://img.shields.io/badge/python-3.10%E2%80%933.13-3776AB)
46
+ ![license](https://img.shields.io/badge/license-MIT-blue)
47
+
48
+ **Correlate and explain, never auto-act.** firstsignal never changes the systems it reads. It works offline with no account and no agent. An AI hypothesis is available if you bring your own key, and it is off by default.
49
+
50
+ Website: https://firstsignal.autoshiftops.com/
51
+
52
+ ## Quick start
53
+
54
+ ```bash
55
+ pip install git+https://github.com/AutoShiftOps/firstsignal
56
+
57
+ # try it on the bundled example incident
58
+ git clone https://github.com/AutoShiftOps/firstsignal && cd firstsignal
59
+ firstsignal file --path examples/checkout-incident.log --packs core,nginx
60
+ cat out/report.md
61
+ ```
62
+
63
+ ```text
64
+ Overall severity: CRITICAL
65
+ 15 lines analyzed, 13 matched, 2 filtered as noise
66
+
67
+ Finding Signal Severity Count
68
+ Out of memory saturation critical 1
69
+ HTTP 5xx responses errors high 5
70
+ Timeouts latency high 4
71
+ Connection limit reached saturation high 2
72
+ ...
73
+ First to appear: Slow operations
74
+ ```
75
+
76
+ The report shows that slow queries came first, then the connection pool filled, then timeouts and 5xx, and the out-of-memory kill came last. That ordering is the point: the loudest error is often not the cause.
77
+
78
+ ## See it as a dashboard
79
+
80
+ ```bash
81
+ firstsignal file --path examples/checkout-incident.log --html
82
+ # open out/report.html in a browser
83
+ ```
84
+
85
+ `--html` writes a self-contained `report.html`: overall severity, the Four Golden Signals, a timeline of when each problem first appeared, findings, and the checks to run next. Nothing is loaded from a server and the report data stays in the file.
86
+
87
+ The terminal output already shows severity, golden signals, findings and the order of first appearance. Use `--html` when you need to share the result with people who were not at the terminal, for example in an incident channel or a postmortem.
88
+
89
+ A [live example](https://firstsignal.autoshiftops.com/viewer.html) is on the website.
90
+
91
+ ## It remembers
92
+
93
+ Every run with findings is remembered as a fingerprint: which patterns fired, in what order, on which target. The next time something similar happens, firstsignal tells you, along with what fixed it last time.
94
+
95
+ ```text
96
+ Seen before
97
+ 3f9a1c2e 12 days ago on prod/deploy/api (100% similar, critical)
98
+ Fix noted: raised DB pool size from 10 to 30, added index on orders.customer_id
99
+
100
+ Remembered as 8b21d0aa. When it is fixed: firstsignal history note 8b21d0aa "what fixed it"
101
+ ```
102
+
103
+ ```bash
104
+ firstsignal history list # what is remembered
105
+ firstsignal history note 8b21d0aa "what fixed it"
106
+ firstsignal history forget 8b21d0aa
107
+ ```
108
+
109
+ - **Local and private.** History is one file, `~/.firstsignal/history.jsonl`, readable only by you. Set `FIRSTSIGNAL_HISTORY` or `--history FILE` to move it, for example into a repo your team shares.
110
+ - **No log text is stored.** Only pattern names, counts, the target, the time and your note.
111
+ - **Matching is deterministic.** The same two incidents always get the same score. No model is involved.
112
+ - Re-running during the same incident updates one record instead of creating many. `--no-history` turns it off.
113
+
114
+ ## Sources
115
+
116
+ ```bash
117
+ # systemd journal
118
+ firstsignal journal --unit nginx --since "30 min ago"
119
+
120
+ # Docker container (stdout and stderr)
121
+ firstsignal docker --container my-api --since 1h
122
+
123
+ # Kubernetes: a pod, a workload, or a label selector
124
+ firstsignal k8s --pod deploy/api -n prod --since 30m
125
+ firstsignal k8s -l app=api -n prod --previous # the container that just crashed
126
+
127
+ # a file, a .gz file, or stdin
128
+ firstsignal file --path /var/log/app.log
129
+ kubectl logs deploy/api | firstsignal file --path -
130
+
131
+ # several sources as one timeline
132
+ firstsignal bundle --unit nginx --container my-api --pod deploy/api -n prod
133
+ ```
134
+
135
+ ## Watch it live
136
+
137
+ ```bash
138
+ firstsignal watch k8s --pod deploy/api -n prod
139
+ firstsignal watch docker --container my-api --window 10
140
+ firstsignal watch file --path /var/log/app.log
141
+ ```
142
+
143
+ ```text
144
+ Watching prod/deploy/api: last 5 min of logs, checked every 15s. Ctrl+C to stop.
145
+ 09:41:12 NEW high Connection limit reached (saturation) x2
146
+ 09:41:12 SEVERITY none -> high
147
+ 09:41:31 NEW critical Out of memory (saturation) x1
148
+ 09:41:31 SEVERITY high -> critical
149
+ 09:41:31 SEEN BEFORE 3f9a1c2e, 12 days ago on prod/deploy/api (80% similar). Fix noted: raised DB pool size
150
+ 09:52:40 CLEARED Connection limit reached
151
+ ```
152
+
153
+ `watch` re-analyzes a sliding window and prints only what changed: a new finding, a severity change, a finding that cleared, or a match with a past incident. When you stop it, it writes the usual reports for the worst moment it saw and keeps one history record for the whole session.
154
+
155
+ | Option | Purpose |
156
+ |---|---|
157
+ | `--window MINUTES` | How much recent log to analyze each time. Default 5 |
158
+ | `--interval SECONDS` | How often to check. Default 15 |
159
+ | `--duration SECONDS` | Stop after this long. Default: until Ctrl+C |
160
+ | `--json` | One JSON event per line, for piping into other tools |
161
+ | `--from-start` | For files: include what is already there. Default: only new lines |
162
+
163
+ Everything stays on your machine. To run it unattended, use it as a systemd service or a Kubernetes sidecar with `--duration` unset.
164
+
165
+ ## What you get
166
+
167
+ `out/report.md` for people and `out/report.json` for pipelines (plus `out/report.html` with `--html`), containing:
168
+
169
+ - **Overall severity** (none, low, medium, high, critical) and a severity per finding
170
+ - **Four Golden Signals**: which of latency, traffic, errors and saturation are affected
171
+ - **Order of first appearance**: which pattern showed up first
172
+ - **Read-only checks to run next**, filled in with your unit, container or pod
173
+ - **Seen before**: similar past incidents from your history, with the fix you noted
174
+ - **Top repeating lines**, with timestamps, IDs and IPs normalized so repeats group together
175
+ - **Redacted examples** for every finding
176
+
177
+ Plain text, JSON lines, logfmt and `kubectl --prefix --timestamps` output are all understood. Health-check lines are filtered unless they report an error.
178
+
179
+ ## Options
180
+
181
+ Options go after the source, for example `firstsignal file --path app.log --json`.
182
+
183
+ | Option | Purpose |
184
+ |---|---|
185
+ | `--packs core,nginx` | Pattern packs: `core`, `nginx`, `postgres`, `node`, `kubernetes`, `jvm`, `redis`, `mysql`, `haproxy`, `kafka`, `all`. Default `core` |
186
+ | `--config FILE` | Settings file. `./firstsignal.toml` is loaded automatically if present |
187
+ | `--out-dir DIR` | Where reports are written. Default `out` |
188
+ | `--html` | Also write `report.html`, a self-contained dashboard |
189
+ | `--json` | Print the JSON report to stdout and nothing else |
190
+ | `--no-write`, `-q` | Skip report files; no console output |
191
+ | `--fail-on LEVEL` | Exit `3` when overall severity is at or above `low`, `medium`, `high` or `critical` |
192
+ | `--max-bytes N` | Analyze only the last N bytes. Default 5,000,000 |
193
+ | `--timeout N` | Seconds to wait for `journalctl`, `docker` or `kubectl`. Default 60 |
194
+ | `--no-history`, `--history FILE` | Skip incident memory; use a different history file |
195
+ | `--no-redact`, `--redact-ips` | Turn secret masking off; also mask IPv4 addresses |
196
+ | `--ai`, `--ai-provider`, `--ai-model` | Optional AI hypothesis, see below |
197
+
198
+ Exit codes: `0` success, `1` could not collect or write, `2` usage error, `3` `--fail-on` threshold met.
199
+
200
+ ## Use it in CI or on a timer
201
+
202
+ ```bash
203
+ # fail a post-deploy check if the new pods log anything high or critical
204
+ firstsignal k8s -l app=api -n prod --since 10m --fail-on high --quiet
205
+ ```
206
+
207
+ `systemd/` has an example service and timer for scheduled runs. A `Dockerfile` is included for piping logs through a container:
208
+
209
+ ```bash
210
+ docker build -t firstsignal .
211
+ kubectl logs deploy/api | docker run --rm -i firstsignal file --path - --json --no-write
212
+ ```
213
+
214
+ ## Your own patterns
215
+
216
+ Copy `examples/firstsignal.toml` to `./firstsignal.toml`:
217
+
218
+ ```toml
219
+ packs = ["core", "postgres"]
220
+
221
+ [[patterns]]
222
+ key = "ledger_mismatch"
223
+ regex = "ledger mismatch"
224
+ signal = "errors" # latency | traffic | errors | saturation
225
+ severity = "critical" # low | medium | high | critical
226
+ title = "Ledger mismatch"
227
+ advice = "Compare the ledger totals for the affected account before retrying."
228
+ ```
229
+
230
+ The same file can replace the noise filter and add redaction rules.
231
+
232
+ ## Optional AI hypothesis
233
+
234
+ ```bash
235
+ export ANTHROPIC_API_KEY=... # or OPENAI_API_KEY
236
+ firstsignal k8s --pod deploy/api -n prod --ai
237
+
238
+ # any OpenAI-compatible endpoint, or a local model with no key at all
239
+ firstsignal file --path app.log --ai --ai-provider ollama --ai-model llama3.1
240
+ ```
241
+
242
+ - **Off by default.** Without `--ai`, nothing leaves your machine.
243
+ - **Only the redacted summary is sent**: counts, order of appearance, up to two redacted example lines per finding, and the top repeating lines. Never the raw log, and never anything with `--no-redact`.
244
+ - **The answer is text for you to read.** It is labeled unverified in the report and nothing in it is executed.
245
+ - **Log content is treated as untrusted** in the prompt, so text inside a log line cannot give the model instructions.
246
+ - If the call fails, the rest of the report is still produced.
247
+
248
+ Environment: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `FIRSTSIGNAL_AI_KEY`; `FIRSTSIGNAL_AI_PROVIDER`, `FIRSTSIGNAL_AI_MODEL`, `FIRSTSIGNAL_AI_BASE_URL`.
249
+
250
+ Redaction is pattern-based and cannot promise to catch every secret. See [SECURITY.md](SECURITY.md).
251
+
252
+ ## How it works
253
+
254
+ ```text
255
+ cli.py ── collectors.py journalctl / docker logs / kubectl logs / file (read-only, no shell)
256
+ ── parsing.py plain text, JSON lines, logfmt, kubectl prefixes → events
257
+ ── analyzer.py patterns → findings, severity, golden signals, order of appearance
258
+ ── redact.py masks secrets before anything is written or sent
259
+ ── ai.py optional hypothesis from the redacted summary (stdlib HTTP, no SDK)
260
+ ── watch.py follow a source, re-analyze a sliding window, report changes
261
+ ── memory.py incident fingerprints, local history, "seen before" matching
262
+ ── reporter.py report.md + report.json
263
+ ── html.py report.html: the viewer page with the report embedded
264
+ ── patterns.py built-in packs settings.py firstsignal.toml
265
+ ```
266
+
267
+ One runtime dependency (`rich`). Python 3.10 to 3.13.
268
+
269
+ ## Development
270
+
271
+ ```bash
272
+ pip install -e ".[dev]"
273
+ pytest --cov
274
+ ruff check .
275
+ bandit -q -r firstsignal
276
+ ```
277
+
278
+ See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and pull requests are welcome.
279
+
280
+ ## Website
281
+
282
+ Live at https://firstsignal.autoshiftops.com/. `site/` holds the landing page, the report viewer and a 404 page as plain HTML with no build step.
283
+
284
+ - **GitHub Pages:** the `Website` workflow deploys `site/` on every push to `main` that touches `site/`. Under Settings, Pages, the source must be **GitHub Actions**; "Deploy from a branch" publishes the README instead. The custom domain is set on the same page.
285
+ - **Social preview:** `site/og.png` (1280×640, a copy of `docs/brand/firstsignal-banner.png`) is the card shown when the link is shared. Upload the same image under the repository's Settings, Social preview.
286
+ - **Brand:** `docs/brand/` holds the mark (`firstsignal-mark.svg`, and `firstsignal-mark-16.svg` drawn for 16px), light and dark lockups, and the banner. The mark is a small first signal that pings, followed by louder ones.
287
+ - **Vercel or Netlify:** import the repo, set the root directory to `site`, and leave the build command empty.
288
+
289
+ `site/viewer.html` and `firstsignal/viewer.html` are the same file; a test keeps them identical.
290
+
291
+ ## Roadmap
292
+
293
+ See [ROADMAP.md](ROADMAP.md) for the phases and [docs/PRODUCT_PLAN.md](docs/PRODUCT_PLAN.md) for the reasoning. Work is tracked in [issues](https://github.com/AutoShiftOps/firstsignal/issues) by [milestone](https://github.com/AutoShiftOps/firstsignal/milestones).
294
+
295
+ ## Limits
296
+
297
+ - Detection is rule-based. It recognizes known failure signatures; it does not understand your application.
298
+ - Order of appearance is a lead, not proof of cause.
299
+ - It reads logs only. It does not look at metrics, traces or deploy history.
300
+
301
+ ## License
302
+
303
+ MIT © 2026 [AutoShiftOps](https://github.com/AutoShiftOps)
@@ -0,0 +1,270 @@
1
+ <p align="center">
2
+ <a href="https://firstsignal.autoshiftops.com/"><img src="https://raw.githubusercontent.com/AutoShiftOps/firstsignal/main/docs/brand/firstsignal-banner.png" alt="firstsignal: the loudest error is rarely the first one" width="820"></a>
3
+ </p>
4
+
5
+ # firstsignal
6
+
7
+ > Formerly **incopilot**. The `incopilot` command, `INCOPILOT_*` variables, `incopilot.toml` and `~/.incopilot` history still work for one release.
8
+
9
+ Read-only incident triage for logs. One command collects logs from **systemd, Docker, Kubernetes or a file**, maps what it finds to the **Four Golden Signals**, and writes a report with the order things went wrong and safe checks to run next.
10
+
11
+ [![CI](https://github.com/AutoShiftOps/firstsignal/actions/workflows/ci.yml/badge.svg)](https://github.com/AutoShiftOps/firstsignal/actions/workflows/ci.yml)
12
+ ![python](https://img.shields.io/badge/python-3.10%E2%80%933.13-3776AB)
13
+ ![license](https://img.shields.io/badge/license-MIT-blue)
14
+
15
+ **Correlate and explain, never auto-act.** firstsignal never changes the systems it reads. It works offline with no account and no agent. An AI hypothesis is available if you bring your own key, and it is off by default.
16
+
17
+ Website: https://firstsignal.autoshiftops.com/
18
+
19
+ ## Quick start
20
+
21
+ ```bash
22
+ pip install git+https://github.com/AutoShiftOps/firstsignal
23
+
24
+ # try it on the bundled example incident
25
+ git clone https://github.com/AutoShiftOps/firstsignal && cd firstsignal
26
+ firstsignal file --path examples/checkout-incident.log --packs core,nginx
27
+ cat out/report.md
28
+ ```
29
+
30
+ ```text
31
+ Overall severity: CRITICAL
32
+ 15 lines analyzed, 13 matched, 2 filtered as noise
33
+
34
+ Finding Signal Severity Count
35
+ Out of memory saturation critical 1
36
+ HTTP 5xx responses errors high 5
37
+ Timeouts latency high 4
38
+ Connection limit reached saturation high 2
39
+ ...
40
+ First to appear: Slow operations
41
+ ```
42
+
43
+ The report shows that slow queries came first, then the connection pool filled, then timeouts and 5xx, and the out-of-memory kill came last. That ordering is the point: the loudest error is often not the cause.
44
+
45
+ ## See it as a dashboard
46
+
47
+ ```bash
48
+ firstsignal file --path examples/checkout-incident.log --html
49
+ # open out/report.html in a browser
50
+ ```
51
+
52
+ `--html` writes a self-contained `report.html`: overall severity, the Four Golden Signals, a timeline of when each problem first appeared, findings, and the checks to run next. Nothing is loaded from a server and the report data stays in the file.
53
+
54
+ The terminal output already shows severity, golden signals, findings and the order of first appearance. Use `--html` when you need to share the result with people who were not at the terminal, for example in an incident channel or a postmortem.
55
+
56
+ A [live example](https://firstsignal.autoshiftops.com/viewer.html) is on the website.
57
+
58
+ ## It remembers
59
+
60
+ Every run with findings is remembered as a fingerprint: which patterns fired, in what order, on which target. The next time something similar happens, firstsignal tells you, along with what fixed it last time.
61
+
62
+ ```text
63
+ Seen before
64
+ 3f9a1c2e 12 days ago on prod/deploy/api (100% similar, critical)
65
+ Fix noted: raised DB pool size from 10 to 30, added index on orders.customer_id
66
+
67
+ Remembered as 8b21d0aa. When it is fixed: firstsignal history note 8b21d0aa "what fixed it"
68
+ ```
69
+
70
+ ```bash
71
+ firstsignal history list # what is remembered
72
+ firstsignal history note 8b21d0aa "what fixed it"
73
+ firstsignal history forget 8b21d0aa
74
+ ```
75
+
76
+ - **Local and private.** History is one file, `~/.firstsignal/history.jsonl`, readable only by you. Set `FIRSTSIGNAL_HISTORY` or `--history FILE` to move it, for example into a repo your team shares.
77
+ - **No log text is stored.** Only pattern names, counts, the target, the time and your note.
78
+ - **Matching is deterministic.** The same two incidents always get the same score. No model is involved.
79
+ - Re-running during the same incident updates one record instead of creating many. `--no-history` turns it off.
80
+
81
+ ## Sources
82
+
83
+ ```bash
84
+ # systemd journal
85
+ firstsignal journal --unit nginx --since "30 min ago"
86
+
87
+ # Docker container (stdout and stderr)
88
+ firstsignal docker --container my-api --since 1h
89
+
90
+ # Kubernetes: a pod, a workload, or a label selector
91
+ firstsignal k8s --pod deploy/api -n prod --since 30m
92
+ firstsignal k8s -l app=api -n prod --previous # the container that just crashed
93
+
94
+ # a file, a .gz file, or stdin
95
+ firstsignal file --path /var/log/app.log
96
+ kubectl logs deploy/api | firstsignal file --path -
97
+
98
+ # several sources as one timeline
99
+ firstsignal bundle --unit nginx --container my-api --pod deploy/api -n prod
100
+ ```
101
+
102
+ ## Watch it live
103
+
104
+ ```bash
105
+ firstsignal watch k8s --pod deploy/api -n prod
106
+ firstsignal watch docker --container my-api --window 10
107
+ firstsignal watch file --path /var/log/app.log
108
+ ```
109
+
110
+ ```text
111
+ Watching prod/deploy/api: last 5 min of logs, checked every 15s. Ctrl+C to stop.
112
+ 09:41:12 NEW high Connection limit reached (saturation) x2
113
+ 09:41:12 SEVERITY none -> high
114
+ 09:41:31 NEW critical Out of memory (saturation) x1
115
+ 09:41:31 SEVERITY high -> critical
116
+ 09:41:31 SEEN BEFORE 3f9a1c2e, 12 days ago on prod/deploy/api (80% similar). Fix noted: raised DB pool size
117
+ 09:52:40 CLEARED Connection limit reached
118
+ ```
119
+
120
+ `watch` re-analyzes a sliding window and prints only what changed: a new finding, a severity change, a finding that cleared, or a match with a past incident. When you stop it, it writes the usual reports for the worst moment it saw and keeps one history record for the whole session.
121
+
122
+ | Option | Purpose |
123
+ |---|---|
124
+ | `--window MINUTES` | How much recent log to analyze each time. Default 5 |
125
+ | `--interval SECONDS` | How often to check. Default 15 |
126
+ | `--duration SECONDS` | Stop after this long. Default: until Ctrl+C |
127
+ | `--json` | One JSON event per line, for piping into other tools |
128
+ | `--from-start` | For files: include what is already there. Default: only new lines |
129
+
130
+ Everything stays on your machine. To run it unattended, use it as a systemd service or a Kubernetes sidecar with `--duration` unset.
131
+
132
+ ## What you get
133
+
134
+ `out/report.md` for people and `out/report.json` for pipelines (plus `out/report.html` with `--html`), containing:
135
+
136
+ - **Overall severity** (none, low, medium, high, critical) and a severity per finding
137
+ - **Four Golden Signals**: which of latency, traffic, errors and saturation are affected
138
+ - **Order of first appearance**: which pattern showed up first
139
+ - **Read-only checks to run next**, filled in with your unit, container or pod
140
+ - **Seen before**: similar past incidents from your history, with the fix you noted
141
+ - **Top repeating lines**, with timestamps, IDs and IPs normalized so repeats group together
142
+ - **Redacted examples** for every finding
143
+
144
+ Plain text, JSON lines, logfmt and `kubectl --prefix --timestamps` output are all understood. Health-check lines are filtered unless they report an error.
145
+
146
+ ## Options
147
+
148
+ Options go after the source, for example `firstsignal file --path app.log --json`.
149
+
150
+ | Option | Purpose |
151
+ |---|---|
152
+ | `--packs core,nginx` | Pattern packs: `core`, `nginx`, `postgres`, `node`, `kubernetes`, `jvm`, `redis`, `mysql`, `haproxy`, `kafka`, `all`. Default `core` |
153
+ | `--config FILE` | Settings file. `./firstsignal.toml` is loaded automatically if present |
154
+ | `--out-dir DIR` | Where reports are written. Default `out` |
155
+ | `--html` | Also write `report.html`, a self-contained dashboard |
156
+ | `--json` | Print the JSON report to stdout and nothing else |
157
+ | `--no-write`, `-q` | Skip report files; no console output |
158
+ | `--fail-on LEVEL` | Exit `3` when overall severity is at or above `low`, `medium`, `high` or `critical` |
159
+ | `--max-bytes N` | Analyze only the last N bytes. Default 5,000,000 |
160
+ | `--timeout N` | Seconds to wait for `journalctl`, `docker` or `kubectl`. Default 60 |
161
+ | `--no-history`, `--history FILE` | Skip incident memory; use a different history file |
162
+ | `--no-redact`, `--redact-ips` | Turn secret masking off; also mask IPv4 addresses |
163
+ | `--ai`, `--ai-provider`, `--ai-model` | Optional AI hypothesis, see below |
164
+
165
+ Exit codes: `0` success, `1` could not collect or write, `2` usage error, `3` `--fail-on` threshold met.
166
+
167
+ ## Use it in CI or on a timer
168
+
169
+ ```bash
170
+ # fail a post-deploy check if the new pods log anything high or critical
171
+ firstsignal k8s -l app=api -n prod --since 10m --fail-on high --quiet
172
+ ```
173
+
174
+ `systemd/` has an example service and timer for scheduled runs. A `Dockerfile` is included for piping logs through a container:
175
+
176
+ ```bash
177
+ docker build -t firstsignal .
178
+ kubectl logs deploy/api | docker run --rm -i firstsignal file --path - --json --no-write
179
+ ```
180
+
181
+ ## Your own patterns
182
+
183
+ Copy `examples/firstsignal.toml` to `./firstsignal.toml`:
184
+
185
+ ```toml
186
+ packs = ["core", "postgres"]
187
+
188
+ [[patterns]]
189
+ key = "ledger_mismatch"
190
+ regex = "ledger mismatch"
191
+ signal = "errors" # latency | traffic | errors | saturation
192
+ severity = "critical" # low | medium | high | critical
193
+ title = "Ledger mismatch"
194
+ advice = "Compare the ledger totals for the affected account before retrying."
195
+ ```
196
+
197
+ The same file can replace the noise filter and add redaction rules.
198
+
199
+ ## Optional AI hypothesis
200
+
201
+ ```bash
202
+ export ANTHROPIC_API_KEY=... # or OPENAI_API_KEY
203
+ firstsignal k8s --pod deploy/api -n prod --ai
204
+
205
+ # any OpenAI-compatible endpoint, or a local model with no key at all
206
+ firstsignal file --path app.log --ai --ai-provider ollama --ai-model llama3.1
207
+ ```
208
+
209
+ - **Off by default.** Without `--ai`, nothing leaves your machine.
210
+ - **Only the redacted summary is sent**: counts, order of appearance, up to two redacted example lines per finding, and the top repeating lines. Never the raw log, and never anything with `--no-redact`.
211
+ - **The answer is text for you to read.** It is labeled unverified in the report and nothing in it is executed.
212
+ - **Log content is treated as untrusted** in the prompt, so text inside a log line cannot give the model instructions.
213
+ - If the call fails, the rest of the report is still produced.
214
+
215
+ Environment: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `FIRSTSIGNAL_AI_KEY`; `FIRSTSIGNAL_AI_PROVIDER`, `FIRSTSIGNAL_AI_MODEL`, `FIRSTSIGNAL_AI_BASE_URL`.
216
+
217
+ Redaction is pattern-based and cannot promise to catch every secret. See [SECURITY.md](SECURITY.md).
218
+
219
+ ## How it works
220
+
221
+ ```text
222
+ cli.py ── collectors.py journalctl / docker logs / kubectl logs / file (read-only, no shell)
223
+ ── parsing.py plain text, JSON lines, logfmt, kubectl prefixes → events
224
+ ── analyzer.py patterns → findings, severity, golden signals, order of appearance
225
+ ── redact.py masks secrets before anything is written or sent
226
+ ── ai.py optional hypothesis from the redacted summary (stdlib HTTP, no SDK)
227
+ ── watch.py follow a source, re-analyze a sliding window, report changes
228
+ ── memory.py incident fingerprints, local history, "seen before" matching
229
+ ── reporter.py report.md + report.json
230
+ ── html.py report.html: the viewer page with the report embedded
231
+ ── patterns.py built-in packs settings.py firstsignal.toml
232
+ ```
233
+
234
+ One runtime dependency (`rich`). Python 3.10 to 3.13.
235
+
236
+ ## Development
237
+
238
+ ```bash
239
+ pip install -e ".[dev]"
240
+ pytest --cov
241
+ ruff check .
242
+ bandit -q -r firstsignal
243
+ ```
244
+
245
+ See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and pull requests are welcome.
246
+
247
+ ## Website
248
+
249
+ Live at https://firstsignal.autoshiftops.com/. `site/` holds the landing page, the report viewer and a 404 page as plain HTML with no build step.
250
+
251
+ - **GitHub Pages:** the `Website` workflow deploys `site/` on every push to `main` that touches `site/`. Under Settings, Pages, the source must be **GitHub Actions**; "Deploy from a branch" publishes the README instead. The custom domain is set on the same page.
252
+ - **Social preview:** `site/og.png` (1280×640, a copy of `docs/brand/firstsignal-banner.png`) is the card shown when the link is shared. Upload the same image under the repository's Settings, Social preview.
253
+ - **Brand:** `docs/brand/` holds the mark (`firstsignal-mark.svg`, and `firstsignal-mark-16.svg` drawn for 16px), light and dark lockups, and the banner. The mark is a small first signal that pings, followed by louder ones.
254
+ - **Vercel or Netlify:** import the repo, set the root directory to `site`, and leave the build command empty.
255
+
256
+ `site/viewer.html` and `firstsignal/viewer.html` are the same file; a test keeps them identical.
257
+
258
+ ## Roadmap
259
+
260
+ See [ROADMAP.md](ROADMAP.md) for the phases and [docs/PRODUCT_PLAN.md](docs/PRODUCT_PLAN.md) for the reasoning. Work is tracked in [issues](https://github.com/AutoShiftOps/firstsignal/issues) by [milestone](https://github.com/AutoShiftOps/firstsignal/milestones).
261
+
262
+ ## Limits
263
+
264
+ - Detection is rule-based. It recognizes known failure signatures; it does not understand your application.
265
+ - Order of appearance is a lead, not proof of cause.
266
+ - It reads logs only. It does not look at metrics, traces or deploy history.
267
+
268
+ ## License
269
+
270
+ MIT © 2026 [AutoShiftOps](https://github.com/AutoShiftOps)
@@ -0,0 +1,4 @@
1
+ """firstsignal: read-only incident triage for logs."""
2
+
3
+ __version__ = "0.2.0"
4
+ __all__ = ["__version__"]
@@ -0,0 +1,6 @@
1
+ """Allow `python -m firstsignal`."""
2
+
3
+ from firstsignal.cli import main
4
+
5
+ if __name__ == "__main__":
6
+ main()
@@ -0,0 +1,27 @@
1
+ """Backward compatibility with the project's former name, incopilot.
2
+
3
+ The old names keep working for one release: INCOPILOT_* environment variables,
4
+ ./incopilot.toml and ~/.incopilot/history.jsonl. The new names win when both exist.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import os
10
+ from pathlib import Path
11
+
12
+ OLD_NAME = "incopilot"
13
+
14
+
15
+ def getenv(name: str, default: str | None = None) -> str | None:
16
+ """Read FIRSTSIGNAL_<name>, falling back to INCOPILOT_<name>."""
17
+ value = os.environ.get(f"FIRSTSIGNAL_{name}")
18
+ if value:
19
+ return value
20
+ return os.environ.get(f"INCOPILOT_{name}", default)
21
+
22
+
23
+ def prefer_existing(new: Path, old: Path) -> Path:
24
+ """Use `new` unless only the old-name file exists."""
25
+ if not new.exists() and old.exists():
26
+ return old
27
+ return new