Module telemetry 

Guide telemetry read-back (src/asdecided/mcp/telemetry.py) — ADR-040.

Read side only: decided mcp-stats (and the guide half of decided usage) summarizes the append-only JSONL log under $XDG_STATE_HOME/decisions/guide-telemetry.jsonl. The recorder itself lives in the MCP serving path and stays a documented no-op seam in the Rust sidecar (rust/decided-mcp/src/sidecar.rs).

Corruption posture is pinned: a missing log is an empty log; a garbled line (non-JSON, or JSON that is not an object) is skipped and COUNTED; a blank line is skipped silently. A log that is not valid UTF-8 makes the oracle crash (read_text raises UnicodeDecodeError, which its except OSError does not catch): traceback to stderr, empty stdout, exit 1 — mirrored here as LogNotUtf8.

Structs

LogNotUtf8

The oracle’s UnicodeDecodeError crash on a non-UTF-8 log: empty stdout, exit 1 (the reader catches only OSError).

TelemetrySummary

What the local log says about Guide usage (the mcp-stats payload).

ToolUsage

Aggregated usage for one tool, ordered by tool name in the summary.

Constants

SCHEMA_VERSION

SHARE_FIELD

SHARE_ISSUE_URL

SHARE_TEMPLATE

Functions

share_url

The prefilled usage-report issue URL. The local log path is DELETED from the shared report (counts and timestamps only); the JSON is json.dumps(..., ensure_ascii=False, indent=2) and the query is urllib.parse.urlencode (quote_plus per value).

summarize

Summarize the telemetry log; an empty or missing log is a valid answer.

summary_value

TelemetrySummary.to_dict() — pinned key order.

telemetry_path

The local telemetry log path under the XDG state directory.