gihyo.jpサイトのロゴ

AgentCoreを運用する技術 ── 本番品質を支える3つの視点

CDK for TypeScriptで検証するAgentCore Observabilityゼロコード計装の仕組み

2026-03-20

はじめに

第一回では、AWSネイティブサービスで実現するDataOps × LLMOps統合アーキテクチャを紹介し、AgentCore Runtime上で動作するAIエージェントの品質管理ライフサイクルを扱いました。

第二回である今回は、そのアーキテクチャを支える技術基盤のひとつであるAgentCore Observabilityに焦点を当てます。

AIエージェントの本番運用とObservability

AIエージェントの本番運用においては、Observabilityを初日から組み込むことが重要です。従来のWebアプリケーションであれば、リクエスト/レスポンスのレイテンシやエラー率を監視すれば概ね十分でした。

しかしAIエージェントでは、以下の特有の課題が加わります。

  • 非決定的な推論過程: 同じ入力に対して、異なるツール呼出パターンや応答が生成される可能性がある
  • ツール呼出の連鎖: 複数のツールを連鎖的に呼び出すため、どの段階で品質が低下したかの特定が容易でない
  • LLM入出力の大容量データ: プロンプトと応答は従来のログと比べデータ量が大きく、格納・検索に工夫が求められる

これらの課題に対応するためには、推論過程をトレースとして記録し、メトリクス・ログとともに可視化するObservability基盤が不可欠です。

AgentCore Observabilityの概要

Amazon Bedrock AgentCore Observabilityは、AIエージェントの動作をトレース・デバッグ・モニタリングするためのマネージドサービスです。テレメトリの収集基盤にはOpenTelemetry(OTel)を採用しています。

OTelはCNCF(Cloud Native Computing Foundation)が策定するテレメトリ収集のオープンスタンダードで、Traces・Metrics・Logsの3種類のシグナル（※システムの動作状態を示すデータカテゴリの公式呼称）を統一的に扱うフレームワークです。

AgentCore Observabilityは、このOTel互換のテレメトリをAgentCoreの各コンポーネントに対して自動的に生成・収集します。テレメトリの送信にはADOT(AWS Distro for OpenTelemetry)を用いています。

OTelの仕様では、OTel SDKをベースにベンダー固有の拡張を付加したものをDistro（ディストリビューション）と呼びます[1]。ADOTはAWSが提供するDistroであり、AWS APIへの署名付きリクエスト（SigV4認証）やX-Ray互換のトレースID生成など、AWSサービスとの連携に必要な機能がOTel SDKに追加されています。

本記事のスコープ

本記事では、AgentCore Observabilityの中でもRuntimeのゼロコード計装に焦点を当てます。また検証では、本番運用におけるIaC(Infrastructure as Code)の標準的な選択肢の一つであるAWS CDK for TypeScriptを用います。検証を通じて、ゼロコード計装の内部的な仕組みを本番運用視点を交えて深掘りします。

ゼロコード計装とは

前節で触れた通り、AgentCore Observabilityはテレメトリの収集基盤にOTelを、送信にADOTを用いています。本節では、OTelが提供する2つの計装アプローチを整理した上で、AgentCore Runtimeのゼロコード計装がこれらとどのような関係にあるのかを明らかにします。

OTelにおける2つの計装アプローチ

OTelは、テレメトリを取得するためのアプローチとしてコードベース計装とゼロコード計装の2つを提供しています[2]。

コードベース計装は、開発者がアプリケーションのソースコードにOTel APIを直接記述する方式です。OTel公式ドキュメントに基づくと、概ね以下の作業が必要になります。

  1. OTel SDK（またはADOT等のDistro）のインストール
  2. アプリケーションコードへの計装（TracerProviderの初期化、スパンの生成、メトリクスの記録など — OTel APIを使ったコード記述）
  3. Exporterの送信先をはじめとする環境変数やSDKの設定
  4. （Collectorを経由する場合）Collectorの構築・設定ファイルの管理

