# 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.

Canonical product and integration documentation lives on https://docs.logister.org/. The app source lives at https://github.com/taimoorq/logister. The public hosted app at https://logister.org/ is secondary to the self-hosting model.

## 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 a project Insights tab that combines Inbox, Activity, and Performance signals into live ECharts views with time windows, live refresh, environment and release filters, custom attribute filters, metric catalog selection, summary cards, event mix, metric series, and recent matching events.
- 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.

## Use Cases And Comparisons

- Self-hosted error monitoring: https://docs.logister.org/use-cases/self-hosted-error-monitoring/
- Sentry alternative: https://docs.logister.org/use-cases/sentry-alternative/
- Bugsnag alternative: https://docs.logister.org/use-cases/bugsnag-alternative/
- Bugzilla alternative: https://docs.logister.org/use-cases/bugzilla-alternative/
- 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 / ASP.NET Core error monitoring: https://docs.logister.org/use-cases/dotnet-error-monitoring/
- JavaScript / TypeScript error monitoring: https://docs.logister.org/use-cases/javascript-error-monitoring/
- ColdFusion / 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 alert emails and digests: https://docs.logister.org/use-cases/amazon-ses-error-alerts/

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

## 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
- Android apps use `logister-android`: https://github.com/taimoorq/logister-android with Maven Central coordinates `org.logister:logister-android:0.1.0` at https://central.sonatype.com/artifact/org.logister/logister-android
- iOS apps use the `Logister` Swift package from https://github.com/taimoorq/logister-ios.git with release tags such as https://github.com/taimoorq/logister-ios/releases/tag/v0.1.0
- CFML apps running on Lucee or Adobe ColdFusion use direct HTTP ingestion.
- Unsupported runtimes, scripts, workers, and custom clients can use the Manual / HTTP API project type and send JSON 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, Android app/release/device metadata, iOS app/release/device metadata, 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.

API tooling lives at https://docs.logister.org/api-reference/. The public OpenAPI contract is available at https://docs.logister.org/openapi.yaml, and the Postman collection is available at https://docs.logister.org/postman/logister-api.postman_collection.json.

## 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.

## Insights

- The project Insights tab is the 2.0 project-level dashboard workspace for live telemetry exploration.
- It helps users see what Logister is collecting at a glance, especially when the project inbox has no active errors but logs, metrics, transactions, spans, check-ins, or performance data are still arriving.
- Best uses include release validation, instrumentation audits, span-backed request load analysis, performance triage, worker or queue monitoring, and narrowing recent events by environment, release, custom dimensions, or metric series.
- Best instrumentation practices: always send stable `environment` and `release` values when available; use stable top-level context keys such as `service`, `region`, `queue`, `route`, `tenant_tier`, or `feature_flag`; avoid raw IDs, emails, request bodies, and high-cardinality values as dashboard dimensions; keep custom metric names consistent; send numeric metric values in `context.value` when average value series should appear in the metric catalog.
- Insights uses PostgreSQL indexes, bounded catalog sampling, and short Redis cache windows for the product UI. Optional ClickHouse remains useful for raw event/span analytics, high-volume custom reporting, and materialized rollups, but is not required for the Insights tab.

## Metrics Reference

- Metrics reference: https://docs.logister.org/metrics/
- Logister collects errors, logs, metrics, transactions, spans, and check-ins. It stores raw events and spans first, then derives dashboard and Insights metrics from those signals.
- Built-in Insights metric keys are `events.total`, `errors.count`, `activity.count`, `logs.count`, `check_ins.count`, `transactions.count`, `transactions.avg`, `transactions.p95`, `db.query.count`, `db.query.avg`, and `db.query.p95`.
- Custom metric events use `event_type: "metric"` and the event message as the metric name. `metric:<name>` charts event count. `metric_value:<name>` charts average numeric `context.value`. The reserved `db.query` metric powers database query count, average duration, and P95 duration.
- Span kinds accepted by the main app include `app`, `browser`, `cache`, `db`, `http`, `internal`, `queue`, `render`, `resource`, and `server`. Root `server` and `browser` spans power request load views.
- Common reporting fields include `environment`, `release`, `service`, `trace_id`, `request_id`, `session_id`, `user_id`, `transaction_name`, `duration_ms`, `value`, `unit`, `tags`, request context, exception context, check-in slug/status, and expected check-in interval.
- The metrics reference includes a matrix for the main app plus Ruby, .NET, Python, JavaScript, Android, iOS, and CFML/HTTP support across errors, logs, custom metrics, DB query timing, transactions, spans, check-ins, environment/release, trace/request correlation, session/user context, and custom dimensions.
- Good context includes route names, HTTP method, status code, deploy release, environment, service, job name, queue name, tenant tier, region, feature flag, sanitized request identifiers, trace/request/session/user IDs, and runtime timings. Avoid secrets, tokens, authorization headers, cookies, payment data, medical data, raw email bodies, and request or response bodies unless deliberately reviewed.

## 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.
- Recommended setup order: provision PostgreSQL and Redis; set `RAILS_ENV`, `RAILS_MASTER_KEY`, `DATABASE_URL`, `REDIS_URL`, `LOGISTER_PUBLIC_URL`, and `LOGISTER_ADMIN_EMAILS`; run `./bin/release`; start one Rails web process and one Sidekiq worker; verify `/up`, sign-in, project creation, API key generation, and one test inbox event; then enable optional services.

## 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, Maven Central, Swift Package Manager tags, `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.

## Canonical Links

- Docs home: https://docs.logister.org/
- Product guide: https://docs.logister.org/product/
- Insights guide: https://docs.logister.org/product/#insights
- Metrics reference: https://docs.logister.org/metrics/
- 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/
- Getting started: https://docs.logister.org/getting-started/
- 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/
- API reference and Swagger UI: https://docs.logister.org/api-reference/
- OpenAPI YAML: https://docs.logister.org/openapi.yaml
- Postman collection: https://docs.logister.org/postman/logister-api.postman_collection.json
- 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/
- Android integration: https://docs.logister.org/integrations/android/
- iOS integration: https://docs.logister.org/integrations/ios/
- CFML integration: https://docs.logister.org/integrations/cfml/
- Android Maven Central package: https://central.sonatype.com/artifact/org.logister/logister-android
- iOS Swift Package release: https://github.com/taimoorq/logister-ios/releases/tag/v0.1.0
- Short AI map: https://docs.logister.org/llms.txt