はじめに
Amazon Bedrock AgentCore Runtime上でAIエージェントを動かす場合、実際にどのように処理が実行されているのかを確認するために、Observabilityは重要です。
特に生成AIアプリケーションでは、
- エージェントのセッション数
- トレース
- LLMの呼び出し
- 入出力トークン
- 実行時間
- ログ
などを確認できると、開発時のデバッグだけでなく、運用時の監視にも役立ちます。
今回は、Node.js + Strands Agentsで作成したAIエージェントをAmazon Bedrock AgentCore Runtime上で動かし、AWS Distro for OpenTelemetry（ADOT）の自動計装を利用して各種データを取得してみました。
結論からいうと、アプリケーション側にOpenTelemetry用のコードを追加することなく、AgentCore RuntimeのトレースやメトリクスをCloudWatchから確認できました。
ただし、いくつかハマったポイントもありました。
特に重要だったのが、以下2点です。
- アプリケーションのエントリーポイントを
opentelemetry-instrument 経由で起動すること
UNIFIED_TRACES_DESTINATION_ENABLED=true を設定すること
この記事では、実際に設定した内容と、CloudWatch上でどのように確認できたのかを紹介します。
今回の構成
今回作成したのは、Node.jsで実装したStrands Agentsのエージェントです。
大まかな構成は次のようになります。
┌─────────────────────────┐
│ Amazon Bedrock │
│ AgentCore Runtime │
│ │
│ Node.js │
│ Strands Agents │
└───────────┬─────────────┘
│
OpenTelemetry
│
▼
┌─────────────────────────┐
│ CloudWatch │
│ │
│ Logs / Spans / Metrics │
│ │
│ GenAI Observability │
└─────────────────────────┘
アプリケーション自体はstrands-agentsを利用しています。
Observabilityについては、AWS Distro for OpenTelemetryのNode.js自動計装を利用しました。
今回利用したパッケージは以下です。
{
"dependencies": {
"@aws/aws-distro-opentelemetry-node-autoinstrumentation": "^0.13.0"
}
}
OpenTelemetryの自動計装を利用する
今回のポイントの一つが、OpenTelemetryのコードをアプリケーションに直接追加しなかったことです。@aws/aws-distro-opentelemetry-node-autoinstrumentationを利用して自動計装を行なったため、AgentCore Runtimeの設定にてエージェント エントリーポイントを以下のように設定しました。
opentelemetry-instrument, dist/app.js
最初にopentelemetry-instrumentを指定するのがポイントです。
ここは非常にシンプルでした。
AgentCore Runtimeの環境変数
AgentCore Runtimeに、Observabilityに関連する環境変数を設定します。今回設定したものとしてUNIFIED_TRACES_DESTINATION_ENABLED=trueの設定が必要でした。
最初、この環境変数を設定していない状態でもRuntime自体は正常に動作していました。しかし、期待していたトレース情報がCloudWatch Logsのspansログストリームに出力されませんでした。
そこで、UNIFIED_TRACES_DESTINATION_ENABLED=trueを設定してRuntimeを実行したところ、spansへの出力を確認できました。
CloudWatch Transaction Searchを有効化する
AgentCore RuntimeのObservabilityを確認するためには、CloudWatch側の設定も必要です。今回、CloudWatch Transaction Searchを有効化しました。設定方法は以下を確認してください。
docs.aws.amazon.com
IAMロール
IAMロールは以下のものを設定しています。logsやxrayあたりがポイントかと思います。
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::バケット名",
"arn:aws:s3:::バケット名/*"
]
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:DescribeLogStreams",
"logs:DescribeLogGroups",
"logs:PutResourcePolicy"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"bedrock:InvokeModel",
"bedrock:InvokeModelWithResponseStream"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"bedrock-agentcore:GetWorkloadAccessToken",
"bedrock-agentcore:GetWorkloadAccessTokenForJWT",
"bedrock-agentcore:GetWorkloadAccessTokenForUserId"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"xray:PutTraceSegments",
"xray:PutTelemetryRecords",
"xray:GetSamplingRules",
"xray:GetSamplingTargets"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "cloudwatch:PutMetricData",
"Resource": "*",
"Condition": {
"StringEquals": {
"cloudwatch:namespace": "bedrock-agentcore"
}
}
}
]
}
実際にRuntimeを呼び出してみる
設定が完了したら、実際にAgentCore Runtimeを呼び出します。すると、CloudWatch Logsには比較的すぐにログが出力されました。また、AgentCore Runtimeのロググループにはspansというログストリームがつくられ、こちらにもトレース情報が出力されることを確認できました。
otel-rt-logsは少し遅れて出力された
一方で、少し注意が必要だったのがotel-rt-logsです。Runtimeを呼び出した直後には、otel-rt-logsの出力を確認できませんでした。しばらく待ってから確認したところ、Runtimeの呼び出しから5分程度経過した後に出力されることを確認しました。そのため、最初にObservabilityを試したときには、「設定が間違っていてotel-rt-logsが出てこないのでは？」と少し迷いました。しかし、実際には時間を置くことで出力されました。
CloudWatchの生成AIオブザーバビリティ
さらに面白かったのが、CloudWatchの生成AI向けObservability画面です。
CloudWatchには生成AIアプリケーション向けのObservability機能があり、その中にBedrock AgentCoreの項目があります。ここからAgentCore Runtimeの実行状況を確認できます。
画面上では、例えば、
- セッション数
- トレース
- トークン使用量
- 生成AIに関する各種メトリクス
などが整理されて表示されます。
OpenTelemetryのログを一つ一つ確認するよりも、こちらの画面を見ることでAgentCore上のエージェントがどのように実行されているのかを把握しやすくなっています。
特に生成AIアプリケーションでは、単純なCPU使用率やメモリ使用量だけではなく、
何回セッションが実行されたか
↓
どのようなトレースになっているか
↓
LLMをどれくらい呼び出したか
↓
どれくらいトークンを消費したか
といった情報が重要になるため、こうした情報をまとめて確認できるのは便利だと感じました。
今回ハマったポイント
今回の検証で特に注意したポイントをまとめます。
1. opentelemetry-instrumentを付けて起動する
単純に、
dist/app.js
と起動するのではなく、
opentelemetry-instrument dist/app.js
とします。
2. UNIFIED_TRACES_DESTINATION_ENABLEDを設定する
今回の検証では、
UNIFIED_TRACES_DESTINATION_ENABLED=true
を設定しました。
これを設定しなかった場合、期待していたspansへのトレース出力を確認できませんでした。Pythonに関する記述では設定不要と書かれているものも多かったのですが、Node.jsにてAgentCore RuntimeのObservabilityを試す場合には、この設定も確認したほうがよさそうです。
3. otel-rt-logsはすぐには出ない
Runtimeを呼び出しても、すべてのObservability情報が同じタイミングで出力されるわけではありませんでした。今回の環境では、通常のログやspansは比較的すぐに確認できましたが、otel-rt-logsは5分程度待つ必要がありました。そのため、「ログが出ない＝設定ミス」とは限らない点には注意が必要です。
まとめ
今回は、Strands Agentsで作成したNode.jsアプリケーションをAmazon Bedrock AgentCore Runtime上で実行し、AWS Distro for OpenTelemetryの自動計装を利用してObservabilityを確認してみました。
今回のポイントは以下です。
| 項目 |
内容 |
| エージェント |
Strands Agents |
| ランタイム |
Amazon Bedrock AgentCore Runtime |
| 言語 |
Node.js |
| OpenTelemetry |
AWS Distro for OpenTelemetry |
| 利用パッケージ |
@aws/aws-distro-opentelemetry-node-autoinstrumentation |
| バージョン |
0.13.0 |
| 起動方法 |
opentelemetry-instrument, dist/app.js |
| AgentCore設定 |
UNIFIED_TRACES_DESTINATION_ENABLED=true |
| CloudWatch設定 |
Transaction Searchを有効化 |
| 確認できた情報 |
Logs / Spans / Metrics / GenAI Observability |
特に印象的だったのは、アプリケーションコードにOpenTelemetryの処理を追加することなく、AgentCore RuntimeとCloudWatchのObservabilityを利用できたことです。また、CloudWatchの生成AIオブザーバビリティ画面では、AgentCore Runtimeについてセッション数やトレース、トークンなどが整理されて表示されるため、エージェントアプリケーションの状態を確認する用途にも使いやすいと感じました。
AgentCore Runtimeでエージェントを運用する場合、単に「動く」だけでなく、「何が起きているのかを観測できる」ことも重要になります。
今回の構成は、AgentCore Runtime上でNode.jsのAIエージェントを動かす際のObservabilityの第一歩として、かなり手軽な構成だと思います。
