When to enable it
Stay on PostgreSQL first, then add ClickHouse when analytics volume justifies it.
You do not need ClickHouse to use Logister. The app can ingest events, group errors, show activity, track monitors, and run the project UI with PostgreSQL and Redis alone. Add ClickHouse when you want a dedicated store for heavier event analysis, longer raw-event exploration, or separation between the everyday product experience and high-volume analytics queries.
| Keep ClickHouse off when... | Turn it on when... |
|---|---|
| You are evaluating Logister or monitoring a small number of services. | You are sending enough events that analytics queries should not compete with normal app usage. |
| You only need the inbox, activity feed, performance summaries, and monitor pages at modest volume. | You want to run custom high-volume event queries outside the normal UI. |
| You do not have an operator ready to own ClickHouse backups, schema, and health checks. | You already operate ClickHouse or can use managed ClickHouse Cloud. |
What changes
ClickHouse is an additional analytics copy, not a replacement for the app database.
When ClickHouse is enabled, Logister still uses PostgreSQL for the product experience users interact with. New events and trace spans are also queued for ClickHouse so operators can query raw data and rollups at analytics scale. Keep the Sidekiq worker running, because the web request accepts the event first and background work performs the ClickHouse write.
No automatic historical backfill
The current ClickHouse path writes newly ingested events and spans. If you enable ClickHouse after running Logister for a while, plan a separate historical export/backfill workflow if you need old telemetry in ClickHouse too.
Insights
The Insights tab works with PostgreSQL and Redis first.
The project Insights workspace uses PostgreSQL indexes, bounded catalog sampling, and short Redis cache windows for its live UI. You can use Insights without ClickHouse, including time-window charts, environment and release filters, custom attribute filters, metric catalog selection, and recent matching events.
ClickHouse is still useful when you want longer-range raw analytics, high-volume custom reporting, or materialized rollups such as events_1m and request_spans_1m. Treat ClickHouse as an optional analytics copy rather than a requirement for the Insights tab.
Environment
Set the ClickHouse connection variables explicitly.
LOGISTER_CLICKHOUSE_ENABLED=true
LOGISTER_CLICKHOUSE_URL=http://127.0.0.1:8123
LOGISTER_CLICKHOUSE_DATABASE=logister
LOGISTER_CLICKHOUSE_EVENTS_TABLE=events_raw
LOGISTER_CLICKHOUSE_SPANS_TABLE=spans_raw
LOGISTER_CLICKHOUSE_USERNAME=default
LOGISTER_CLICKHOUSE_PASSWORD=
LOGISTER_CLICKHOUSE_FAILURE_THROTTLE_SECONDS=60
REDIS_URL=redis://127.0.0.1:6379/0LOGISTER_CLICKHOUSE_URL can point at either a native ClickHouse HTTP endpoint or the ClickHouse Cloud Query API endpoint. Redis is included here because ClickHouse writes are queued through the background worker.
Schema setup
Initialize schema and keep the starter SQL nearby.
- Schema, raw event/span tables, and materialized views:
docs/clickhouse_schema.sql - Starter dashboard queries:
docs/clickhouse_dashboard_queries.sql
bin/rails logister:clickhouse:schema:status
bin/rails logister:clickhouse:schema:load
bin/rails logister:clickhouse:schema:statusThe schema status task reports whether the required tables and materialized views exist. The schema load task reads docs/clickhouse_schema.sql through the configured ClickHouse connection, so it works the same way locally and in production.
Manual SQL option
If you operate ClickHouse outside the Rails host, you can still apply docs/clickhouse_schema.sql directly with your ClickHouse client. Afterward, run the Rails status task or call /health/clickhouse from the app to verify the app can see the same schema.
Worker path
Keep Sidekiq running before you rely on ClickHouse.
Accepted events and spans queue background writes. If the web app can reach ClickHouse but the worker is not running, new telemetry can still appear in the normal Logister UI while ClickHouse stays empty. When self-observability is configured with LOGISTER_API_KEY and LOGISTER_ENDPOINT, ClickHouse write failures are reported through logister-ruby as throttled logs and count metrics so one outage does not create an internal event storm.
bundle exec sidekiq -C config/sidekiq.ymlHealth checks
Use the health endpoint to verify connectivity and schema readiness.
GET /health/clickhousereturns200when ClickHouse is disabled.GET /health/clickhousereturns200when ClickHouse is enabled, reachable, and the required schema is present.GET /health/clickhousereturns503when ClickHouse is enabled but unreachable or missing required tables/views. The response includes readiness state and missing table names when Logister can determine them.
After the health check passes, send a test event and span, then confirm the worker writes them before you rely on ClickHouse for reporting.
What to query
Use ClickHouse for raw event analytics, root span rollups, and custom reporting.
The starter SQL creates events_raw, spans_raw, events_1m, request_spans_1m, and matching materialized views. The most useful query dimensions usually match the context your integrations send: project, event type, environment, release, service, exception class, transaction name, span kind, route, tags, and the original context JSON.
| Question | Useful fields |
|---|---|
| Which services are producing the most errors? | Project, service, event type, exception class, release. |
| Which releases changed event volume? | Release, event type, occurred time, environment. |
| Which transactions are slowest? | Transaction name, duration, status, route, service. |
| Which request or page-load roots are slowest? | spans_raw or request_spans_1m, trace ID, route, span kind, duration, service. |
| Which custom tags matter most? | Tags plus the full context JSON for app-specific dimensions. |