# AgentCore Investigation

Traces AgentCore sessions and tool calls in CloudWatch logs to debug latency.

- Repository: https://github.com/awslabs/mcp (9860 stars)
- Category: DevOps
- License: Apache-2.0
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add awslabs/mcp --skill agentcore-investigation -g -a claude-code -y`
Codex: `npx skills add awslabs/mcp --skill agentcore-investigation -g -a codex -y`
Cursor: `npx skills add awslabs/mcp --skill agentcore-investigation -g -a cursor -y`
Gemini CLI: `npx skills add awslabs/mcp --skill agentcore-investigation -g -a gemini-cli -y`

## Description

Investigate Bedrock AgentCore runtime sessions via CloudWatch Logs Insights, resolve session/trace IDs, query OTEL spans, filter noise, build timelines. Use when debugging AgentCore agent sessions, tracing tool calls, or analyzing latency.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# AgentCore Runtime Session Investigation

Investigate AgentCore runtime sessions by querying CloudWatch Logs Insights, filtering OpenTelemetry noise, and producing structured investigation output.

**Key capabilities:**
- Session-to-trace resolution via OTEL span correlation
- Structured and glob-style parse queries for both dedicated and combined log groups
- OpenTelemetry noise filtering with AgentCore-specific heuristics
- Timeline construction with T+offset format
- Error, tool invocation, token usage, and latency analysis

---

## Reference Files

Load these files as needed for detailed guidance:

### MCP:
#### [mcp-setup.md](mcp/mcp-setup.md)
**When:** ALWAYS load before starting an investigation, ensures CloudWatch and Application Signals MCP servers are configured
**Contains:** MCP server configuration for CloudWatch Logs and Application Signals, with setup instructions for Claude Code, Gemini, Codex, and Kiro CLI

#### [.mcp.json](mcp/.mcp.json)
**When:** Load when setting up MCP servers for the first time
**Contains:** Sample MCP configuration with both CloudWatch and Application Signals servers

### [otel-span-schema.md](references/otel-span-schema.md)
**When:** ALWAYS load before querying or filtering OTEL spans
**Contains:** Field extraction priorities, known instrumentation scopes, noise filtering heuristics (DROP/KEEP patterns)

---

## Phase 0: SessionId-to-TraceId Resolution

When the user provides a sessionId, resolve it to traceId(s) first. If user provides traceId directly, skip this phase.

### Discovery Query (structured fields)

```
fields traceId, @timestamp
| filter attributes.session.id = "SESSION_ID"
| stats count(*) as spanCount, min(@timestamp) as firstSeen, max(@timestamp) as lastSeen by traceId
| sort firstSeen asc
```

### Discovery Query (combined log group, glob-style parse)

The rest: https://github.com/awslabs/mcp/blob/HEAD/src/cloudwatch-mcp-server/skills/agentcore-investigation/SKILL.md