Metadata-Version: 2.5
Name: findlog
Version: 1.0.0
Summary: Find the failure and the events surrounding it in a large log file.
Project-URL: Homepage, https://github.com/shauryaR790/findlog-py
Project-URL: Repository, https://github.com/shauryaR790/findlog-py
Project-URL: Documentation, https://github.com/shauryaR790/findlog-py#readme
Project-URL: Changelog, https://github.com/shauryaR790/findlog-py/blob/main/CHANGELOG.md
Author: findlog contributors
License-Expression: MIT
License-File: LICENSE
Keywords: analysis,cli,debugging,incident,logs
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Logging
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# findlog

Command-line tool that finds a failure in a log file and prints the lines around it.

```bash
pip install findlog
findlog server.log --around "Connection refused"
```

## Install from source

```bash
git clone https://github.com/shauryaR790/findlog-py.git
cd findlog-py
pip install -e ".[dev]"
```

## Commands

```bash
findlog server.log --around "Connection refused"
findlog server.log --line 8421
findlog server.log --around "Connection refused" --save
findlog server.log --around "Connection refused" --json
```

## What it reports

For a matching line, findlog prints:

- first match line number
- occurrence count
- lines before and after
- other errors and warnings in the same window
- file and line from a stack trace when the log includes one

It groups repeated matches that happen close together into one incident.

It does not guess root cause. It shows what the log contains near the failure.

## Options

| Option | Description |
|--------|-------------|
| `--around TEXT` | Text or phrase to search for |
| `--line N` | Line number to inspect |
| `--context N` | Lines of context (default: 10) |
| `--all` | Show every grouped incident |
| `--regex` | Treat `--around` as a regex |
| `--save` | Write incident lines to a file |
| `--output PATH` | Path for saved slice |
| `--json` | JSON output |
| `--quiet` | Minimal output |

Exit codes: `0` ok, `1` no match, `2` bad input, `3` file error.

## Example

```
findlog server.log --around "Connection refused"
```

```
FINDLOG
------------------------------------

MATCH
  Connection refused

FIRST FAILURE
  line 5

OCCURRENCES
  3

RELATED
  Database connection failed
  Database unavailable

FOLLOWED BY
  line 12  Shutdown
```

## Python API

```python
from findlog import analyze_log

result = analyze_log("server.log", query="Connection refused")
print(result.primary_incident.first_match_line)
```

## Notes

- Reads files line by line. Does not load the whole file into memory.
- Runs offline. Does not upload logs.
- Does not modify the source log.

## License

MIT License. See [LICENSE](./LICENSE).