上記のうち、最も開発負担が大きいのは2.のアプリケーションコードへの計装です。各処理にスパンを手動で挿入し、適切な属性を付与し、エラーハンドリングと組み合わせるといった作業は、アプリケーション全体にわたる継続的な取り組みとなります。

ゼロコード計装は、この負担を解消するアプローチです。OTel公式ドキュメントでは、以下のように説明されています。

"Zero-code instrumentation adds the OpenTelemetry API and SDK capabilities to your application typically as an agent or agent-like installation. The specific mechanisms involved may differ by language, ranging from bytecode manipulation, monkey patching, or eBPF to inject calls to the OpenTelemetry API and SDK into your application."

つまり、ゼロコード計装では専用のランチャーがアプリケーション起動時にOTel SDKをアプリケーションプロセスへ自動的に組み込み、HTTPクライアントやデータベースドライバ、ロギングといった領域の主要ライブラリに対してmonkey patching（※実行時にライブラリの既存コードを動的に書き換える手法）でテレメトリ生成コードを注入します。これにより、コードベース計装で最も負担の大きかった2.のアプリケーションコードへの計装が不要となっています。

AgentCore ObservabilityとOTelゼロコード計装

AgentCore Runtimeのゼロコード計装は、このOTelのゼロコード計装を基盤としています。AWS公式ドキュメントでは、AgentCoreのObservabilityを有効化する手順としてOTelのopentelemetry-instrumentコマンドの使用を案内しており、以下の様に述べています。

"Execute your agent code using the OpenTelemetry auto-instrumentation command: opentelemetry-instrument python my_agent.py. This auto-instrumentation approach automatically adds the SDK to the Python path. You may already be using this approach as part of your standard OpenTelemetry implementation."

つまり、AgentCoreのゼロコード計装は独自の仕組みではなく、OTel標準のゼロコード計装をそのまま利用していることが公式ドキュメントから読み取れます。では、OTelのゼロコード計装のテレメトリパイプラインはどのような構成なのか、次に整理します。

OTelゼロコード計装のテレメトリパイプライン

OTelはPythonに限らずJava, Go, .NETなど多くの言語をサポートしていますが、以下では本記事の検証環境であるPythonを前提に説明します。OTelのテレメトリパイプラインは、主に以下のコンポーネントで構成されます。

コンポーネント 役割 実行場所
opentelemetry-instrument アプリケーションの起動プロセス中で実行されるPythonランチャー。アプリのソースコードを変更することなくOTel SDKを組み込み、初期化する[3] アプリプロセス内
OTel SDK, Distro テレメトリの生成・収集を行う。AWSにおいては前述のADOTがこれに該当する アプリプロセス内
Exporter 収集したテレメトリを外部に送信するSDKのコンポーネント。送信先は環境変数で設定される [4] アプリプロセス内
OpenTelemetry Collector テレメトリの受信・フォーマット変換・バッチ処理・転送などを行う中間コンポーネント（省略可能） 別プロセス

ここで重要な点は2つあります。1つめは、opentelemetry-instrument・OTel SDK・Exporterはアプリケーションプロセスの中で動作するコンポーネントであり、Collectorは別プロセスとして動作する中間コンポーネントである点です。2つめは、Collectorは必須ではなく、Exporterがバックエンドへ直接テレメトリを送信する構成（Collectorレス）も可能である点です。以下に、両方のパターンを含むOTelの一般的な構成図を示します。

テレメトリの送信プロトコルとして代表的なものがOTLP(OpenTelemetry Protocol)です。OTLPを用いる場合、Exporterの送信先は環境変数OTEL_EXPORTER_OTLP_ENDPOINTで設定します[3]。シグナル毎に送信先を分ける場合は、以下の環境変数が優先的に使用されます。

  • Traces: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
  • Metrics: OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
  • Logs: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT

