Ship error messages with telemetry failure events

[alexkroman]

Summary

Enhance telemetry to include error messages with failure events, enabling better error tracking and grouping in Datadog while maintaining privacy safeguards.

Changes

• Error message capture: Added optional error_message parameter to build_event() and _safe_dispatch() to carry the user-facing error message with failure telemetry events
• Message capping: Implemented _ERROR_MESSAGE_MAX_CHARS = 500 limit to bound payload size and prevent upstream message bodies from inflating the event
• Conditional inclusion: Error messages are only included when provided and non-empty, keeping the event structure clean for failures without messages
• Exception handling: Updated track() context manager to extract and pass error messages from:
  • CLIError.message for CLI errors
  • str(exc) for unexpected exceptions
  • Omitted for bare typer.Exit (no message available)
• Documentation: Updated docstrings to clarify that error messages (capped at 500 chars) now ride along with failure events for Error Tracking, while stack traces remain deliberately omitted
• Test coverage: Added three new tests validating:
  • Error messages are included in failure events
  • Messages are truncated at 500 characters
  • Empty error messages are omitted from the event
  • Updated existing tests to assert on the new error.message field

Implementation Details

The error message is stored in the reserved error.message field (alongside error.kind), which Datadog Error Tracking uses for issue grouping and display. The 500-character cap balances providing actionable context for debugging while preventing payload bloat if an upstream error embeds a full response body. Stack traces remain omitted to preserve the privacy-first design of the telemetry system.

https://claude.ai/code/session_0139pycafLLahbQiHsjP8kKX