feat(telemetry): full Sentry observability + per-command usage tags

[lukeocodes]

Summary

Stacked on #74 (fix/telemetry-session-mode). Three commits, one logical change: take the CLI's Sentry telemetry from "errors-only" to a full observability + product-analytics surface.

What changed

1. SDK init kwargs — turn the dials on (packages/deepctl-telemetry/.../client.py)

Init kwarg	Before	After
traces_sample_rate	0.0	1.0
profiles_sample_rate	0.0	1.0
enable_logs	(default False)	True
attach_stacktrace	(default False)	True
max_breadcrumbs	20	100
send_default_pii	False	False (unchanged)
before_send=_scrub_event	yes	yes (unchanged)

2. Transaction wrap (src/deepctl/main.py)

cli() is now invoked inside a sentry_sdk.start_transaction(op="cli.command"). Initial name is a fixed "cli" placeholder — BaseCommand.execute renames it once Click has dispatched. (Previous heuristic in _safe_command_name produced json for dg --output json whoami because flag values look like command names. Dropped.)

3. Per-command usage tags (packages/deepctl-core/.../base_command.py)

BaseCommand.execute now wraps handle() with two telemetry hooks:

• _tag_telemetry_start(ctx) — runs before handle. Renames the active transaction to ctx.command_path (so dg debug audio becomes deepctl debug audio instead of just debug), and tags the scope with:
  • cmd.flags — sorted comma-separated list of flag names the user passed (e.g. diarize,model,output). Never values. Sentinel (none) when no flags were used.
  • cmd.output_format — one of json | yaml | table | csv | default.
• _tag_telemetry_status(status) — runs after handle. Tags cmd.status with ok, cancelled, error, or whatever the BaseResult.status enum returned.

Both methods are wrapped in bare except Exception: pass so a Sentry hiccup, missing scope, or unknown Click parameter-source enum value can never crash the user's command.

What you'll see in Sentry per dg invocation

Per dg listen URL --diarize --model nova-3 -o json:

transaction:
  op:    cli.command
  name:  deepctl listen           ← from ctx.command_path
  tags:
    cli.os:          darwin
    cli.arch:        arm64
    cli.python:      3.13
    cli.version:     0.2.23
    cmd.flags:       diarize,model,output
    cmd.output_format: json
    cmd.status:      ok

Plus a session envelope (release health), profile envelope (when sampled long enough), and any log envelopes for logging.warning+ records.

Privacy

• Flag names only, never values. --model nova-3 becomes cmd.flags: model, not cmd.flags: model=nova-3.
• cmd.output_format is a bounded enum.
• cmd.status is a bounded enum.
• transaction.name is ctx.command_path — the dispatch tree, not user input.
• send_default_pii=False and before_send=_scrub_event continue to scrub request bodies, headers, cookies, and user identifiers from error events.

Proof

$ SENTRY_DEBUG=1 dg --output json whoami 2>&1 | grep -iE '(transaction <|envelope)'
[sentry] DEBUG: [Tracing] Starting <cli.command> transaction <cli>
[sentry] DEBUG: Sending envelope [envelope with 1 items (transaction)] project:4510993603362816 host:o206115.ingest.us.sentry.io
[sentry] DEBUG: Sending envelope [envelope with 1 items (internal)]    project:4510993603362816 host:o206115.ingest.us.sentry.io
[sentry] DEBUG: Sending envelope [envelope with 1 items (session)]     project:4510993603362816 host:o206115.ingest.us.sentry.io

<cli> is the placeholder — the transaction is renamed to deepctl whoami by _tag_telemetry_start once Click dispatches. Sentry serialises the final state on send, so the actual envelope arrives with the resolved name.

Tests

File	Class	Cases
packages/deepctl-telemetry/tests/unit/test_telemetry.py	TestSessionFlush::test_init_enables_full_observability_stack (renamed)	asserts every new kwarg landed + session_mode not in kwargs regression guard
packages/deepctl-core/tests/unit/test_base.py	TestTelemetryTagging (new)	10 cases — transaction rename, flag-name extraction (only COMMANDLINE-sourced params), (none) sentinel for zero flags, output format default, parametrised status pass-through, exception suppression on both methods

21 passed (telemetry: 11, base_command: 10)