OTel仕様におけるこれらの環境変数のデフォルト値はhttp://localhost:4317（gRPC）/http://localhost:4318（HTTP）であり[3]、ローカルで稼働するCollectorへの送信を前提とした設計になっています。

AgentCore Runtimeのゼロコード計装は何をしてくれるのか

ここまでの整理を踏まえ、OTel標準のゼロコード計装と比べてAgentCore Runtimeがさらに何を自動化しているのかをまとめます。

# OTelゼロコード計装で開発者が行う作業 AgentCore Runtime
1 OTel SDK（またはDistro）のインストール 開発者が行う
2 環境変数の設定 不要（Runtimeが自動注入）
3 opentelemetry-instrumentの起動コマンドへの追加 開発者が行う
4 Collectorの構築・管理 不要（Collectorレス？）

前述の通り、コードベース計装で最も負担の大きかった「アプリケーションコードへの計装」はOTelのゼロコード計装により既に不要になっています。AgentCore Runtimeではそれに加えて2.の環境変数設定もRuntime基盤が自動で行うことが公式ドキュメントにて記載されています。例えば、こちらのAWS公式ドキュメントに以下の記述があり、RuntimeがデフォルトでADOT環境変数を自動的にセットしていることが読み取れます。

"Setting this variable (DISABLE_ADOT_OBSERVABILITY=true) to true unsets the AgentCore runtime's default ADOT environment variables, ensuring that none of the default ADOT configurations are set."

一方、4. Collectorの構築・管理に関しては、セットアップ手順にCollectorの構築・設定が一切含まれていない為、Runtime基盤がマネージドにCollectorを構築・管理しているか、Collectorレス構成と推察されます。この点に関して、公式ドキュメントでの明示的な言及は現状確認出来ませんでした。以降は、Runtimeが実際にどのような環境変数を注入し、テレメトリパイプラインがどのように構成されているのかなどを中心に、動作検証を通じて確認していきます。

CDK for TypeScriptを用いた動作検証

ここからは、実際の動作検証を通してAgentCore Runtimeのゼロコード計装の仕組みを確認していきます。AgentCoreの実装には、前述の通りAWS CDK for TypeScriptを用いました。

検証の概要

CDK for TypeScriptからAgentCore Runtimeをデプロイする際には、AgentRuntimeArtifactクラスの5つのファクトリメソッド（fromAsset, fromCodeAsset, fromEcrRepository, fromS3, fromImageUri）を利用出来ます（執筆時点⁠）⁠。

本検証では、Dockerコンテナイメージを用いるfromAsset（Docker/ECRパターン）を主軸に利用しました。また、AIエージェントは第一回と同様Strands Agents SDKで構築し、Claude Sonnet 4を基盤モデルとしてBedrock Knowledge Baseを検索する構成としました。ゼロコード計装の検証が主目的のため、エージェントのロジック自体は最小限とし、代わりにコンテナ内の環境を探るロジックを多く実装し検証を行いました。各パターンのデプロイ後、Runtimeが注入する環境変数を出力する検証用コマンドと通常のプロンプトをそれぞれ数回ずつ送信し、CloudWatch Logsの出力を確認しました。

なお、検証環境の主なコンポーネントのバージョンは以下です。

コンポーネント バージョン
AWS CDK CLI v2.1109.0
@aws-cdk/aws-bedrock-agentcore-alpha v2.241.0-alpha.0
aws-opentelemetry-distro v0.15.0
OpenTelemetry SDK（Runtime検出値） v1.39.1
Pythonランタイム 3.13
リージョン us-east-1

観測結果と考察

以降では、動作検証で得られた観測結果と、そこから読み解けるゼロコード計装の仕組みを併せて述べていきます。なお、考察部分は観測結果や仕様に基づく推察であり、誤っている可能性がある点、予めご理解いただけると幸いです。

1. 環境変数から読み解くテレメトリの送信構成

