Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Observability Specification

Version: 1.0.0 Status: Draft

Purpose

This specification defines observability conventions for ClearHead tooling. It covers semantic events, structured logging, and debugging telemetry.

Observability is for:

  • Debugging system behavior (“why is this action in this state?”)
  • Property change history (“when did priority change from 2 to 1?”)
  • Operational analytics (completion velocity, patterns over time)
  • Distributed tracing (sync operations, cross-device coordination)

Observability is NOT for:

  • Current state (that’s the domain data)
  • Habit occurrences (authoritative Actions in .actions and .completed.actions; definitions in .habits.actions)
  • Sync coordination (that’s git)

Relationship to Other Concerns

Git                       → Sync, version history, conflict resolution
Domain Model              → Current semantic state (charters, actions, plans)
DSL Files (.actions, .md) → Human-readable projections, queryable
Observability (this)      → Debugging, analytics, audit trail

These are complementary. Git tracks file-level history. Observability tracks semantic history (what those file changes meant in domain terms).

Framework

ClearHead uses OpenTelemetry for observability:

  • Standard format — Wide ecosystem support (Jaeger, Prometheus, Grafana)
  • Structured logs — Semantic events with typed fields
  • Offline-first — Local file export, aggregate later

Storage Location

Telemetry is stored in XDG state directory (machine-specific, not synced):

  • Linux/macOS: ~/.local/state/clearhead/telemetry/ (or $XDG_STATE_HOME/clearhead/telemetry/)
  • Windows: %LOCALAPPDATA%\clearhead\state\telemetry\

File Format

Logs are stored as newline-delimited JSON (NDJSON) for easy parsing with DuckDB, jq, or standard tools:

telemetry/
├── events-2026-01.ndjson
├── events-2026-02.ndjson
└── ...

Files rotate monthly by default. Configurable via settings.

Semantic Events

Events are domain-specific and use consistent field naming.

Common Fields

All events include:

FieldTypeDescription
timestampISO 8601When the event occurred
eventstringEvent type identifier
toolstringEmitting tool (cli, lsp, sync)
action_uuidstringRelated action UUID (if applicable)

Action Lifecycle Events

EventWhen EmittedAdditional Fields
action_createdNew plan addedname, file_path
action_completedState → completedname, completed_at
action_cancelledState → cancelledname, reason (optional)
action_startedState → in_progressname
action_blockedState → blockedname, reason (optional)
action_restartedState → newname, reason (optional)
action_archivedAction moved to archivename, archive_file
action_deletedAction removed from filename

Property Change Events

EventWhen EmittedAdditional Fields
priority_changedPriority modifiedold_priority, new_priority
due_date_changedDo date modifiedold_date, new_date
name_changedName modifiedold_name, new_name
context_addedContext tag addedcontext
context_removedContext tag removedcontext

Habit Events

EventWhen EmittedAdditional Fields
instance_generatedArrived slot durably stampedhabit_uuid, slot, action_uuid
instance_completedOccurrence completedhabit_uuid, slot, action_uuid, completed_date
instance_skippedUser cancels an occurrence or an explicit exclusion skips an unstamped slothabit_uuid, slot, reason
habit_editedNative Habit modifiedhabit_uuid, fields_changed
habit_completedWhole Habit completedhabit_uuid
converted_to_habitKind-change proposal acceptedhabit_uuid, converted_from (same native UUID)
habit_catchup_pendingBounded generation has remaining arrived slotshabit_uuid, resume_after
calendar_link_heldReplacement relationship awaits explicit confirmationuid, reason

A missed slot is not a skip. Retry/no-op stamping emits no second generation event. Native Habit identity and canonical slot survive transport UID changes. Instance history belongs to Actions and archives, not telemetry.

Sync Events

Sync events are deferred to the future sync server implementation. Git is the current sync mechanism; file-level history is available via git log. These event types are reserved for when a distributed sync server is introduced.

Semantic Patch / Projection Events

These events trace how a named semantic operation becomes a domain model change and how that change is projected to files. They are especially useful for debugging why a file ended up in a particular state.

EventWhen EmittedAdditional Fields
patch_derivedA semantic change set is produced by a named operation with resolved targetsoperation, patch_id, operation_count
patch_appliedA semantic change set is applied to the domain modelpatch_id, applied_count, skipped_count, reason (optional)
projection_writtenA projected DSL file is written from domain model statefile_path, bytes_written, reason (e.g., on_save, manual_apply)

Correlation: Implementations SHOULD correlate patch_* events using tracing identifiers (e.g., OpenTelemetry trace/span IDs) so operators can answer: “what operation was requested, what change set was derived, what was applied, what was projected”.

System Events

EventWhen EmittedAdditional Fields
workspace_openedWorkspace loadedpath, action_count
file_parsedActions file parsedfile_path, action_count, parse_time_ms
lsp_startedLSP server startedport (if applicable)

Retention

Default retention: 1 year. Older files can be:

  • Deleted automatically (if configured)
  • Archived to cold storage
  • Aggregated into summary statistics

Telemetry settings can be aggregated via a sync server but that is not required and up to implementors and configuration

See Also