# LogTap

> LogTap is an open-source (MIT) high-throughput observability data gateway: natively compatible with the Sentry SDK reporting protocol, combining structured log search, event tracking with funnel & retention analytics, health probing, and multi-channel alerting. Built on Go + NSQ, it keeps single-node write P95 latency steadily under 2 ms and deploys privately with one `docker compose` command.

LogTap is built on Go + Gin + NSQ: a stateless HTTP ingest gateway handles auth, deserialization, and queue publishing only, while NSQ decouples it from batch consumer workers that write to PostgreSQL / TimescaleDB (open-source edition) or ClickHouse (enterprise / cloud edition). Official single-node benchmarks (32-core/64 GB, co-located) show P95 write latency of 1.7–1.9 ms at 10–120 concurrent users with 5,600+ EPS, peaking at 11,200 EPS.

This site is available in Chinese (https://logtap-website.autotask.run/) and English (https://logtap-website.autotask.run/en/). Every documentation page below is also served as raw Markdown at the same URL with a `.md` suffix, and `llms-full.txt` next to this file contains all documentation in both languages.

## Docs (English)

- [Overview](https://logtap-website.autotask.run/en/docs/overview.md): What LogTap is and what it does — Sentry-compatible error monitoring plus structured logs, event analytics, and alerting in one observability gateway.
- [Quick Start](https://logtap-website.autotask.run/en/docs/quickstart.md): Bring up LogTap with three Docker Compose commands and send your first structured log.
- [Ingest API](https://logtap-website.autotask.run/en/docs/ingest-api.md): The HTTP reporting protocol for custom logs and tracking events — endpoints, auth, data model, batching, and gzip.
- [Sentry Compatibility](https://logtap-website.autotask.run/en/docs/sentry-compat.md): Adopt LogTap with zero code changes — swap one line of DSN. Store / Envelope protocols implemented natively, with historical data migration.
- [SDKs](https://logtap-website.autotask.run/en/docs/sdks.md): Official LogTap client SDKs — JavaScript/TypeScript (Browser/Node), Go, and Flutter, with batch buffering, gzip, and automatic retries.
- [Deployment](https://logtap-website.autotask.run/en/docs/deployment.md): Deploying LogTap to production — Docker Compose, non-Docker (systemd), environment variables, and production advice.

## 文档（中文）

- [概览](https://logtap-website.autotask.run/docs/overview.md): LogTap 是什么、能做什么：Sentry 协议兼容的异常监控 + 结构化日志 + 事件埋点 + 告警，一体化可观测性网关。
- [快速开始](https://logtap-website.autotask.run/docs/quickstart.md): 用 Docker Compose 三条命令把 LogTap 跑起来，发出第一条结构化日志。
- [上报接口](https://logtap-website.autotask.run/docs/ingest-api.md): LogTap 自定义日志与埋点事件的 HTTP 上报协议：端点、鉴权、数据模型、批量与 gzip。
- [Sentry 兼容](https://logtap-website.autotask.run/docs/sentry-compat.md): 零改动接入现有 Sentry SDK：改一行 DSN 即可，Store / Envelope 协议原生实现，历史数据可迁移。
- [SDK](https://logtap-website.autotask.run/docs/sdks.md): LogTap 官方客户端 SDK：JavaScript/TypeScript（Browser/Node）、Go、Flutter，批量缓冲、gzip、自动重试。
- [部署指南](https://logtap-website.autotask.run/docs/deployment.md): LogTap 生产部署：Docker Compose、无 Docker（systemd）、环境变量与生产建议。

## Benchmarks (open-source edition, single node)

| Concurrency | Actual throughput | P95 | P99 |
| --- | --- | --- | --- |
| 10 VU | 467 EPS | 1.8 ms | 2.4 ms |
| 40 VU | 1,867 EPS | 1.9 ms | 3.3 ms |
| 120 VU | 5,600 EPS | 1.7 ms | 2.8 ms |
| 160 VU (knee point) | 7,463 EPS | 163.9 ms | 556.2 ms |

- Peak ingest: 10,000–20,000 EPS (open source) vs 100,000–300,000+ EPS (enterprise/cloud)
- Storage compression: 1:1.5–1:2 (PostgreSQL row store) vs 1:5–1:10 (ClickHouse column store, LZ4/ZSTD)
- Analytics over 100M+ events: 3–10 s (open source) vs 0.1–0.5 s (enterprise, vectorized engine)

## Quick start

```bash
git clone https://github.com/aak1247/logtap.git
cd logtap/deploy
# Generate AUTH_SECRET (base64, >= 32 bytes decoded)
bash ../scripts/gen-auth-secret.sh
# Start — ships with Postgres/TimescaleDB, Redis, NSQ
docker compose up -d
```

## FAQ

- **Already on Sentry — does migration require code changes?** No: the Store / Envelope protocols are natively implemented, so changing the DSN host is enough.
- **Open-source vs enterprise?** Open source: PostgreSQL / TimescaleDB, 10,000+ EPS, batteries included. Enterprise/cloud: ClickHouse, 100,000–300,000+ EPS, 1:5–1:10 compression, sub-second analytics at 100M+ events.
- **Free? License?** The open-source edition is free under MIT, usable in commercial projects.
- **Private deployment?** Fully supported — data lands only in your own databases; GeoIP uses the offline GeoLite2 bundle, with no external calls.

## Links

- [GitHub repository](https://github.com/aak1247/logtap)
- [Technical design docs](https://github.com/aak1247/logtap/blob/main/docs/OVERVIEW.md)
- [Issues & feedback](https://github.com/aak1247/logtap/issues)
- [Online console](https://logtap.autotask.run/)