検証用コードにより、Runtimeが自動設定するOTel関連の環境変数を確認しました。以下の22個が観測されました。

環境変数 値
AGENT_OBSERVABILITY_ENABLED true
AWS_EXECUTION_ENV AWS_BedrockAgentCore_Runtime
AWS_REGION us-east-1
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT https://logs.us-east-1.amazonaws.com/v1/logs
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT https://xray.us-east-1.amazonaws.com/v1/traces
OTEL_EXPORTER_OTLP_PROTOCOL http/protobuf
OTEL_PYTHON_DISTRO aws_distro
OTEL_PYTHON_CONFIGURATOR aws_configurator
OTEL_PYTHON_ID_GENERATOR xray
OTEL_PROPAGATORS baggage,xray,tracecontext
OTEL_TRACES_EXPORTER otlp
OTEL_LOGS_EXPORTER otlp
OTEL_TRACES_SAMPLER parentbased_always_on
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT true
OTEL_RESOURCE_ATTRIBUTES service.name=..., cloud.resource_id=..., ...
OTEL_EXPORTER_OTLP_LOGS_HEADERS x-aws-log-group=..., x-aws-log-stream=otel-rt-logs, ...
OTEL_EXPORTER_OTLP_TIMEOUT 5000
OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION base2_exponential_bucket_histogram
OTEL_AWS_APPLICATION_SIGNALS_ENABLED false
OTEL_METRICS_ADD_APPLICATION_SIGNALS_DIMENSIONS false
OTEL_PYTHON_EXCLUDED_URLS /ping

これらの環境変数から、テレメトリの送信構成について以下の点が読み取れます。

OTEL_TRACES_EXPORTER, OTEL_LOGS_EXPORTERの値や、複数のOTEL_EXPORTER_<略>という環境変数名から、テレメトリの送信プロトコルはデフォルトでOTLPに設定されていると判断出来ます。またOTEL_EXPORTER_OTLP_PROTOCOLの値から、OTLP ExporterがテレメトリをOTLP/HTTPで送信していることが分かります。加えて、TracesとLogs各々の送信先を指すOTEL_EXPORTER_OTLP_TRACES_ENDPOINTとOTEL_EXPORTER_OTLP_LOGS_ENDPOINTの値は、AWSがX-Ray及びCloudWatch Logs用に公式に提供しているOTLP受信エンドポイントでした[5]。

さらに、OTEL_EXPORTER_OTLP_LOGS_HEADERSの値を確認すると、CloudWatch Logsへの出力先が以下のようにHTTPヘッダーで指定されていました。

x-aws-log-group=/aws/bedrock-agentcore/runtimes/{runtimeId}-DEFAULT,
x-aws-log-stream=otel-rt-logs,
x-aws-metric-namespace=bedrock-agentcore

CloudWatch LogsのOTLPエンドポイントはx-aws-log-groupとx-aws-log-streamヘッダーで出力先のロググループ/ストリームを指定する仕様です[6]。

実際、デプロイ後のCloudWatch Logsにはotel-rt-logs（OTel JSON）とruntime-logs（プレーンテキストのstdoutキャプチャ）の2つのストリームが生成されていましたが、上記ヘッダーに指定されているのはotel-rt-logsのみです。runtime-logsはOTelパイプラインとは別にRuntimeがstdout/stderrをキャプチャする経路で生成されたものと見受けられます（後段の「4. opentelemetry-instrumentの役割」参照⁠）⁠。otel-rt-logsの出力例を以下に示します。

{
  "resource": {
    "attributes": {
      "service.name": "obsVerifyAgent.DEFAULT",
      "cloud.region": "us-east-1",
      "cloud.platform": "aws_bedrock_agentcore",
      "telemetry.sdk.version": "1.39.1",
      "telemetry.auto.version": "0.15.0-aws"
    }
  },
  "severityText": "INFO",
  "body": "AGENT_OBSERVABILITY_ENABLED = true",
  "traceId": "69aecfdf01797dd1421693173ddf2bd5",
  "spanId": "0cd510dfab4d8935"
}

