aws / aws/bedrock-agentcore-sdk-python
feat: Observability Client — Delivery, Query & Trace Analysis
- Dominant language
- Python
- Stars
- 761
- Forks
- 147
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 7
Description
## 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`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/delivery.py#L30)
- [`enable_observability_for_resource()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/delivery.py#L101)
- [`enable_for_memory()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/delivery.py#L531)
- [`enable_for_gateway()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/delivery.py#L553)
- [`enable_traces_for_runtime()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/delivery.py#L241)
- [`disable_observability_for_resource()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/delivery.py#L426)
- [`get_observability_status()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/delivery.py#L493)
- [`ObservabilityClient`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/client.py#L14)
- [`query_spans_by_session()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/client.py#L44)
- [`query_spans_by_trace()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/client.py#L79)
- [`query_runtime_logs_by_traces()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/client.py#L114)
- [`TraceProcessor`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/trace_processor.py#L12)
- [`build_span_hierarchy()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/trace_processor.py#L32)
- [`CloudWatchQueryBuilder`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/query_builder.py#L4)
- [`CloudWatchResultBuilder`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/builders.py#L9)
Contributor guide
Assessment
This issue has not been assessed yet.