agentcore-observability-setup
Validates and bootstraps Amazon Bedrock AgentCore observability so customers can trace
vggargav · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add aws/tools-for-devops-agent --skill agentcore-observability-setup技能说明
name: agentcore-observability-setup description: Validates and bootstraps Amazon Bedrock AgentCore observability so customers can trace agent reasoning, detect silent failures, and measure performance before an outage. Use this skill when a user asks to check, validate, audit, verify, fix, or set up AgentCore observability, tracing, metrics, or logging - for example "is AgentCore observability configured correctly", "why can't I see traces for my agent", "my Bedrock agent has no spans in CloudWatch", "validate agent monitoring", "AgentCore observability readiness", or "set up OTEL for my agent". Covers AgentCore Runtime agents, Memory and Gateway resources, built-in tools, and agents hosted outside the runtime (Lambda, ECS, EKS, on-prem, multi-cloud). Verifies what is reachable via read-only CloudWatch, X-Ray, and AgentCore control-plane APIs, and prescribes exact remediation for gaps it cannot directly read such as code-level OTEL instrumentation. metadata: author: vggargav version: "1.0.0" aws-devops-agent-skills.agent-types: "Chat tasks, Evaluation" aws-devops-agent-skills.aws-services: "Amazon Bedrock AgentCore, Amazon CloudWatch, AWS X-Ray" aws-devops-agent-skills.technical-domains: "AI/ML, Observability"
AgentCore Observability Setup & Validation
Validate and bootstrap observability for Amazon Bedrock AgentCore workloads, aligned with the AgentCore observability documentation. Produce a readiness report that states, per check, what is configured vs. what should be, and generate the exact remediation for every gap.
Operating Principle
Verify where reachable; prescribe everywhere else. Every check is exactly one of:
- VERIFY — confirmable through a read-only API (log group exists, data arriving, spans flowing, Transaction Search enabled, tracing toggle, delivery configured).
- PRESCRIBE — cannot be read directly (code-level OTEL instrumentation in the agent's source). Validate the effect (are spans arriving?) and emit the exact steps. Do not claim to read source code.
This skill is read-only. It validates and generates configuration/commands. The customer decides whether to apply them. Never mutate IAM, resources, or configuration.
When to Use
Activate when the user asks to:
- Check / validate / audit whether AgentCore observability is configured correctly
- Diagnose missing traces, spans, metrics, or logs for a Bedrock agent
- Set up or bootstrap observability (tracing, metrics, logging) for an agent
- Run an AgentCore observability readiness review
- Understand why agent telemetry isn't appearing in CloudWatch GenAI Observability
Step 1: Detect Permission Tier
This skill degrades gracefully based on which read-only permissions the DevOps Agent role holds. Detect the tier by attempting calls and noting failures; run the checks the tier allows and report what to add to unlock the rest. Never attempt to modify IAM.
| Tier | Permissions | Unlocks |
|---|---|---|
| 1 — Standard (default DA IAM) | logs:DescribeLogGroups, logs:FilterLogEvents, logs:GetLogEvents, logs:StartQuery, logs:GetQueryResults, cloudwatch:GetMetricData, cloudwatch:ListMetrics, cloudwatch:DescribeAlarms | Telemetry-arrival verification for any host |
| 2 — Runtime config | bedrock-agentcore:GetAgentRuntime, bedrock-agentcore:ListAgentRuntimes, xray:GetTraceSegmentDestination, logs:DescribeDeliveries, logs:DescribeDeliverySources, logs:DescribeDeliveryDestinations, logs:DescribeResourcePolicies | Runtime tracing/env, Transaction Search state, Memory/Gateway delivery, X-Ray resource policy |
| 3 — Non-runtime host | lambda:GetFunctionConfiguration; ecs:DescribeTaskDefinition, ecs:DescribeServices, ecs:ListTasks; eks:DescribeCluster | Host-side config verification for Lambda / ECS / EKS |
If Tier 2/3 permissions are absent, tell the user the check is prescriptive-only here and give the
exact scoped inline policy to attach to the DevOps Agent role (see references/iam-tiers.md) so a
re-run can verify it. The shared managed policy is cross-tenant and must not be modified per-skill.
Step 2: Determine Scope (Host & Surface)
Host detection:
- Runtime — auto-detect with
bedrock-agentcore:GetAgentRuntime/bedrock-agentcore:ListAgentRuntimes(Tier 2). If absent, ask the user. - Non-runtime — the agent cannot reliably auto-detect the host. Ask: "Is the agent on Lambda, ECS, EKS, or on-prem/another cloud?"
Surfaces to assess (ask which apply, or discover via Tier 2 List*):
Runtime agents · Memory resources · Gateway resources · Built-in tools (code interpreter, browser) · non-runtime host.
Outcome matrix:
| Host / Surface | Expected outcome |
|---|---|
| Runtime agent | Verify (Tier 1+2) + Prescribe |
| Memory resource | Verify delivery + tracing (Tier 2) + Prescribe |
| Gateway resource | Verify delivery + tracing (Tier 2) + Prescribe |
| Built-in tools | Prescribe; verify telemetry-arrival where present |
| Lambda | Verify host config (Tier 3) + Prescribe |
| ECS | Verify host config (Tier 3) + Prescribe |
| EKS | Verify telemetry arrival (Tier 1) + Prescribe config (pod env is K8s-RBAC-gated, not IAM-verifiable) |
| On-prem / multi-cloud | Prescribe only |
Step 3: Run Checks
Assign each finding a severity (CRITICAL / HIGH / MEDIUM / LOW / INFO) and a type (VERIFY / PRESCRIBE).
The complete check catalog with APIs, log-group patterns, and pass/fail logic is in
references/checks-catalog.md. Summary below.
3.1 Account prerequisite — CloudWatch Transaction Search (all hosts)
- VERIFY (Tier 2):
xray:GetTraceSegmentDestination→ destination must beCloudWatchLogsand statusACTIVE. IfXRay/inactive, Transaction Search is not enabled → CRITICAL (spans will not be delivered to CloudWatch Logs; this is the single most common s