AIエージェントのコードでは標準ライブラリのlogging.info()を呼んでいるだけですが、テレメトリの発信元を識別するためのResource Attributes（上記JSONのresource.attributes）と、リクエストの一連の処理を追跡するためのTrace Context（上記JSONのtraceIdとspanId）が自動付与された構造化ログが出力されていました。

2. コンテナ内部の構成

AgentCore Runtimeコンテナ内の稼働中プロセスを確認したところ、python main.py（=エージェント本体）のプロセス(PID 1)が一つだけ動作していることを確認しました。加えて/procディレクトリを走査したところ、Collectorプロセスは見つかりませんでした。さらにファイルシステム上でCollector設定ファイルを検索しましたが（/etc/otel*, /opt/otel*, /opt/collector*等⁠）⁠、こちらも見つかりませんでした。

また、Collectorが別プロセスではなくライブラリとして組み込まれている可能性を検証するためsys.modulesを確認したところ、215個のOTel関連モジュールがロードされていましたが、いずれもSDKやExporter、計装のライブラリであり、Collector関連のモジュールは含まれていませんでした。

以上を踏まえると — Exporterの送信先がAWSのOTLPエンドポイントを直接指している点、コンテナ内にCollectorプロセスもライブラリも存在しない点から — AgentCore Runtimeのゼロコード計装は、TracesとLogsに関してCollectorレス構成で動作していると推察されます。ADOT SDKもこのCollectorレス構成をサポートしています[7]。

3. Metricsシグナルの経路

前節の環境変数には、OTEL_EXPORTER_OTLP_TRACES_ENDPOINTとOTEL_EXPORTER_OTLP_LOGS_ENDPOINTは設定されていましたが、OTEL_EXPORTER_OTLP_METRICS_ENDPOINTは設定されていませんでした。汎用のOTEL_EXPORTER_OTLP_ENDPOINTも未設定のため、OTel仕様に従いMetricsの送信先はデフォルト値（http://localhost:4318）にフォールバックしますが[3]、前述の様にコンテナ内にこのポートをListenしているプロセスは存在しないため、MetricsはOTelパイプラインを通じては送信されていないと考えられます。

これは、AgentCore RuntimeのMetricsがOTelパイプラインとは別の経路で提供される設計であることに起因すると考えられます。AWS公式ドキュメント[8]によると、Invocations, Latency, SessionCountなどのセッションメトリクスやCPU/Memory使用量等のRuntimeメトリクスは、AgentCoreサービス基盤がCloudWatchに自動発行しています。つまり、OTelパイプラインが担うのはTracesとLogsのみであり、Metricsはこのパイプラインの対象外と見受けられます。

4. opentelemetry-instrumentの役割

opentelemetry-instrumentがテレメトリ生成にどのような役割を果たすのかを検証するために、fromCodeAssetの構成でentrypointからopentelemetry-instrumentのみを除外してデプロイしました。

// CDK スタック（TypeScript）— opentelemetry-instrument を省略
const runtime = new AgentRuntime(this, 'Runtime', {
  // ...
  artifact: AgentRuntimeArtifact.fromCodeAsset({
    // ...
    entrypoint: ['main.py'],  // ← opentelemetry-instrument なし
  }),
});

結果は以下の通りでした。

  • Runtimeが自動設定した環境変数: 同一
  • ログストリームruntime-logs: 同一
  • ログストリームotel-rt-logs: ストリームは作成されたが、イベントは一切記録されなかった

opentelemetry-instrumentを省略しても環境変数は注入されるが、テレメトリは予想通り生成されませんでした。一方、runtime-logsは変わらずstdoutをキャプチャしていたことから、runtime-logsはOTelとは無関係にRuntimeがstdout/stderrをキャプチャして書き込んでいるストリームであると考えられます。この対照実験の結果は、環境変数が注入されるだけではテレメトリは生成されず、opentelemetry-instrumentによるSDKの初期化と計装が不可欠であることを示しています。

