Skip to content

Commit 13ab2b8

Browse files
MehrazRummanMehrazRumman
committed
ready for publish
1 parent daa5810 commit 13ab2b8

5 files changed

Lines changed: 252 additions & 40 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
## [0.1.0] - 2026-04-26
11+
12+
### Added
13+
- FastAPI middleware for automatic request/response logging
14+
- Structured `LogEvent` model with request metadata, response status, and latency
15+
- Configurable event filtering pipeline (`ObserverFilter` protocol)
16+
- Multiple storage backends: in-memory, JSON file, SQLite
17+
- Console and file log handlers
18+
- JSON and plain-text formatters
19+
- Built-in dashboard for inspecting logged events (mountable as a sub-application)
20+
- `ObserverConfig` for controlling log level, path filters, and storage
21+
- Logger factory with structured output support
22+
- Full test suite (69 tests, 87% coverage)
23+
- MkDocs documentation site with quickstart, API reference, and best-practices guides
24+
- CI/CD pipelines for testing (Python 3.10–3.14), coverage badge, and PyPI publishing
25+
26+
[Unreleased]: https://github.com/MehrazRumman/fastapi-observer/compare/v0.1.0...HEAD
27+
[0.1.0]: https://github.com/MehrazRumman/fastapi-observer/releases/tag/v0.1.0

