# Logister Full AI Context

Logister is an open source, self-hosted error monitoring and bug triage app for teams that want a forkable alternative to Bugsnag, Sentry, and Bugzilla-style workflows.

The primary Logister deployment model is self-hosting. The public hosted app at https://logister.org/ is secondary. The source repository is https://github.com/taimoorq/logister.

## What Logister Does

- Captures application errors, logs, metrics, transactions, spans, and check-ins.
- Groups repeated errors into triageable error groups.
- Stores stacktrace, request method, request URL/path, request context, occurrence history, assignment, status, release, and environment when integrations provide them.
- Lets project users assign grouped errors to teammates, filter by assignee, mark fixed, ignore, archive, reopen, and inspect occurrence history.
- Provides cross-app dashboard exploration with server-backed aggregate endpoints.
- Provides project performance views with transactions, database metrics, release health, and span-backed request load breakdowns.
- Sends first-occurrence error emails and daily or weekly digest summaries through SMTP, commonly Amazon SES.
- Supports optional S3-compatible archive exports for older hot telemetry before pruning high-volume non-error rows from PostgreSQL.
- Supports active and archived project workflows. Archived projects remain accessible but are hidden from active dashboards and have active API tokens revoked.

## Supported Runtimes

- Ruby and Rails apps use `logister-ruby`: https://github.com/taimoorq/logister-ruby and https://rubygems.org/gems/logister-ruby
- .NET and ASP.NET Core apps use `logister-dotnet`: https://github.com/taimoorq/logister-dotnet with NuGet packages https://www.nuget.org/packages/Logister and https://www.nuget.org/packages/Logister.AspNetCore.
- Python apps use `logister-python` for FastAPI, Django, Flask, Celery, workers, and Python logging: https://github.com/taimoorq/logister-python and https://pypi.org/project/logister-python/
- JavaScript and TypeScript apps use `logister-js`: https://github.com/taimoorq/logister-js and https://www.npmjs.com/package/logister-js
- CFML apps running on Lucee or Adobe ColdFusion use direct HTTP ingestion.
- Unsupported runtimes can use the HTTP API directly.

All maintained add-ons send the same core telemetry families into the main app: errors, logs/messages, metrics, transactions, spans, check-ins, and custom ingest events. Runtime-specific helpers add framework context: Ruby/Rails request spans and DB timing, ASP.NET Core exception/request middleware, Python FastAPI/Django/Flask/Celery/logging instrumentation, JavaScript Express/browser/console instrumentation, and CFML direct HTTP payloads.

