Local telemetry

Understand local telemetry

Marivo writes OpenTelemetry-shaped JSONL events to UTC-dated files in the project state directory:

.marivo/telemetry/events-2026-07-29.000.jsonl

The final three digits are a size segment. Marivo starts a new segment when the current file would grow beyond 128 MiB. The limit is approximate when multiple processes append concurrently.

Marivo retains 14 UTC calendar days of managed event files. On the first write of each UTC day, it also removes the oldest historical segments until historical telemetry is at most 1 GiB. Files for the current UTC day are never removed by that cleanup. A legacy .marivo/telemetry/events.jsonl file from an earlier Marivo version is left untouched; archive or remove it explicitly after deciding whether its events are still needed.

Telemetry schema v2 covers explicit public CLI, datasource, semantic, and analysis operations. Each operation writes a correlated pair:

• marivo.operation.started
• marivo.operation.completed

The pair shares an operation ID. Nested public calls include a parent operation ID, and completed events include status, total duration, stable structured error and repair fields, or a bounded result summary. Expensive operations may also include validation, execution, persistence, and evidence phase durations. The marivo.operation.origin attribute distinguishes top-level explicit calls from delegated calls and declarations executed during internal_load. Successful internal declarations are omitted when an existing analysis session reloads its semantic catalog; the enclosing semantic load operation and any failed declaration remain recorded.

Session-bound events can include the persisted session.question. Analysis operations include analysis_purpose when supplied, and md.raw_sql(...) includes its required reason. Session creation records whether the requested question was applied or ignored because an existing session was resumed.

Input summaries can include canonical metric, dimension, datasource, semantic, and artifact identifiers together with counts, types, options, limits, and fingerprints. String collections that are not defined identifier collections, including guardrails and datasource client tags, include only count and item types. Explicit artifact reads such as show(), contract(), and to_pandas() include the receiver artifact/ref and producing job so consumers can connect a result to its later use. Result summaries can include artifact and job identifiers, content hash, result kind and status, row and issue counts, cache state, truncation, and evidence status. Marivo never writes credentials, resolved secrets, datasource hosts, DSNs, SQL text, filesystem paths, slice values, frame row values, free-text collection items, arbitrary object representations, or exception messages to telemetry.

The legacy events.jsonl file can contain schema v1 lines after an upgrade. Marivo does not migrate that file. Consumers reading retained history should scan the dated events-*.jsonl files and, when needed, read the legacy file separately. They should select records whose marivo.event.schema_version attribute is 2.

These events stay local. Marivo does not upload them. The raw session question, analysis purpose, and raw-SQL reason are stored in the local event file; review that file before sharing project state outside your environment.

Disable local telemetry for one process:

MARIVO_TELEMETRY=off marivo init

Set a project default in marivo.toml:

[telemetry]
enabled = "off" # "on" or "off"

MARIVO_TELEMETRY=on|off overrides [telemetry].enabled for the current process. If neither is set, local telemetry defaults to "on".