Skip to content

Commit 7c5f4c6

Browse files
leo-aa88leo-aa88
committed
docs, issue templates, makefile fix
1 parent a651355 commit 7c5f4c6

File tree

7 files changed

+367
-0
lines changed

7 files changed

+367
-0
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
name: Bug report
2+
description: Something is broken or producing wrong output
3+
labels: ["bug"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Thanks for taking the time to report a bug.
9+
The most useful thing you can provide is the exact command you ran and the full output.
10+
11+
- type: textarea
12+
id: command
13+
attributes:
14+
label: Command
15+
description: The exact raglogs command that produced the problem.
16+
placeholder: "raglogs compare --since 30m --baseline 24h"
17+
validations:
18+
required: true
19+
20+
- type: textarea
21+
id: expected
22+
attributes:
23+
label: Expected behaviour
24+
description: What did you expect to happen?
25+
validations:
26+
required: true
27+
28+
- type: textarea
29+
id: actual
30+
attributes:
31+
label: Actual behaviour
32+
description: What actually happened? Include the full output, including any error messages or tracebacks.
33+
render: text
34+
validations:
35+
required: true
36+
37+
- type: textarea
38+
id: log_sample
39+
attributes:
40+
label: Log sample (if relevant)
41+
description: |
42+
If the bug is about incorrect clustering, normalization, or timeline/compare output,
43+
paste a few representative log lines. Redact any sensitive values.
44+
render: json
45+
46+
- type: input
47+
id: version
48+
attributes:
49+
label: raglogs version
50+
description: Output of `pip show raglogs` or the git commit hash.
51+
placeholder: "0.1.0 / abc1234"
52+
validations:
53+
required: false
54+
55+
- type: input
56+
id: python
57+
attributes:
58+
label: Python version
59+
description: Output of `python --version`.
60+
placeholder: "3.12.3"
61+
validations:
62+
required: false
63+
64+
- type: dropdown
65+
id: llm
66+
attributes:
67+
label: LLM provider
68+
description: Which LLM provider is configured?
69+
options:
70+
- disabled (no LLM)
71+
- openai
72+
- ollama
73+
- other OpenAI-compatible endpoint
74+
validations:
75+
required: false

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Question
4+
url: https://github.com/leo-aa88/raglogs/issues/new?labels=question&template=
5+
about: Not a bug or feature request? Open a plain issue with the question label.

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: Feature request
2+
description: Suggest a new command, flag, adapter, or behaviour
3+
labels: ["enhancement"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Feature requests are welcome. The most convincing ones include a concrete
9+
example of the problem and what the output would look like.
10+
11+
- type: textarea
12+
id: problem
13+
attributes:
14+
label: What problem does this solve?
15+
description: Describe the situation where you hit this limitation.
16+
placeholder: "When an incident spans multiple services, I can't easily see..."
17+
validations:
18+
required: true
19+
20+
- type: textarea
21+
id: proposed
22+
attributes:
23+
label: Proposed solution
24+
description: |
25+
What would you want the command, flag, or output to look like?
26+
A concrete example is more useful than a general description.
27+
placeholder: |
28+
raglogs compare --service api --service billing-worker --since 30m --baseline 24h
29+
30+
Output:
31+
...
32+
validations:
33+
required: true
34+
35+
- type: textarea
36+
id: alternatives
37+
attributes:
38+
label: Alternatives considered
39+
description: Other approaches you considered, and why they fall short.
40+
41+
- type: dropdown
42+
id: area
43+
attributes:
44+
label: Area
45+
options:
46+
- New CLI command
47+
- New flag on existing command
48+
- Log source adapter (Datadog, Loki, CloudWatch, etc.)
49+
- Normalization / clustering
50+
- LLM integration
51+
- HTTP API
52+
- Output format
53+
- Other
54+
validations:
55+
required: true

‎.github/ISSUE_TEMPLATE/normalization.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: Normalization / clustering issue
2+
description: Log messages that should cluster together are not, or unrelated messages are being grouped
3+
labels: ["normalization"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Normalization quality directly affects how useful raglogs is.
9+
The more concrete examples you provide, the easier this is to fix.
10+
11+
- type: dropdown
12+
id: problem_type
13+
attributes:
14+
label: Problem type
15+
options:
16+
- Messages that should cluster together are producing separate clusters
17+
- Unrelated messages are being grouped into the same cluster
18+
- A dynamic value (ID, IP, timestamp) is not being stripped
19+
- A meaningful value is being incorrectly stripped
20+
validations:
21+
required: true
22+
23+
- type: textarea
24+
id: raw_messages
25+
attributes:
26+
label: Raw log messages
27+
description: Paste the actual log lines as they appear in your logs.
28+
render: text
29+
validations:
30+
required: true
31+
32+
- type: textarea
33+
id: normalized
34+
attributes:
35+
label: What they normalize to (if known)
36+
description: |
37+
You can check normalization with:
38+
```python
39+
from src.core.normalization.normalize import normalize_message
40+
print(normalize_message("your message here"))
41+
```
42+
render: text
43+
44+
- type: textarea
45+
id: expected_normalization
46+
attributes:
47+
label: What they should normalize to
48+
description: The normalized form you would expect, so they fingerprint correctly.
49+
render: text
50+
validations:
51+
required: true
52+
53+
- type: textarea
54+
id: context
55+
attributes:
56+
label: Additional context
57+
description: Log format, service type, or anything else that helps.

‎CODE_OF_CONDUCT.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Code of Conduct
2+
3+
## Our commitment
4+
5+
raglogs is a small open-source tool. Everyone who participates — opening issues, submitting pull requests, commenting on discussions — is expected to treat others with basic respect.
6+
7+
We are not trying to build a movement or a community with a charter. We are trying to build useful software. The bar is simple: engage in good faith, focus on the work, and don't be a jerk.
8+
9+
## What this means in practice
10+
11+
**Do:**
12+
- Critique code, ideas, and approaches directly and honestly
13+
- Ask questions when something is unclear
14+
- Disagree — including strongly — on technical grounds
15+
- Accept that maintainers have final say on direction
16+
17+
**Don't:**
18+
- Attack people instead of ideas
19+
- Harass, threaten, or demean anyone
20+
- Flood issues with off-topic noise
21+
22+
## Scope
23+
24+
This applies to the GitHub repository: issues, pull requests, discussions, and code review comments.
25+
26+
## Enforcement
27+
28+
If something is genuinely harmful — harassment, threats, sustained bad-faith disruption — maintainers will remove the content and, if necessary, block the account. There is no formal appeals process for a project of this size.
29+
30+
For anything that crosses a line, contact the maintainer directly via GitHub.

‎CONTRIBUTING.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# Contributing to raglogs
2+
3+
raglogs is an incident analysis CLI tool. Contributions are welcome — bug fixes, new log adapters, normalization improvements, and documentation are all useful.
4+
5+
This document covers how to get set up, what the codebase expects, and how to submit changes.
6+
7+
---
8+
9+
## Getting started
10+
11+
```bash
12+
git clone https://github.com/leo-aa88/raglogs
13+
cd raglogs
14+
python -m venv .venv && source .venv/bin/activate
15+
pip install -r requirements.txt && pip install -e .
16+
cp .env.example .env
17+
# Edit .env — set RAGLOGS_DB_URL at minimum
18+
docker compose up postgres -d
19+
raglogs init
20+
```
21+
22+
Run the demo to verify everything works:
23+
24+
```bash
25+
raglogs demo
26+
raglogs timeline --since 2h
27+
raglogs compare --since 2h --baseline 24h
28+
```
29+
30+
---
31+
32+
## Project structure
33+
34+
```
35+
src/core/
36+
clustering/ Fingerprint grouping, importance scoring, baseline comparison
37+
compare/ Window diffing — new, disappeared, increased, decreased
38+
explain/ Evidence assembly, confidence, templates, summarizer
39+
ingestion/ Ingestion orchestration and batch persistence
40+
llm/ Provider abstraction (OpenAI, Ollama, noop)
41+
normalization/ Message normalization, fingerprinting, trigger patterns
42+
parsing/ JSON and text parsers, field alias resolution
43+
retrieval/ Keyword-based question answering
44+
timeline/ Causal timeline reconstruction
45+
src/cli/commands/ One file per CLI command
46+
src/api/routes/ FastAPI route handlers
47+
src/db/ SQLAlchemy models and session management
48+
src/utils/ Time window parsing, hashing helpers
49+
tests/unit/ Pure unit tests — no database required
50+
tests/integration/ Full pipeline tests — require running Postgres
51+
```
52+
53+
The pipeline flows: ingest → normalize → fingerprint → cluster → baseline compare → evidence assembly → explain / timeline / compare.
54+
55+
---
56+
57+
## Running tests
58+
59+
Unit tests require no database:
60+
61+
```bash
62+
make test-unit
63+
# or
64+
pytest tests/unit/
65+
```
66+
67+
Integration tests require a running Postgres instance:
68+
69+
```bash
70+
docker compose up postgres -d
71+
make test-int
72+
# or
73+
pytest tests/integration/
74+
```
75+
76+
All tests must pass before a pull request will be merged. If you are adding new functionality, add tests for it.
77+
78+
---
79+
80+
## Code style
81+
82+
- Python 3.11+
83+
- Type annotations on all function signatures
84+
- `ruff` for linting, `black` for formatting
85+
86+
```bash
87+
make lint
88+
make format
89+
```
90+
91+
No hard rules on line length beyond what `black` enforces. Prefer explicit over clever. Avoid abstractions that exist only to save lines.
92+
93+
---
94+
95+
## Areas where contributions are most useful
96+
97+
**Normalization improvements**
98+
99+
The normalization step (`src/core/normalization/patterns.py`) determines clustering quality. If you have real-world log formats that normalize poorly — producing too many clusters for the same error, or collapsing unrelated errors — a fix there has high leverage. Include before/after examples and a test in `tests/unit/test_normalization.py`.
100+
101+
**Log source adapters**
102+
103+
New adapters go in `src/adapters/`. Each adapter yields `ParsedLogLine` objects. The rest of the pipeline is fully source-agnostic. Useful adapters: Datadog, Loki, Kubernetes pod logs, CloudWatch.
104+
105+
**Trigger patterns**
106+
107+
New trigger event patterns go in `TRIGGER_PATTERNS` in `src/core/normalization/patterns.py`. A good trigger pattern is specific enough to avoid false positives and general enough to match common variants across log formats.
108+
109+
**Bug fixes**
110+
111+
Check the issue tracker. Bugs with a reproducing log sample are easiest to fix.
112+
113+
---
114+
115+
## Submitting a pull request
116+
117+
1. Fork the repository and create a branch from `main`
118+
2. Make your changes with tests
119+
3. Run `make lint` and `make test-unit` — both must pass
120+
4. Open a pull request with a clear description of what changed and why
121+
5. Reference any related issue
122+
123+
Pull requests that are purely cosmetic (reformatting with no functional change) will not be merged.
124+
125+
Keep pull requests focused. A PR that fixes a bug and adds an unrelated feature is harder to review and slower to merge than two separate PRs.
126+
127+
---
128+
129+
## Commit messages
130+
131+
No strict format required. Be clear about what changed and why. One-line messages are fine for small changes. For anything non-trivial:
132+
133+
```
134+
Short summary (under 72 chars)
135+
136+
Longer explanation of what changed and why, if not obvious from the
137+
diff. Reference the issue number if applicable.
138+
```
139+
140+
---
141+
142+
## Questions
143+
144+
Open a GitHub issue with the `question` label. If it is a quick question about whether a contribution would be accepted before you invest time in it, that is a good use of an issue.

‎Makefile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ demo: db-up
6969
alembic upgrade head
7070
raglogs demo
7171
raglogs timeline --since 2h
72+
raglogs compare --since 30m --baseline 24h
7273

7374
ingest:
7475
raglogs ingest $(SAMPLE)

0 commit comments

Comments
 (0)