Metadata-Version: 2.4
Name: fact-telemetry
Version: 0.1.0a2
Summary: An asynchronous telemetry framework for FastAPI with pluggable storage backends.
Author-email: Mohammed Fayaz Ahamed <mdfayaz20061998@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/Mohammed-Fayaz-Ahamed/fact
Project-URL: Repository, https://github.com/Mohammed-Fayaz-Ahamed/fact
Project-URL: Issues, https://github.com/Mohammed-Fayaz-Ahamed/fact/issues
Keywords: fastapi,telemetry,observability,middleware,clickhouse,postgresql,async,analytics,logging
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software 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 :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Monitoring
Requires-Python: <4.0,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.0
Requires-Dist: starlette>=0.46.0
Requires-Dist: clickhouse-connect>=0.8.0
Requires-Dist: psycopg[binary]>=3.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=1.0; extra == "dev"
Requires-Dist: httpx>=0.28; extra == "dev"
Requires-Dist: uvicorn>=0.35; extra == "dev"
Dynamic: license-file

# FACT

**FACT (FastAPI Advanced Collection Telemetry)** is a lightweight, asynchronous telemetry framework for FastAPI applications.

FACT captures request telemetry through middleware, validates telemetry records, buffers them in an asynchronous in-memory queue, and persists them to configurable storage backends using batched writes. The framework is designed to minimize request overhead while providing reliable telemetry collection through retry mechanisms, dead-letter queue (DLQ) support, and runtime metrics.

FACT currently supports PostgreSQL and ClickHouse storage backends and provides a configurable architecture suitable for high-throughput, multi-tenant applications.

> **Status:** Alpha Development

---

## Features

- Middleware-based automatic telemetry collection
- Asynchronous in-memory queue
- Configurable batch processing
- PostgreSQL storage backend
- ClickHouse storage backend
- Multi-tenant request support
- Dynamic metadata support
- Payload validation
- Exponential backoff retry mechanism
- Local file-based Dead Letter Queue (DLQ)
- Runtime telemetry metrics
- Centralized configuration using `FactConfig`
- Environment variable support
- Automated test suite
- Benchmark and soak testing utilities

---

## Architecture

```text
                Incoming Request
                       │
                       ▼
        ClickHouseTelemetryMiddleware
                       │
                       ▼
            Payload Validation
                       │
                       ▼
           Async In-Memory Queue
                       │
                       ▼
              Batch Collection
                       │
                       ▼
           Retry with Backoff
                       │
             ┌─────────┴─────────┐
             │                   │
             ▼                   ▼
      Storage Backend        Dead Letter Queue
             │
             ▼
 PostgreSQL / ClickHouse
```

FACT separates request processing from persistence by using an asynchronous producer-consumer architecture. Incoming requests enqueue telemetry records immediately, while a background worker batches and persists records independently. This minimizes request latency and provides resilience during temporary storage failures.

---

## Documentation

Detailed documentation is available in the `docs/` directory.

- Installation
- Quick Start
- Architecture
- Configuration
- Storage Backends
- Middleware
- Benchmarking
- Roadmap

---

## Project Status

FACT is currently in **Alpha Development**.

Implemented capabilities include:

- Middleware-based telemetry ingestion
- Batch processing engine
- PostgreSQL backend
- ClickHouse backend
- Retry with exponential backoff
- Dead Letter Queue (DLQ)
- Payload validation
- Runtime metrics
- Benchmarking utilities
- Automated tests

---

## License

This project is licensed under the Apache License 2.0.

See the [LICENSE](LICENSE) file for details.