以上を踏まえた全体像

ここまでの検証結果と考察を踏まえ、AgentCore Runtimeのゼロコード計装の全体像を2つの視点で整理します。

テレメトリ送信のアーキテクチャ

検証結果を踏まえたAgentCore Runtimeのゼロコード計装の全体像を、以下のアーキテクチャ図に示します。

なお、ユーザーのDockerコンテナ外（AgentCore Runtimeの基盤レベル）に透過的なCollectorが介在する可能性を完全には否定出来ません。しかし、以下の3点から、Collectorを挟む合理的な理由は乏しく、Collectorレス構成であると考えるのが妥当と見受けられます。

第一に、Exporterの送信先はAWSのOTLPエンドポイントを直接指しており(前述1.)、Collectorへのルーティングを示す設定は存在しません。

第二に、コンテナ内にCollectorのプロセス・設定ファイル・ライブラリのいずれも確認されませんでした（前述2.⁠）⁠。

第三に、送信先のX-RayとCloudWatch LogsはいずれもOTLPをネイティブに受け付けるため(前述1.)、Collectorによるプロトコル変換やフォーマット変換を挟む技術的な必要性はありません。

ゼロコード計装の3層構造

以上を整理すると、AgentCore Runtimeのゼロコード計装は3つの層で構成されていると捉えることが出来ます。なお、これは執筆時点における筆者の解釈であり、AWSが公式に定義しているものではない点、ご注意下さい。

層1（AgentCore Runtime）は完全マネージドです。「⁠AgentCore Runtimeのゼロコード計装は何をしてくれるのか」の比較表で示した#2（環境変数の自動注入）と#4（Collector不要）が、この層が担っている役割に当たります。環境変数の注入やロググループの作成が内部的にどのように実現されているかは外部からは観測できません。

層2（ADOT + opentelemetry-instrument）は、「⁠OTelゼロコード計装のテレメトリパイプライン」の図における「アプリケーション プロセス」に相当します。つまり、この層はAgentCore独自の仕組みではなく、OTel標準のゼロコード計装のコンポーネントそのものです。「⁠4. opentelemetry-instrumentの役割」で確認した通り、opentelemetry-instrumentを省略した場合、層1の環境変数が注入されるにもかかわらずotel-rt-logsが空でした。これは、層2が層1と層3を橋渡しする役割を果たしていることを示しています。

層3（AIエージェントコード）はOTel固有のコードが不要です。標準のlogging.info()を呼ぶだけで、層2のopentelemetry-instrumentがPythonのロガーをモンキーパッチしているため、Resource AttributesとTrace Contextが付与されたOTelログに自動変換されます。

また、OTelのゼロコード計装はboto3等の主要ライブラリも自動計装の対象としており、Bedrock API呼出がスパンとして記録されることが期待されます。これが「ゼロコード計装」の意味するところです。

本番運用の観点では、各層の管理責務を明確にしておくことが重要です。

層1は完全マネージドのため、障害時にはAWS側への問い合わせが必要です。

層2は開発者が管理するため、ADOTのバージョンアップやopentelemetry-instrumentの設定変更は開発チームの責務になります。

層3はOTelコードが不要である反面、ロガーのモンキーパッチによりlogging.info()の出力形式が変わるため、既存のログ解析パイプラインがある場合は影響を確認する必要があります。

本番運用時の注意事項

検証結果と考察を踏まえると、ゼロコード計装の利便性の裏側には、コスト・運用・信頼性の面で本番環境において事前に把握しておくと良い特性がいくつかあると思われます。

コストへの影響: サンプリング率とログの二重出力

