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

The docs are organized as a practical self-hosted product manual: Documentation, Installation, Configuration, Usage, Integrations, API reference, and Troubleshooting. Feature explanations should define the concept, explain why it exists, show how users interact with it, name common failure modes, and point to the next guide.

## 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, environment, and source/deployment context when integrations provide them.
- Supports optional project-scoped GitHub App source integration for private repository source excerpts, CODEOWNERS hints, explicit repository connections, deployment links, and GitHub issue creation when Issues write permission is granted.
- 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.1` 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.1
- 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. Maintained SDKs can send source context (`repository`, `commit_sha`, and `branch`) on events. JavaScript, Python, .NET, and Ruby SDKs also expose deployment-record helpers; Android and iOS attach source context in-app and expect CI/CD to POST deployment records to `/api/v1/deployments`.

Public ingestion endpoints `/api/v1/ingest_events`, `/api/v1/check_ins`, and `/api/v1/deployments` 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.

Source-linked debugging works best when SDKs and custom clients send `repository`, `commit_sha`, `branch`, `release`, and `environment` on error events. CI/CD can also POST a `deployment` envelope to `/api/v1/deployments` with `release`, `repository`, `commit_sha`, optional `branch`, `deployed_at`, `pull_request_number`, `release_tag`, and GitHub URLs so Logister can show source excerpts, PR/release links, and "this started after deploy X" context.

GitHub App setup docs live at https://docs.logister.org/github-app/. Self-hosters create their own GitHub App instead of storing personal access tokens. Required variables are `LOGISTER_GITHUB_APP_ID`, `LOGISTER_GITHUB_APP_PRIVATE_KEY`, `LOGISTER_GITHUB_WEBHOOK_SECRET`, and either `LOGISTER_GITHUB_APP_SLUG` or `LOGISTER_GITHUB_APP_INSTALL_URL`; GitHub Enterprise Server installs can also set `LOGISTER_GITHUB_API_URL` and `LOGISTER_GITHUB_WEB_URL`. Project owners and project admins install or link GitHub App installations from project settings, sync repository metadata, and explicitly connect the repositories each project should use. Syncing or telemetry alone does not create source mappings.

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.

Troubleshooting lives at https://docs.logister.org/troubleshooting/. It covers quick baseline checks, empty inboxes, rejected events, API status codes, Sidekiq worker issues, SMTP delivery, optional ClickHouse readiness, S3-compatible archive exports, and what support context to collect without sharing secrets.

## 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 GitHub App source integration for private repository access without personal tokens.
- Optional Cloudflare Turnstile for auth bot protection.
- Optional Cloudflare Pages for static docs hosting.
- Optional Logister self-observability through `logister-ruby`; configure `LOGISTER_API_KEY`, `LOGISTER_ENDPOINT`, source fields such as `LOGISTER_REPOSITORY`, `LOGISTER_COMMIT_SHA`, and `LOGISTER_BRANCH`, then run `bin/rails logister:sample_telemetry` to emit a sample error, log, metric, transaction, span set, check-in, and deployment record.
- 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.6.1` or `docker.io/taimoorq/logister:v2.6.1`
- 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/
- GitHub App source integration: https://docs.logister.org/github-app/
- 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/
- Troubleshooting: https://docs.logister.org/troubleshooting/
- 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.1
- Short AI map: https://docs.logister.org/llms.txt