Collected telemetry
Logister accepts six event families plus trace spans.
All families can include common context such as environment, release, trace_id, request_id, session_id, user_id, transaction_name, and duration_ms. CamelCase aliases such as traceId, requestId, transactionName, and durationMs are accepted where the app reads them.
| Family | Important fields | Useful for |
|---|---|---|
| Errors | event_type: "error", message, level, fingerprint, exception and request context. | Grouped issue triage, ownership, release regressions, and related-log investigation. |
| Logs | event_type: "log", message, level, fingerprint, context attributes. | Operational breadcrumbs, warning volume, deploy notes, and context around errors. |
| Metrics | event_type: "metric", message as metric name, optional context.value, context.unit, or duration. | Business or app measurements such as queue depth, job counts, cache rate, and the reserved db.query timing metric. |
| Transactions | event_type: "transaction", transaction name, duration, status, route, optional timing breakdowns. | Request, task, and job latency; slow endpoint review; and SLO-style trends. |
| Spans | event_type: "span", trace ID, span ID, parent span ID, name, kind, status, duration, start/end time. | Request waterfalls and load breakdowns. Root server and browser spans represent top-level requests or page loads. |
| Check-ins | event_type: "check_in" or /api/v1/check_ins, slug, status, expected interval, optional duration. | Scheduled jobs, workers, cron tasks, and heartbeat monitors with derived ok, error, and missed states. |
Support matrix
The main app receives and displays the data; add-ons help each runtime send it.
CFML uses direct HTTP payloads instead of a separate package. The HTTP API accepts the same event shapes for custom or unsupported runtimes.
| Feature | Main app | Ruby | .NET | Python | JavaScript | CFML / HTTP |
|---|---|---|---|---|---|---|
| Error events | Receives, groups, assigns, and displays occurrences. | Automatic Rails errors and manual errors. | ASP.NET Core middleware and manual exceptions. | FastAPI, Django, Flask, Celery, logging exceptions, and manual exceptions. | Express middleware, console errors, and manual exceptions. | Direct error payloads. |
| Log events | Receives and shows activity/detail views. | Logister.report_log. | CaptureMessageAsync. | Python logging integration and manual messages. | instrumentConsole() and manual messages. | Direct log payloads. |
| Custom metric counts | Charts metric:<name> counts. | Metric reporting. | CaptureMetricAsync. | capture_metric. | captureMetric. | Direct metric payloads. |
| Custom metric values | Charts metric_value:<name> when context.value is numeric. | Sends value and unit context. | Sends value and unit context. | Sends value and unit context. | Sends value and unit context. | Direct context.value and context.unit. |
| Database query timing | Charts reserved db.query count, average, and P95 duration. | ActiveRecord DB metric instrumentation. | Direct metric support for DB timing. | Direct metric support for DB timing. | Direct metric support for DB timing. | Direct db.query metric payloads. |
| Transactions | Charts counts, average duration, and P95 duration. | Rails/request and manual transactions. | ASP.NET Core request and manual transactions. | Framework request/task and manual transactions. | Express/request, browser, job, and manual transactions. | Direct transaction payloads. |
| Spans | Builds request load breakdowns. | Manual spans and opt-in Rails request spans. | Manual spans and opt-in ASP.NET Core request spans. | Manual spans and opt-in FastAPI/Django/Flask request spans. | Manual spans, Express request spans, and browser page/resource spans. | Direct root and child span payloads. |
| Check-ins | Tracks monitor state and missed status. | Cron, scheduler, and worker check-ins. | Worker and scheduled-task check-ins. | Celery and manual check-ins. | Job/script check-ins. | Direct check-in endpoint or payloads. |
| Environment and release | Filters, release health, and event detail. | Supported on capture paths. | Supported on capture paths. | Supported on capture paths. | Supported on capture paths. | Direct fields or context. |
| Trace/request correlation | Related logs, event detail, transaction/spans, and ClickHouse fields. | Trace ID and request ID options. | Trace ID and request ID options. | Trace ID and request ID options. | Trace ID and request ID options. | Direct fields or context. |
| Session/user context | Event detail, related context, and attribute visibility. | Session ID and user ID options. | Session ID and user ID options. | Session ID and user ID options. | Session ID and user ID options. | Direct fields or context. |
| Custom dimensions | Insights filters for safe scalar context. | Custom context and tags. | Custom context and tags. | Custom context and tags. | Custom context and tags. | Direct context and tags. |
Mobile add-ons
Android and iOS use package-manager add-ons that send the same event envelope.
Mobile telemetry should include platform, service, release, environment, session_id, source context, and safe app/device metadata. Android should use the package name as service; iOS should use the bundle ID.
| Platform | Package | Package manager | Current support |
|---|---|---|---|
| Android | org.logister:logister-android | Maven Central / Gradle | Kotlin-first helpers with Java interop for manual errors, logs, metrics, transactions, spans, check-ins, and source context. |
| iOS | Logister from https://github.com/taimoorq/logister-ios.git | Swift Package Manager | Async Swift client for manual errors, logs, metrics, transactions, spans, check-ins, and source context. |
Read the Android integration guide or iOS integration guide for install snippets, setup examples, release details, and privacy boundaries.
Reporting guide
Send the fields that power the views your developers use.
| Field or context | Accepted aliases | Powers |
|---|---|---|
event_type | eventType | Controls the storage and UI path: error, log, metric, transaction, span, or check-in. |
message | name for spans | Primary label in inbox, activity, event detail, metric catalog, and span views. |
fingerprint | None | Stable grouping for repeated errors or recurring operational signals. |
environment | Top-level or context | Environment filters, event detail, ClickHouse dimensions, and monitor separation. |
release | Top-level or context | Release filters, release health, event detail, and ClickHouse dimensions. |
service | Top-level or context | Service attribution and custom filtering when sent as scalar context. |
trace_id | traceId, nested trace.traceId | Related logs, event correlation, spans, and analytics dimensions. |
request_id | requestId, nested trace.requestId | Related logs, request detail, spans, and analytics dimensions. |
session_id | sessionId | Session-scoped investigation context. |
user_id | userId, nested user.id | User-scoped investigation context. |
transaction_name | transactionName | Transaction labels, performance views, event detail, and analytics dimensions. |
duration_ms | durationMs | Transaction duration, db.query duration, event detail, span duration, and optional check-in runtime. |
value | None | Custom metric average series when numeric. |
unit | None | Human-readable unit for custom metric values. |
tags | None | Tag maps for ClickHouse and event context when integrations send them. |
request | Runtime-specific request context | Request method, URL/path highlights, and investigation context. |
exception | exception_class | Error detail and analytics exception dimensions. |
check_in_slug | monitor_slug, check-in slug | Monitor identity. |
check_in_status | status | Monitor state. |
expected_interval_seconds | Check-in endpoint field | Missed-check-in detection. |
Span fields
| Field | Required? | How Logister uses it |
|---|---|---|
trace_id | Yes | Groups root and child spans into one trace. |
span_id | Yes | Unique span identifier within a project and trace. |
parent_span_id | No | Links child spans to a root or parent span. |
name | Yes | Span label in performance views. |
kind | No | Normalized to app, browser, cache, db, http, internal, queue, render, resource, or server. |
status | No | Status text for the span. |
duration_ms | Yes | Waterfall and request-load breakdown duration. |
started_at | Yes | Span start time. |
ended_at | No | Derived from start and duration when absent. |
Data collection boundaries
Prefer 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.
Be careful with raw SQL, full URLs with user data, request parameters, response bodies, headers, local variables, and frame locals. Avoid passwords, tokens, API keys, authorization headers, cookies, payment data, medical data, raw email bodies, and anything your team would not want stored in an observability database.
Insights metrics
These built-in series are available in project Insights.
| Metric key | Unit | What it means | Useful for |
|---|---|---|---|
events.total | count | All errors, logs, metrics, transactions, and check-ins in scope. | Overall ingestion volume and telemetry drops or spikes. |
errors.count | count | Error event count. | Incident detection, release regressions, and triage workload. |
activity.count | count | All non-error events. | Supporting telemetry volume without error noise. |
logs.count | count | Log event count. | Warning/debug volume and service activity changes. |
check_ins.count | count | Check-in event count. | Scheduler and worker heartbeat volume. |
transactions.count | count | Transaction event count. | Request or job throughput for instrumented paths. |
transactions.avg | ms | Average numeric transaction duration. | Baseline latency and broad performance regressions. |
transactions.p95 | ms | 95th percentile numeric transaction duration. | Tail latency and user-impacting slow paths. |
db.query.count | count | Metric events where message is exactly db.query. | Database query volume and suspected high-chatter pages. |
db.query.avg | ms | Average duration on db.query metric events. | Database latency trend and query-plan changes. |
db.query.p95 | ms | 95th percentile duration on db.query metric events. | Tail database latency and occasional heavy query detection. |
Insights supports 1h, 6h, 24h, and 7d windows. Bucket size is minute for 1h, hourly for 6h and 24h, and daily for 7d.
Custom metrics
Metric events become count and average-value series.
Custom metric events are regular event_type: "metric" events whose message is not the reserved db.query database timing metric.
| Series key | Unit | What it means | Useful for |
|---|---|---|---|
metric:<name> | count | Count of metric events with message equal to <name>. | Counters such as jobs processed, cache misses, webhooks received, or retries. |
metric_value:<name> | value | Average numeric context.value for metric events with message equal to <name>. | Gauges such as queue depth, payload size, memory usage, or external API latency. |
Keep metric names stable and include context.unit when you have one. Logister only offers an average-value series when context.value is numeric.
Performance segments
Spans and transactions explain where request time goes.
The Performance page prefers root trace spans when present. If no root spans are available, it falls back to transaction events and reads timing breakdowns from transaction context.
| Segment | Sources | Useful for |
|---|---|---|
| App | Root duration after known child time is subtracted; browser spans are treated as app time. | Controller, application, or client-side work not explained by a child segment. |
| Database | Child kind db, transaction DB runtime fields, and aliases database or sql. | Query load, slow SQL, N+1 behavior, and database saturation. |
| Render | Child kind render, view runtime fields, and aliases view or template. | Template and response rendering cost. |
| HTTP | Child kind http, dependency durations, and aliases external or client. | Downstream services, third-party APIs, and network-bound work. |
| Cache | Child kind cache. | Cache backend pressure and latency. |
| Queue | Child kind queue. | Background job enqueue/dequeue and broker timing. |
| Resources | Child kind resource. | Browser resource loads or resource-level work. |
| Other | Unknown timing breakdown keys or remaining measured duration. | Time that needs better instrumentation or does not fit another segment. |
Filter dimensions
Use low-cardinality context to make charts useful.
Insights can filter by environment, release, and selected custom scalar context attributes. Good custom dimensions are short, stable values such as tenant_id, plan, region, service, feature, or queue. Avoid high-cardinality or sensitive values such as raw email addresses, tokens, request bodies, and full URLs with user data.
Reserved operational fields such as duration_ms, trace_id, request_id, transaction_name, check_in_slug, exception payloads, stack traces, request/response bodies, and SQL/query text are intentionally excluded from the attribute filter picker.