‎CONTRIBUTING.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Contributing to fastapi-observer
2+
3+
Thank you for your interest in contributing!
4+
5+
## Getting Started
6+
7+
1. Fork the repository and clone your fork:
8+
```bash
9+
git clone https://github.com/<your-username>/fastapi-observer.git
10+
cd fastapi-observer
11+
```
12+
13+
2. Install all development dependencies:
14+
```bash
15+
pip install -e ".[test,docs,dev]"
16+
```
17+
18+
3. Install pre-commit hooks:
19+
```bash
20+
pre-commit install
21+
```
22+
23+
4. Create a feature branch:
24+
```bash
25+
git checkout -b feature/your-feature-name
26+
```
27+
28+
## Running Tests
29+
30+
```bash
31+
# Run the full test suite
32+
pytest -q
33+
34+
# Run with coverage report
35+
pytest --cov=fastapi_observer --cov-report=term-missing
36+
37+
# Run a specific test file
38+
pytest tests/test_middleware.py -v
39+
```
40+
41+
Maintain coverage above 85% for any new code you add.
42+
43+
## Code Style
44+
45+
This project uses [Black](https://black.readthedocs.io/) for formatting.
46+
47+
```bash
48+
# Format all files
49+
black .
50+
51+
# Check formatting without changing files
52+
black --check .
53+
```
54+
55+
Pre-commit hooks run Black automatically on every commit. If a commit is rejected, run `black .` and re-stage the files.
56+
57+
## Building Documentation
58+
59+
```bash
60+
mkdocs serve # preview locally at http://127.0.0.1:8000
61+
mkdocs build # build static site into /site
62+
```
63+
64+
## Submitting a Pull Request
65+
66+
1. Make sure all tests pass and coverage has not dropped.
67+
2. Update documentation if you changed public APIs or added new features.
68+
3. Add an entry to [CHANGELOG.md](CHANGELOG.md) under the `Unreleased` section.
69+
4. Open a pull request against the `main` branch with a clear description of the change.
70+
71+
## Reporting Bugs
72+
73+
Open an issue at <https://github.com/MehrazRumman/fastapi-observer/issues> with:
74+
75+
- A minimal reproducible example
76+
- Expected vs. actual behaviour
77+
- Python version and fastapi-observer version
78+
79+
## Security Issues
80+
81+
Please do **not** open a public issue for security vulnerabilities. See [SECURITY.md](SECURITY.md) for the responsible disclosure process.

‎README.md‎

Lines changed: 87 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,80 +1,129 @@
11
# fastapi-observer
22

3-
FastAPI Observer provides structured logging and observability helpers for FastAPI applications.
3+
Structured logging and observability middleware for FastAPI applications.
44

55
[![Test](https://github.com/MehrazRumman/fastapi-observer/actions/workflows/tests.yml/badge.svg)](https://github.com/MehrazRumman/fastapi-observer/actions/workflows/tests.yml)
66
[![coverage](assets/coverage.svg)](https://github.com/MehrazRumman/fastapi-observer/actions/workflows/coverage-badge.yml)
77
[![pypi package](https://img.shields.io/pypi/v/fastapi-observer?logo=pypi&label=pypi%20package)](https://pypi.org/project/fastapi-observer/)
88
[![python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-brightgreen?logo=python&logoColor=white)](#python-compatibility)
99

10-
## Python compatibility
10+
**[Documentation](https://mehrazrumman.github.io/fastapi-observer/)** · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md)
1111

12-
- Supported Python versions: `3.10`, `3.11`, `3.12`, `3.13`, `3.14`
13-
- Enforced in CI with tox matrix: `py310`, `py311`, `py312`, `py313`, `py314`
12+
---
1413

15-
## Package versions
14+
## Features
1615

17-
### Runtime
16+
- **Zero-boilerplate middleware** — one line to log every request and response
17+
- **Structured events** — typed `LogEvent` objects with method, path, status code, latency, and more
18+
- **Pluggable storage** — in-memory, JSON file, JSON Lines, or SQLite backends
19+
- **Filter pipeline** — drop health-check noise, log only errors, or set a minimum latency threshold
20+
- **Built-in dashboard** — mount an event-inspector UI at any path in your app
21+
- **Multiple formatters** — plain-text or JSON output
22+
- **Python 3.10–3.14** with full CI coverage across all versions
1823

19-
- `pydantic>=2.0,<3.0`
24+
---
2025

21-
### Testing
26+
## Install
2227

23-
- `pytest>=8.0`
24-
- `pytest-cov>=5.0`
28+
```bash
29+
pip install fastapi-observer
30+
```
2531

26-
### Documentation
32+
---
2733

28-
- `mkdocs>=1.6`
29-
- `mkdocs-material>=9.5`
34+
## Quick start
3035

31-
### Development
36+
### Basic logging
3237

33-
- `pre-commit>=3.7`
34-
- `black>=24.10`
38+
```python
39+
from fastapi import FastAPI
40+
from fastapi_observer import ObserverConfig, ObserverMiddleware
3541

36-
## Install
42+
app = FastAPI()
43+
app.add_middleware(ObserverMiddleware, config=ObserverConfig())
3744

38-
```bash
39-
pip install fastapi-observer
45+
@app.get("/items")
46+
async def list_items():
47+
return {"items": ["alpha", "beta", "gamma"]}
4048
```
4149

42-
For development:
50+
Every request is now logged to the console with method, path, status code, and latency.
4351

44-
```bash
45-
pip install -e ".[test,docs,dev]"
46-
```
52+
### Persist events and open the dashboard
4753

48-
## Tests and coverage
54+
```python
55+
from fastapi import FastAPI
56+
from fastapi_observer import ObserverConfig, ObserverMiddleware, build_dashboard_app
57+
from fastapi_observer.storage import InMemoryEventStore
4958

50-
Run tests:
59+
app = FastAPI()
60+
store = InMemoryEventStore()
5161

52-
```bash
53-
pytest -q
62+
app.add_middleware(ObserverMiddleware, config=ObserverConfig(), storage=store)
63+
app.mount("/dashboard", build_dashboard_app(store, title="Observer Dashboard"))
5464
```
5565

56-
Run tests with coverage:
66+
Open `http://localhost:8000/dashboard` to browse and inspect logged events.
5767

58-
```bash
59-
pytest -q --cov=fastapi_observer --cov-report=term-missing --cov-report=xml
68+
### Filter out noise
69+
70+
```python
71+
from fastapi_observer import ObserverConfig, ObserverMiddleware, only_errors, min_duration_ms
72+
73+
app.add_middleware(
74+
ObserverMiddleware,
75+
config=ObserverConfig(handlers=["console"], log_format="json"),
76+
event_filters=[
77+
only_errors, # log 4xx/5xx responses only
78+
min_duration_ms(50.0), # ignore fast responses
79+
],
80+
)
6081
```
6182

62-
Run full Python version matrix locally:
83+
See the [examples/](examples/) directory for more patterns including SQLite storage and custom filters.
84+
85+
---
86+
87+
## Storage backends
88+
89+
| Backend | Class | Use case |
90+
|---|---|---|
91+
| In-memory | `InMemoryEventStore` | Development, testing |
92+
| JSON file | `JsonFileEventStore` | Simple persistence |
93+
| JSON Lines | `JsonLinesEventStore` | Append-only log files |
94+
| SQLite | `SQLiteEventStore` | Queryable local storage |
95+
96+
---
97+
98+
## Python compatibility
99+
100+
- Supported versions: `3.10`, `3.11`, `3.12`, `3.13`, `3.14`
101+
- Enforced in CI with a tox matrix across all versions
102+
103+
---
104+
105+
## Development
106+
107+
Install all dependencies:
63108

64109
```bash
65-
tox
110+
pip install -e ".[test,docs,dev]"
111+
pre-commit install
66112
```
67113

68-
## Docs
69-
70-
Build docs:
114+
Run tests:
71115

72116
```bash
73-
mkdocs build --strict
117+
pytest -q
118+
pytest -q --cov=fastapi_observer --cov-report=term-missing # with coverage
119+
tox # full version matrix
74120
```
75121

76-
Serve docs locally:
122+
Build and preview docs:
77123

78124
```bash
79-
mkdocs serve
125+
mkdocs serve # http://127.0.0.1:8000
126+
mkdocs build --strict
80127
```
128+
129+
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution guide.

‎SECURITY.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Security Policy
2+
3+
## Supported Versions
4+
5+
| Version | Supported |
6+
| ------- | --------- |
7+
| 0.1.x | Yes |
8+
9+
## Reporting a Vulnerability
10+
11+
Please **do not** open a public GitHub issue for security vulnerabilities.
12+
13+
Instead, report them by emailing **blackndmaroon@gmail.com** with the subject line:
14+
15+
```
16+
[fastapi-observer] Security vulnerability report
17+
```
18+
19+
Include as much of the following as you can:
20+
21+
- A description of the vulnerability and its potential impact
22+
- The file(s) and line number(s) involved
23+
- A minimal reproducible example or proof-of-concept
24+
- Any suggested fix (optional but appreciated)
25+
26+
You will receive an acknowledgement within **72 hours** and a resolution timeline once the issue is assessed. We follow responsible disclosure — please allow us reasonable time to address the issue before any public disclosure.
27+
28+
## Security Considerations for Users
29+
30+
- **Do not log sensitive fields** (passwords, tokens, PII). Use path or header filters in `ObserverConfig` to exclude them.
31+
- **Restrict access to the dashboard** — mount it behind authentication middleware in production.
32+
- **Secure storage files** — JSON and SQLite storage files contain request data; apply appropriate filesystem permissions.
33+
- Keep your `fastapi` and `pydantic` dependencies up to date to pick up upstream security fixes.

‎pyproject.toml‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,35 @@ version = "0.1.0"
88
description = "Logging and observability helpers for FastAPI applications."
99
readme = "README.md"
1010
requires-python = ">=3.10,<3.15"
11-
license = { file = "LICENSE" }
12-
authors = [{ name = "fastapi-observer maintainers" }]
11+
license = "MIT"
12+
authors = [{ name = "Mehraz Hossain Rumman", email = "blackndmaroon@gmail.com" }]
13+
keywords = ["fastapi", "logging", "observability", "middleware", "monitoring"]
14+
classifiers = [
15+
"Development Status :: 3 - Alpha",
16+
"Intended Audience :: Developers",
17+
"Programming Language :: Python :: 3",
18+
"Programming Language :: Python :: 3.10",
19+
"Programming Language :: Python :: 3.11",
20+
"Programming Language :: Python :: 3.12",
21+
"Programming Language :: Python :: 3.13",
22+
"Programming Language :: Python :: 3.14",
23+
"Topic :: Internet :: WWW/HTTP :: HTTP Servers",
24+
"Topic :: Software Development :: Libraries :: Python Modules",
25+
"Topic :: System :: Logging",
26+
]
27+
1328
dependencies = [
1429
"fastapi>=0.100,<1.0",
1530
"pydantic>=2.0,<3.0",
1631
]
1732

33+
[project.urls]
34+
Homepage = "https://github.com/MehrazRumman/fastapi-observer"
35+
Documentation = "https://mehrazrumman.github.io/fastapi-observer/"
36+
Repository = "https://github.com/MehrazRumman/fastapi-observer.git"
37+
Issues = "https://github.com/MehrazRumman/fastapi-observer/issues"
38+
Changelog = "https://github.com/MehrazRumman/fastapi-observer/blob/main/CHANGELOG.md"
39+
1840
[project.optional-dependencies]
1941
test = [
2042
"httpx>=0.24",

0 commit comments

Comments
 (0)
⚡