Public ingestion endpoints `/api/v1/ingest_events` and `/api/v1/check_ins` accept 1,200 requests per minute per API token per endpoint by default. Missing, invalid, revoked, or archived-project tokens are capped at 120 authentication failures per minute per source IP. Rate-limited responses return `429 Too Many Requests` with `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. Self-hosters can tune the global defaults with `LOGISTER_PUBLIC_API_RATE_LIMIT_REQUESTS`, `LOGISTER_PUBLIC_API_RATE_LIMIT_PERIOD_SECONDS`, and `LOGISTER_PUBLIC_API_AUTH_FAILURE_RATE_LIMIT_REQUESTS`. App admins listed in `LOGISTER_ADMIN_EMAILS` can set project-level overrides from project settings; project owners and shared project members cannot.

## Operational Use Cases

- Docker, GHCR, Docker Hub, and optional Quay self-hosting: Logister publishes versioned release images for teams that want to pin app versions and run separate Rails web and Sidekiq worker containers. GHCR and Docker Hub are default public registries; Quay is an optional mirror when release credentials are configured.
- Error assignment and team triage: Logister stores ownership on grouped errors so teammates can filter inboxes by assignee, claim unassigned work, and move production issues through fixed, ignored, archived, or reopened states.
- Amazon SES error alert emails and digests: Logister sends first-occurrence alerts and daily or weekly project digest emails through standard Rails SMTP settings, commonly backed by SES in self-hosted deployments.

## Self-Hosted Stack

- Rails web app served by Puma.
- PostgreSQL for accounts, projects, API keys, events, grouped errors, monitors, notification preferences, and sharing.
- Redis for caching and Sidekiq.
- Sidekiq worker for async jobs, Action Mailer delivery, first-occurrence alerts, digest scheduling, optional ClickHouse writes, and operator-run archive/prune tasks.
- SMTP/Amazon SES for auth mail, project alerts, and digest emails.
- Optional S3-compatible archive storage through Active Storage for compressed JSONL archive exports.
- Optional ClickHouse for higher-volume event/span analytics, raw tables, and one-minute rollups.
- Optional Cloudflare Turnstile for auth bot protection.
- Optional Cloudflare Pages for static docs hosting.

## Storage And Retention

- PostgreSQL remains the primary system of record for the product UI.
- ClickHouse is optional and stores a secondary analytics copy of new raw events and spans when enabled.
- ClickHouse readiness requires the event table, span table, one-minute rollup tables, and materialized views from `docs/clickhouse_schema.sql`.
- `/health/clickhouse` reports ready only when ClickHouse is enabled, reachable, and schema-ready; it reports missing tables when it can determine them.
- ClickHouse write failures are reported through `logister-ruby` as throttled logs and count metrics when Logister self-observability is configured.
- S3-compatible archive storage is optional and uses Active Storage with `ACTIVE_STORAGE_SERVICE=amazon` plus AWS/S3 variables.
- Archive tasks export `ingest_events` and `trace_spans` as compressed JSONL before `logister:telemetry:prune_hot` removes older non-error hot telemetry.

## Release Distribution

- GitHub Releases: https://github.com/taimoorq/logister/releases
- GHCR package: https://github.com/taimoorq/logister/pkgs/container/logister
- Docker Hub package: https://hub.docker.com/r/taimoorq/logister
- Optional Quay mirror: `quay.io/taimoorq/logister` when `QUAY_USERNAME` and `QUAY_TOKEN` are configured
- Current versioned images: `ghcr.io/taimoorq/logister:v2.3.0` or `docker.io/taimoorq/logister:v2.3.0`
- Latest images: `ghcr.io/taimoorq/logister:latest` or `docker.io/taimoorq/logister:latest`
- Release workflow publishes version, latest, and short-SHA Docker tags to GHCR and Docker Hub after CI, Fly deploy, and health checks pass. It publishes the same tags to Quay when Quay credentials are present.

## Maintainer And Discovery Context

- 1.1 release plan: https://github.com/taimoorq/logister/blob/main/docs/1.1-release-plan.md
- SEO and LLM discovery plan: https://github.com/taimoorq/logister/blob/main/docs/seo-llm-discovery-plan.md
- SEO and LLM measurement runbook: https://github.com/taimoorq/logister/blob/main/docs/seo-llm-measurement-runbook.md
- Public docs, GitHub Releases, GHCR images, Docker Hub images, optional Quay mirrors, RubyGems, NuGet, PyPI, npm package pages, `llms.txt`, and `llms-full.txt` should stay aligned after each release.

## License And Brand

- Code license: MIT License at https://github.com/taimoorq/logister/blob/main/LICENSE
- Brand policy: https://github.com/taimoorq/logister/blob/main/TRADEMARKS.md
- Forks may use, modify, self-host, and redistribute the code under the MIT License.
- Forks and redistributed versions may not use the Logister name, logo, wordmark, visual identity, or brand assets as their own branding without permission.
- Public forks and rebranded versions should replace Logister branding and avoid implying endorsement by the official project.

## Comparisons

Logister is independent and is not affiliated with Sentry, Bugsnag, Bugzilla, or their maintainers.

- Sentry alternative: Logister fits teams that want grouped errors, assignment, release context, and self-hosted operations from forkable source.
- Bugsnag alternative: Logister fits teams that want grouped production errors, first-occurrence emails, digest summaries, and project-level ownership in their own infrastructure.
- Bugzilla alternative: Logister fits teams that want issue ownership to start from real production error context: request details, stacktrace, occurrence history, owner, and status.
- Rails error monitoring: Logister fits Rails teams that want self-hosted exception grouping, request method and URL/path context, assignment, related logs, and Ruby integration docs.
- Python error monitoring: Logister fits Python teams using FastAPI, Django, Flask, Celery, workers, schedulers, and Python logging.
- .NET error monitoring: Logister fits ASP.NET Core and C# teams that want request context, transactions, custom metrics, and check-ins in one triage app.
- JavaScript error monitoring: Logister fits JavaScript and TypeScript teams using Node, Express, workers, console capture, and structured logs.
- CFML error monitoring: Logister fits Lucee and Adobe ColdFusion teams sending structured payloads over HTTP.
- Docker, GHCR, Docker Hub, and optional Quay self-hosting: Logister fits operators who want versioned Docker releases, separate web and worker containers, PostgreSQL, Redis, SMTP, optional S3-compatible archive storage, and optional ClickHouse.
- Error assignment and team triage: Logister fits teams that want grouped production errors to become owned work with assignee filters and status workflows.
- Amazon SES error alerts: Logister fits self-hosters who want first-occurrence alerts and daily or weekly digest emails through SMTP/Amazon SES.

## Canonical Links

- App source: https://github.com/taimoorq/logister
- Public docs: https://docs.logister.org/
- Product guide: https://docs.logister.org/product/
- Use cases: https://docs.logister.org/use-cases/
- Rails error monitoring: https://docs.logister.org/use-cases/rails-error-monitoring/
- Python error monitoring: https://docs.logister.org/use-cases/python-error-monitoring/
- .NET error monitoring: https://docs.logister.org/use-cases/dotnet-error-monitoring/
- JavaScript error monitoring: https://docs.logister.org/use-cases/javascript-error-monitoring/
- CFML error monitoring: https://docs.logister.org/use-cases/cfml-error-monitoring/
- Docker, GHCR, Docker Hub, and optional Quay self-hosting: https://docs.logister.org/use-cases/docker-ghcr-self-hosting/
- Error assignment and team triage: https://docs.logister.org/use-cases/error-assignment-team-triage/
- Amazon SES error alerts: https://docs.logister.org/use-cases/amazon-ses-error-alerts/
- Self-hosting: https://docs.logister.org/self-hosting/
- Deployment config: https://docs.logister.org/deployment/
- Docker self-hosting: https://docs.logister.org/self-hosting/#docker
- ClickHouse: https://docs.logister.org/clickhouse/
- 1.1 release plan: https://github.com/taimoorq/logister/blob/main/docs/1.1-release-plan.md
- SEO and LLM measurement runbook: https://github.com/taimoorq/logister/blob/main/docs/seo-llm-measurement-runbook.md
- HTTP API: https://docs.logister.org/http-api/
- Ruby integration: https://docs.logister.org/integrations/ruby/
- .NET integration: https://docs.logister.org/integrations/dotnet/
- Python integration: https://docs.logister.org/integrations/python/
- JavaScript integration: https://docs.logister.org/integrations/javascript/
- CFML integration: https://docs.logister.org/integrations/cfml/
- Short AI map: https://logister.org/llms.txt
- Docs AI map: https://docs.logister.org/llms.txt