Metadata-Version: 2.4
Name: nilalytics
Version: 0.3.0
Summary: Serverless realtime analytics: OTLP events -> DuckLake on object storage (S3/GCS/R2/Azure), served over Quack.
Project-URL: Homepage, https://angelerator.github.io/nilalytics/
Project-URL: Documentation, https://angelerator.github.io/nilalytics/
Project-URL: Repository, https://github.com/Angelerator/nilalytics
Project-URL: Issues, https://github.com/Angelerator/nilalytics/issues
Author: Angelerator
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: analytics,duckdb,ducklake,lakehouse,mobile-analytics,observability,opentelemetry,otlp,product-analytics,web-analytics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: Log Analysis
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Requires-Dist: duckdb>=1.5.3
Requires-Dist: pytz>=2024.1
Requires-Dist: requests>=2.31
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9; extra == 'docs'
Description-Content-Type: text/markdown

# nilalytics

[![PyPI](https://img.shields.io/pypi/v/nilalytics)](https://pypi.org/project/nilalytics/)
[![Python](https://img.shields.io/pypi/pyversions/nilalytics)](https://pypi.org/project/nilalytics/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-angelerator.github.io-14b8a6)](https://angelerator.github.io/nilalytics/)

**The batteries‑included, OpenTelemetry‑native way to run your own web & mobile product analytics — on a DuckLake in your object storage.**

nilalytics collects product events, errors, and performance data over
[OpenTelemetry](https://opentelemetry.io/) (OTLP), stores them in a
[DuckLake](https://ducklake.select/) lakehouse on any major cloud's object
storage, and serves sub‑second reads over DuckDB's [Quack](https://duckdb.org/docs/stable/core_extensions/quack) protocol — no warehouse, no per‑event fees, no data leaving your infrastructure.

- **Web, mobile _and_ backends:** Grafana Faro (web), OpenTelemetry SDKs (mobile + server) → OTLP. Record user actions *and* whether the backend calls behind them succeeded — in one lake.
- **Runs on any cloud:** S3, MinIO, Google Cloud Storage, Cloudflare R2, or Azure / ADLS Gen2.
- **Small files solved:** DuckLake data inlining keeps streaming writes fast and cheap.
- **Batteries included:** funnels, retention, errors, traces, metrics, cross‑device identity.
- **Secure by default:** token‑authenticated ingest, read‑only query authz, a hardened public gateway.

📖 **Full documentation:** <https://angelerator.github.io/nilalytics/>

## Install

```bash
pip install nilalytics
```

> Also works with `pipx install nilalytics` or `uv tool install nilalytics`.
> Bleeding edge from source: `pip install git+https://github.com/Angelerator/nilalytics`.

## 60‑second local demo

```bash
# 1. object storage (local MinIO)
minio server .minio-data --address 127.0.0.1:9100 --console-address 127.0.0.1:9101 &
mc alias set nila http://127.0.0.1:9100 minioadmin minioadmin
mc mb --ignore-existing nila/nilalytics

# 2. run the pipeline
nilalytics server &      # ingest + Quack catalog
nilalytics gateway &     # public ingest gateway (CORS + tokens)

# 3. send + query
nilalytics emit --count 200 --persons 5
nilalytics query report
```

## Architecture

```mermaid
flowchart LR
  W["Web · Grafana Faro"] -->|OTLP + token| GW
  M["Mobile · OpenTelemetry"] -->|OTLP + token| GW
  GW["Ingest Gateway<br/>CORS · tokens · TLS"] --> SRV["OTLP server<br/>(duckdb-otlp)"]
  B["Backend services · OpenTelemetry"] -->|"OTLP · private net"| SRV
  SRV --> LAKE[("DuckLake<br/>DuckDB + Quack catalog<br/>+ Parquet on object storage")]
  LAKE --> READ["Reads: DuckDB / DuckDB-WASM<br/>over Quack"]
```

## Acknowledgements

nilalytics stands on the shoulders of giants. Huge thanks to
[DuckDB](https://duckdb.org/), [DuckLake](https://ducklake.select/) and Quack (DuckDB Labs / DuckDB Foundation),
[duckdb‑otlp](https://github.com/smithclay/duckdb-otlp) ([@smithclay](https://github.com/smithclay)),
[OpenTelemetry](https://opentelemetry.io/) (CNCF),
[Grafana Faro](https://github.com/grafana/faro-web-sdk) (Grafana Labs),
and [MinIO](https://min.io/) — plus the projects that inspired it:
[canardstack](https://github.com/smithclay/canardstack),
[icelight](https://github.com/cliftonc/icelight), and
[stratif.io](https://stratif.io/).

Full credits and dependency list: [Acknowledgements](https://angelerator.github.io/nilalytics/acknowledgements/).

## License

[Apache‑2.0](LICENSE) © Angelerator

