feat(traces): implement search and aggregate subcommands

[jakedgy]

Summary

Replace the placeholder traces command with working search and aggregate subcommands using the typed datadogV2.SpansApi.

This is a draft — I'm using these subcommands in real investigation workflows to shape the interface before requesting review.

Closes #49

Motivation: Agent-Driven Trace Investigation

The primary use case is AI agents performing structured investigations. The apm command provides the bird's-eye view (services, operations, dependencies), but when an agent needs to drill into why a service is slow or erroring, it needs span-level data:

apm services stats  →  "web-server has elevated p99"
apm dependencies    →  "web-server → postgres is slow"
traces search       →  "show me the actual slow spans"
traces aggregate    →  "p99 duration by resource_name"

search and aggregate are the two operations that matter for this workflow. Everything else (SpansMetrics CRUD, etc.) is out of scope — it doesn't serve the investigation use case.

What's Here

• traces search — find individual spans with auto-pagination (SpansApi.ListSpans)
• traces aggregate — compute stats over spans (SpansApi.AggregateSpans), reuses parseComputeString from logs
• Follows existing patterns: --from/--to flexible time parsing, --query span syntax, formatter.FormatOutput
• Structure + execution tests with mock client

What's Still Being Explored

I have actual work that will exercise these commands, so I'm letting real usage inform what needs to change before this is review-ready:

• Output shaping — Do agents need different default fields or formatting for spans vs. logs?
• Pagination defaults — Is --limit 50 the right default, or do investigation flows need more/fewer spans?
• Aggregate UX — Does --compute / --group-by feel right in practice, or should it mirror the logs interface more closely?
• Error messages — Are the troubleshooting hints actually useful when things go wrong?

Testing

• Command structure tests (registration, flags, defaults)
• Search + aggregate execution with mock client
• All existing tests pass with go test -race ./...

---

🤖 Generated with Claude Code

[platinummonkey]

main has drifted @jakedgy some of those imports have changed

[platinummonkey]

Note: just refactored this project onto Rust so let me know and will happily port this change over

[jakedgy]

Note: just refactored this project onto Rust so let me know and will happily port this change over

All good -- startup life meant I didn't get to this as quickly as I wanted.

But I have been wanting to learn more Rust. I'll take care of it. Thanks for the heads up.

[jakedgy]

Update: Rust rewrite complete

Branch has been rebased onto main (Rust codebase) and the traces implementation rewritten from Go to Rust.

Usage verdict

After gathering usage data: good enough to ship. Not perfect, but functional and follows all existing codebase patterns.

Known limitation: agent context consumption

The biggest issue is that trace span data can fill up agent context quickly — individual spans contain a lot of nested attributes (tags, meta, metrics). This isn't traces-specific though; it's a general problem for any command that returns large payloads in agent mode.

Follow-up idea: We should think about an output format that is agent/context-friendly — e.g., a compact summary mode that returns key fields only, or a truncation strategy that caps nested attribute depth. This would benefit all commands, not just traces.

Changes in this push

• Full Go → Rust rewrite of traces.rs (search + aggregate)
• Updated main.rs with clap subcommand definitions and dispatch
• 18 unit tests passing
• All CI checks clean (clippy, fmt, build)
• Code reviewed against .claude/code-health/ guidance

[platinummonkey]

nice fwiw, useragent::is_agent_mode() || cfg.agent_mode can detect based on common environment variables or the --agent flag being sent. This would allow for more compact outputs under that circumstance