特工核心调查
- 作者仓库星标 9,113
- 作者仓库 mcp
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @awslabs · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
第 0 阶段:SessionId 到 TraceId 解析
当用户提供sessionId时,首先将其解析为traceId(s)。如果用户直接提供traceId,则跳过此阶段。
第 1 阶段:发现日志组
使用 `describe_log_groups` 和 logGroupNamePrefix `/aws/bedrock-agentcore/runtimes` 查找所有运行时日志组。
第 2 阶段:查询 CloudWatch Logs Insights
运行所有 6 种查询类型以进行完整的调查。每个查询都有一个结构化版本(用于专用`otel-rt-logs`)和一个全局样式解析版本(用于组合日志组)。
第 3 阶段:过滤 OTEL 噪声
请参阅 otel-span-schema.md 了解提取规则、已知范围和 DROP/KEEP 启发法。检索查询结果后: 对收到的总结果进行计数 删除与 DROP 模式匹配的条目(删除计数) 保留与 KEEP 模式匹配的条目
第四阶段:构建时间表
计算与最早跨度的 `startTimeUnixNano` 的相对偏移量:
# 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)
```
fields @timestamp, @message
| parse @message '"traceId":"*"' as traceId
| parse @message '"session.id":"*"' as sessionId
| filter sessionId = "SESSION_ID" or @message like "SESSION_ID"
| stats earliest(@timestamp) as firstSeen, latest(@timestamp) as lastSeen, count(*) as spanCount by traceId
| sort firstSeen asc
| limit 50
```
### Latest Interaction Only
```
fields traceId
| filter attributes.session.id = "SESSION_ID"
| sort @timestamp desc
| limit 1
```
Store discovered traceId(s) and use them in ALL subsequent queries.
## Phase 1: Discover Log Groups
Use `describe_log_groups` with logGroupNamePrefix `/aws/bedrock-agentcore/runtimes` to find all runtime log groups.
```
Log group naming patterns (in priority order):
- /aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>/otel-rt-logs (structured OTEL spans)
- /aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>/[runtime-logs] (stdout/stderr)
- /aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>-DEFAULT (single combined group)
```
### Log Group Layouts
AgentCore runtimes always emit OTEL spans. Some deployments split logs into a dedicated `otel-rt-logs` sub-group; others write everything into a single combined log group. Both are normal.
| Log Group Layout | Query Strategy |
|-----------------|----------------|
| Dedicated `otel-rt-logs` exists | Use structured field queries (`traceId`, `attributes.session.id`, etc.) |
| Single combined log group | Try structured fields first — if they return 0 results, use glob-style `parse @message` |
If a dedicated `otel-rt-logs` group exists, prefer it for structured queries.
### Parse Syntax Guidance
When using `parse @message` on combined log groups, prefer glob-style parse — it is simpler and avoids escaping issues:
```
| parse @message '"name":"*"' as spanName
| parse @message '"traceId":"*"' as traceId
| parse @message '"startTimeUnixNano":"*"' as startNano
```
Regex parse (`/pattern/`) is valid CloudWatch Logs Insights syntax but requires careful escaping of quotes and special characters inside JSON. If glob-style parse extracts the field you need, use it.
## Phase 2: Query CloudWatch Logs Insights
Run all 6 query types for a complete investigation. Each query has a structured version (for dedicated `otel-rt-logs`) and a glob-style parse version (for combined log groups).
### Query Size Limits
Every query MUST include `| limit` to prevent context window overflow:
- Session overview: `| limit 50`
- Span details: `| limit 100`
- Errors: `| limit 50`
- Tool invocations: `| limit 100`
- Token usage: `| limit 50`
- Latency outliers: `| limit 20`
### Query 1: Session Overview
**Structured:**
```
fields @timestamp, traceId, spanId, parentSpanId, name, scope.name,
attributes.session.id, attributes.gen_ai.operation.name, attributes.gen_ai.agent.name,
startTimeUnixNano, endTimeUnixNano
| filter traceId = "TRACE_ID"
| sort startTimeUnixNano asc
| limit 50
```
**Combined log group:**
```
fields @timestamp, @message
| filter @message like "TRACE_ID"
| parse @message '"name":"*"' as spanName
| parse @message '"traceId":"*"' as traceId
| parse @message '"spanId":"*"' as spanId
| parse @message '"startTimeUnixNano":"*"' as startNano
| parse @message '"endTimeUnixNano":"*"' as endNano
| sort @timestamp asc
| limit 50
```
### Query 2: Span Details with Duration
**Structured:**
```
fields @timestamp, traceId, spanId, parentSpanId, name, scope.name,
startTimeUnixNano, endTimeUnixNano,
(endTimeUnixNano - startTimeUnixNano) / 1000000 as durationMs,
status.code, attributes.gen_ai.operation.name
| filter traceId = "TRACE_ID"
| filter ispresent(startTimeUnixNano)
| sort startTimeUnixNano asc
| limit 100
```
**Combined log group:**
```
fields @timestamp, @message
| filter @message like "TRACE_ID"
| parse @message '"name":"*"' as spanName
| parse @message '"spanId":"*"' as spanId
| parse @message '"parentSpanId":"*"' as parentSpanId
| parse @message '"startTimeUnixNano":"*"' as startNano
| parse @message '"endTimeUnixNano":"*"' as endNano
| parse @message '"statusCode":"*"' as statusCode
| sort @timestamp asc
| limit 100
```
### Query 3: Errors
**Structured:**
```
fields @timestamp, traceId, spanId, name, status.code, status.message,
attributes.error.message, attributes.exception.message, attributes.exception.type
| filter traceId = "TRACE_ID"
| filter status.code = 2 OR ispresent(attributes.error.message) OR ispresent(attributes.exception.message)
| sort @timestamp asc
| limit 50
```
**Combined log group:**
```
fields @timestamp, @message
| filter @message like "TRACE_ID"
| filter @message like /ERROR|exception|Exception|fault|STATUS_CODE_ERROR/
| parse @message '"name":"*"' as spanName
| parse @message '"statusCode":"*"' as statusCode
| parse @message '"startTimeUnixNano":"*"' as startNano
| sort @timestamp asc
| limit 50
```
### Query 4: Tool Invocations
**Structured:**
```
fields @timestamp, traceId, spanId, name, scope.name,
attributes.gen_ai.operation.name, attributes.tool.name,
startTimeUnixNano, endTimeUnixNano,
(endTimeUnixNano - startTimeUnixNano) / 1000000 as durationMs
| filter traceId = "TRACE_ID"
| filter attributes.gen_ai.operation.name = "execute_tool" OR ispresent(attributes.tool.name) OR name like /tool/
| sort startTimeUnixNano asc
| limit 100
```
**Combined log group:**
```
fields @timestamp, @message
| filter @message like "TRACE_ID"
| filter @message like /tool|execute_tool|function_call/
| parse @message '"name":"*"' as spanName
| parse @message '"startTimeUnixNano":"*"' as startNano
| parse @message '"endTimeUnixNano":"*"' as endNano
| parse @message '"statusCode":"*"' as statusCode
| sort @timestamp asc
| limit 100
```
### Query 5: Token Usage
**Structured:**
```
fields @timestamp, traceId, spanId, name,
attributes.gen_ai.usage.input_tokens, attributes.gen_ai.usage.output_tokens,
attributes.gen_ai.usage.total_tokens, attributes.gen_ai.agent.name
| filter traceId = "TRACE_ID"
| filter ispresent(attributes.gen_ai.usage.total_tokens)
| sort @timestamp asc
| limit 50
```
**Combined log group:**
```
fields @timestamp, @message
| filter @message like "TRACE_ID"
| filter @message like /input_tokens|output_tokens|usage/
| parse @message '"name":"*"' as spanName
| parse @message '"gen_ai.usage.input_tokens"' as hasTokens
| sort @timestamp asc
| limit 50
```
### Query 6: Latency Outliers
**Structured:**
```
fields @timestamp, traceId, spanId, name,
(endTimeUnixNano - startTimeUnixNano) / 1000000 as durationMs
| filter traceId = "TRACE_ID"
| filter ispresent(endTimeUnixNano)
| sort durationMs desc
| limit 20
```
**Combined log group:**
```
fields @timestamp, @message
| filter @message like "TRACE_ID"
| parse @message '"name":"*"' as spanName
| parse @message '"startTimeUnixNano":"*"' as startNano
| parse @message '"endTimeUnixNano":"*"' as endNano
| sort @timestamp asc
| limit 50
```
Queries are async — use `get_logs_insight_query_results` to poll until status is `Complete`.
## Phase 3: Filter OTEL Noise
See [otel-span-schema.md](references/otel-span-schema.md) for extraction rules, known scopes, and DROP/KEEP heuristics.
After retrieving query results:
1. Count total results received
2. Remove entries matching DROP patterns (count removed)
3. Keep entries matching KEEP patterns
4. Log: "Filtered: {total} → {kept} spans ({removed} noise entries dropped)"
## Phase 4: Build Timeline
Compute relative offsets from the earliest span's `startTimeUnixNano`:
```
[T+0ms] Session started — traceId: abc123
[T+45ms] LLM inference — model: anthropic.claude-v3 — 1,200ms
[T+1,250ms] Tool call: search_documents — 340ms
[T+1,600ms] Tool result: 3 documents found
[T+1,650ms] LLM inference — model: anthropic.claude-v3 — 890ms
[T+2,550ms] Response generated — 200 OK
[T+2,600ms] Session ended — total: 2,600ms
```
## Error Handling
| Situation | Action |
|-----------|--------|
| No log groups found | Ask user for log group name or AWS region |
| Query returns 0 results | Widen time range to ±24h, retry. If still empty, try alternate ID fields |
| Session ID not found | Try filtering by requestId, invocationId, traceId variants |
| Query timeout | Use `cancel_logs_insight_query`, reduce time range, retry |
| Partial results | Note in output, suggest narrower time window |
| Structured field queries return 0 results | Switch to glob-style `parse @message` queries (see Parse Syntax Guidance) |
章节与文件索引
按说明文件中的顺序排列。
参考文件
MCP:
[otel-span-schema.md](参考文献/otel-span-schema.md)
第 0 阶段:SessionId 到 TraceId 解析
仅限最新互动
文件/命令 -> describe_log_groups · /aws/bedrock-agentcore/runtimes · otel-rt-logs · traceId · attributes.session.id · parse @message · /pattern/ · | limit
内容校验值 -> aca98be9da74
当前原文的自动摘译,尚未人工审校。
参考文件
根据需要加载这些文件以获得详细指导:
MCP:
mcp-setup.md 何时:开始调查之前始终加载 — 确保 CloudWatch 和 Application Signals MCP 服务器已配置 包含:CloudWatch Logs 和应用程序信号的 MCP 服务器配置,以及 Claude Code、Gemini、Codex 和 Kiro CLI 的设置说明 .mcp.json 何时:首次设置 MCP 服务器时加载
otel-span-schema.md
何时:始终在查询或过滤 OTEL 跨度之前加载包含:字段提取优先级、已知检测范围、噪声过滤启发式(DROP/KEEP 模式)
仅限最新互动
存储发现的traceId并在所有后续查询中使用它们。