検証で確認した環境変数OTEL_TRACES_SAMPLER=parentbased_always_onは、全トレースを収集する設定です[8]。これは検証や開発時には便利ですが、全てのリクエストがトレースとしてX-Rayに送信されるため、高トラフィックの本番環境ではX-RayとCloudWatchのコストが増大する可能性があると思われます。当該記事の検証では、Runtimeが設定するこの値をCDKの環境変数設定等で上書きできるか否か、また上書きした場合の動作については確認していません。デフォルトのまま利用する場合、コスト規模の事前見積もりが重要となります。

また、runtime-logs（stdoutキャプチャ）とotel-rt-logs（OTel JSON）の両方にログが出力される点にも注意が必要です。logging.info()の呼出は、stdoutへの出力（Runtimeがキャプチャ）と、モンキーパッチされたOTelハンドラーによるOTel JSON出力の両方を生成するため、同じログメッセージが2つのストリームに異なる形式で保存されます。CloudWatch Logsの保存コストが実質的に二重にかかると見受けられるため、本番環境の様な一定のトラフィックが見込まれる環境においては、ロググループの保持期間を適切に設定し、不要なログの蓄積を防ぐことが重要と思われます。

運用フロー: ADOTのバージョン管理

層1の環境変数はRuntime側が設定するため、Runtimeのアップデートによって新しい環境変数が追加されたり、値が変更されたりする可能性があります。層2のADOTバージョンがその変更に対応していない場合、テレメトリの動作が変わる可能性があります。プロジェクト事情に伴いCDK側でADOTのバージョンを固定している場合は、Runtimeの更新時に互換性を確認する運用フローが必要になる可能性があると思われます。

信頼性: ネットワーク障害時のテレメトリ損失

検証で推察した通り、AgentCore Runtimeのゼロコード計装はCollectorレス構成で動作していると見受けられます。この場合、Collectorが担うバッファリングの仕組みが無いため、ネットワーク障害が発生した際のテレメトリ損失への耐性はADOT SDKのエクスポーター実装に依存します。テレメトリの欠損が許容できない場合は、エクスポーターのタイムアウト値（OTEL_EXPORTER_OTLP_TIMEOUT=5000）とリトライ動作の確認が推奨されると思われます。

参考文献

  1. [1] OpenTelemetry "OpenTelemetry Distro" ↩

  2. [2] OpenTelemetry, "Instrumentation" ↩

  3. [3] OpenTelemetry, "OpenTelemetry Protocol Exporter" ↩a↩b↩c↩d

  4. [4] AWS, "OpenTelemetry Protocol (OTLP) Endpoint - AWS X-Ray" ↩

  5. [5] AWS, "OTLP Endpoints - Amazon CloudWatch" ↩

  6. [6] OpenTelemetry, "Environment Variable Specification" ↩

  7. [7] AWS, "Exporting collector-less telemetry using AWS Distro for OpenTelemetry (ADOT) SDK" ↩

  8. [8] AWS, "AgentCore generated runtime observability data" ↩a↩b

おわりに

本記事では、まずOTelのゼロコード計装の仕組みを整理し、AgentCore Runtimeがその上に何を自動化しているのかを位置付けた上で、CDK for TypeScriptによる検証を通じて実際の動作を確認しました。

観測結果と考察から、テレメトリ送信はCollectorレス構成でAWSのOTLPエンドポイントへ直接送信されるアーキテクチャであり、ゼロコード計装全体はRuntime（環境変数注入⁠）⁠、ADOT + opentelemetry-instrument（ブートストラップ⁠）⁠、AIエージェントコード（OTelコード不要）の3層で捉えることが出来ると考えます。

また、内部の仕組みを理解することで見えてきた、サンプリング率やログの二重出力、ADOTのバージョン管理といった本番運用時の注意事項についても整理しました。

第3回では、AgentCore利用時の GRC・ガバナンスに焦点を当てる予定です。

おすすめ記事

記事・ニュース一覧