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.
- firstsignal-0.2.0/LICENSE +21 -0
- firstsignal-0.2.0/PKG-INFO +303 -0
- firstsignal-0.2.0/README.md +270 -0
- firstsignal-0.2.0/firstsignal/__init__.py +4 -0
- firstsignal-0.2.0/firstsignal/__main__.py +6 -0
- firstsignal-0.2.0/firstsignal/_compat.py +27 -0
- firstsignal-0.2.0/firstsignal/ai.py +163 -0
- firstsignal-0.2.0/firstsignal/analyzer.py +143 -0
- firstsignal-0.2.0/firstsignal/cli.py +477 -0
- firstsignal-0.2.0/firstsignal/collectors.py +131 -0
- firstsignal-0.2.0/firstsignal/html.py +28 -0
- firstsignal-0.2.0/firstsignal/memory.py +226 -0
- firstsignal-0.2.0/firstsignal/parsing.py +119 -0
- firstsignal-0.2.0/firstsignal/patterns.py +267 -0
- firstsignal-0.2.0/firstsignal/redact.py +47 -0
- firstsignal-0.2.0/firstsignal/reporter.py +203 -0
- firstsignal-0.2.0/firstsignal/settings.py +82 -0
- firstsignal-0.2.0/firstsignal/viewer.html +482 -0
- firstsignal-0.2.0/firstsignal/watch.py +149 -0
- firstsignal-0.2.0/firstsignal.egg-info/PKG-INFO +303 -0
- firstsignal-0.2.0/firstsignal.egg-info/SOURCES.txt +38 -0
- firstsignal-0.2.0/firstsignal.egg-info/dependency_links.txt +1 -0
- firstsignal-0.2.0/firstsignal.egg-info/entry_points.txt +3 -0
- firstsignal-0.2.0/firstsignal.egg-info/requires.txt +11 -0
- firstsignal-0.2.0/firstsignal.egg-info/top_level.txt +1 -0
- firstsignal-0.2.0/pyproject.toml +75 -0
- firstsignal-0.2.0/setup.cfg +4 -0
- firstsignal-0.2.0/tests/test_ai.py +101 -0
- firstsignal-0.2.0/tests/test_analyzer.py +102 -0
- firstsignal-0.2.0/tests/test_cli.py +138 -0
- firstsignal-0.2.0/tests/test_collectors.py +127 -0
- firstsignal-0.2.0/tests/test_compat.py +57 -0
- firstsignal-0.2.0/tests/test_html.py +46 -0
- firstsignal-0.2.0/tests/test_memory.py +146 -0
- firstsignal-0.2.0/tests/test_packs.py +111 -0
- firstsignal-0.2.0/tests/test_parsing.py +44 -0
- firstsignal-0.2.0/tests/test_redact.py +32 -0
- firstsignal-0.2.0/tests/test_reporter.py +77 -0
- firstsignal-0.2.0/tests/test_settings.py +57 -0
- 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
|
+
[](https://github.com/AutoShiftOps/firstsignal/actions/workflows/ci.yml)
|
|
45
|
+

|
|
46
|
+

|
|
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
|
+
[](https://github.com/AutoShiftOps/firstsignal/actions/workflows/ci.yml)
|
|
12
|
+

|
|
13
|
+

|
|
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,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
|