Skip to content
Agent Archaeology

Telltale

Telemetry Output

Telltale emits compact JSONL events for local review, forwarding, dashboards, and alerting. The default scan path writes one canonical JSON object per line to a local file; optional delivery paths can wrap the same event body for a specific sink without changing the event schema.

Default JSONL sink

By default, telltale scan uses the user path profile, appends telemetry to an OS-standard per-user JSONL path, and keeps the active file bounded with built-in size-based rotation: ~/.local/state/telltale/logs/adr-events.jsonl on Linux (or $XDG_STATE_HOME when set), ~/Library/Logs/Telltale/adr-events.jsonl on macOS, and %LOCALAPPDATA%\Telltale\Logs\adr-events.jsonl on Windows.

Write events locally
SH
cargo run --bin telltale -- scan --once --emit-activity

Use --path-profile system for managed deployments, --path-profile project for repo-relative development paths, or an explicit --log-path to override any profile default. ADR_LOG_PATH and ADR_STATE_PATH are also honored. Use --log-rotate-disabled when an external rotation policy owns the file, and use --dry-run when validating fixtures or command behavior without writing events.

Event families

Common event types include:

  • activity: redacted per-session activity summaries.
  • detection: rule matches, risk scores, categories, and response guidance.
  • session_risk_summary: optional per-session rollups from already-redacted activity and detection events.
  • scanner_health: source-discovery and scanner health status.
  • scanner_error: parser or scan errors that should be visible to operators.
  • correlation: cross-session patterns built from emitted telemetry.

Optional activity and session summaries

Enable optional activity and session summary events when dashboards need more than detection-only output:

Enable activity and session summaries
SH
cargo run --bin telltale -- scan --once --emit-activity --emit-session-risk-summary

Session risk summaries provide one compact row per agent session for dashboards.

Privacy boundary

Telemetry should be useful without becoming a transcript dump. Telltale emits redacted excerpts, evidence hashes, rule IDs, risk scores, source metadata, and bounded context by default. It should not emit raw secrets, full auth files, raw private keys, complete .env values, or full session bodies.

Forwarding to SIEMs

Forward the JSONL file with the shipper or collector your environment already uses. A safe starter pattern:

  • Write events locally with the default user path profile, ADR_LOG_PATH, or an explicit --log-path.
  • Validate the event shape against the schema.
  • Configure the shipper to read only the JSONL event path.
  • Keep human-readable diagnostics, scanner state, credentials, and raw agent session stores outside the forwarded telemetry path.
  • For managed deployments, either keep Telltale built-in rotation enabled or disable it with --log-rotate-disabled and use OS-native rotation (logrotate, newsyslog, or a Windows scheduled task); keep the active shipper target filename stable.

Optional export and sink paths

The canonical event payload remains the same across delivery paths:

Export existing JSONL
SH
telltale export --format jsonl

Reads existing JSONL telemetry.

Export for Elasticsearch
SH
telltale export --format elastic-bulk

Writes Elasticsearch Bulk API pairs.

Splunk HEC
SH
telltale scan --splunk-hec-endpoint ... --splunk-hec-token ...

Posts events through a Splunk HEC envelope when a deployment explicitly opts in.