feat: Observability Client — Delivery, Query & Trace Analysis

[Hweinstock]

Problem

The SDK has no observability surface area. On the delivery side, memory and gateway resources require manual CloudWatch vended log delivery setup — customers must call PutDeliverySource, PutDeliveryDestination, and CreateDelivery with the correct naming conventions, ARN formats, and source types. On the query side, the SDK's CloudWatchSpanHelper is internal to the evaluation module and not exposed as public API — customers who programmatically query traces for debugging, monitoring, or custom dashboards have no SDK path. The starter toolkit provides both: an ObservabilityDeliveryManager for enabling/disabling logs and traces per resource, and an ObservabilityClient with a full query→parse→analyze pipeline for spans and traces.

Acceptance Criteria

• Customers can enable CloudWatch logs and traces for memory and gateway resources with a single method call
• Customers can enable traces for runtime resources
• Customers can disable observability and optionally clean up log groups
• Customers can check observability status (whether delivery sources exist) for a resource
• Customers can query spans by session ID or trace ID from CloudWatch Logs Insights
• Customers can query runtime logs by trace ID(s) from agent-specific log groups
• Customers can find the most recent session ID for an agent
• Query results are parsed into typed Span and RuntimeLog objects
• Customers can reconstruct trace trees (parent-child span hierarchy) from query results
• Customers can compute trace duration, count error spans, and filter to error-only traces
• All functionality is verified via integration tests running in CI

Relevant Links

• ObservabilityDeliveryManager
• enable_observability_for_resource()
• enable_for_memory()
• enable_for_gateway()
• enable_traces_for_runtime()
• disable_observability_for_resource()
• get_observability_status()
• ObservabilityClient
• query_spans_by_session()
• query_spans_by_trace()
• query_runtime_logs_by_traces()
• TraceProcessor
• build_span_hierarchy()
• CloudWatchQueryBuilder
• CloudWatchResultBuilder