![[アップデート] Agent Toolkit for AWS の新スキル「amazon-opensearch-service」で自然言語でのログ分析を試してみた](https://images.ctfassets.net/ct0aopd36mqt/wp-thumbnail-b383cfad7452c18278d4772c71cae640/70681da1d5cfd4b8d3a7edcc29830075/amazon-opensearch-service?w=3840&fm=webp)
[アップデート] Agent Toolkit for AWS の新スキル「amazon-opensearch-service」で自然言語でのログ分析を試してみた
クラウド事業統括本部の石川です。Amazon OpenSearch Service / Amazon OpenSearch Serverless に対応した Agent Toolkit for AWS の「amazon-opensearch-service」スキルは、Migration（移行）、Operations（運用）、Search（検索）、Log analytics（ログ分析）、Trace analytics（トレース分析）の 5 つの機能領域をカバーしています。 今回は、Claude Code + OpenSearch Serverless NextGen 環境で「Log analytics（ログ分析）」を試してみました。
Amazon OpenSearch Service は Agent Toolkit for AWS への対応を発表しました。マネージドなリモート MCP サーバーである AWS MCP Server が AWS API 呼び出しを担い、キュレーション済みのナレッジパッケージである amazon-opensearch-service スキルが自然言語のリクエストを適切な機能領域にルーティングすることで、Claude Code、Kiro、Cursor などの AI コーディングエージェントから OpenSearch ドメインと OpenSearch Serverless コレクションを構築・管理・クエリできるようになります。
前回の記事では、スキルの実行時取得（search_documentation → retrieve_skill）と、次世代（NextGen）OpenSearch Serverless のベクトル検索環境の構築までを試しました。今回はその続編です。公式推奨の aws-data-analytics プラグインでスキルを導入し、前回構築した環境に対して、各機能領域へ実際に自然言語でプロンプトを投げながら「スキルがどこまで正しく導いてくれるか」を検証します。
amazon-opensearch-service スキルとは
スキルの実体は、ルーティング定義（SKILL.md）と機能領域ごとのリファレンス（手順書・PPL クエリテンプレート・レポート雛形）をまとめた Markdown パッケージです。エージェントは最初の「Step 0」でリクエストを 5 つの capability のいずれか 1 つに判定し、その capability のエントリポイントだけを読み込んで作業します。5 領域という広さに対して、エージェントのコンテキスト消費を抑える設計です。
スキル全体には「ユニバーサルルール」というガードレールも定義されています。金額見積もりの禁止（料金は https://calculator.aws へ誘導）、認証情報・アカウント ID の出力禁止、A/B 判断では必ず第一推奨を 1 つ選ぶ、マーケティング調の語彙の禁止などです。
やってみた
前提条件
- 検証環境: ap-northeast-1、Claude Code + aws-data-analytics プラグイン v1.1.0（mcp-proxy-for-aws@1.6.3）
- 構築済み OpenSearch Serverless NextGen 環境（collection group: blog-nextgen-cg、VECTORSEARCH コレクション: blog-nextgen-vec、AWS サービス説明文 40 件 + Titan Text Embeddings V2 の 1024 次元ベクトル投入済み、スケールゼロ設定）
ログ分析の検証用に、次の素材も準備しました。
- ログ: EC サイト風 Web API のアプリケーションログ 387 件。2026-07-20 17:00〜17:30 UTC に、payment-db のロック競合起因で /api/checkout が 500 を返すインシデントを仕込んでいます
スキルの導入と疎通確認
公式ドキュメント記載のコマンドでプラグインをインストールし、再読み込みします。
/plugin install aws-data-analytics@claude-plugins-official
/reload-plugins
✔ Successfully installed plugin: aws-data-analytics@claude-plugins-official (scope: user)
Reloaded: 3 plugins · 7 agents · 1 plugin MCP server
これだけで amazon-opensearch-service を含む 8 スキルと、AWS MCP Server への接続設定がまとめて入ります。疎通確認として、次のプロンプトを投げました。
ap-northeast-1 の OpenSearch Serverless コレクションを一覧して
MCP の call_aws ツール経由で、SigV4 認証済みの API 呼び出しが実行されました。プラグインを入れない場合でも、search_documentation でスキルを発見して retrieve_skill でロードする実行時取得が機能することも確認しています。
Log analytics: PPL（Piped Processing Language） でインシデント調査してみる
プロンプト
app-logs インデックスを調査して、2026/07/21時点の過去 24 時間で 500 エラーが増えている原因を PPL で分析してください
app-logs インシデント分析レポート
capability は LOG-ANALYTICS。log-analytics-guide.md は「まずインデックスを発見し、マッピングを確認し、サンプルを見てからクエリを組む」という discovery-first のワークフローと、PPL クエリレシピ集で構成されています。OpenSearch Serverless で PPL（_plugins/_ppl）が使えるかが注目ポイントでしたが、スキルの記載どおり動作しました。サンプルログ 387 件を bulk 投入し、レシピを順に適用します。
PPL: source=app-logs | stats count() by status
[353, 200] [5, 400] [13, 404] [16, 500]
PPL: source=app-logs | where status = 500 | stats count() as errors by path
[16, '/api/checkout']
PPL: source=app-logs | where status = 500
| stats count() as errors by span(@timestamp, 15m) | sort - errors
[9, '2026-07-20 17:00:00']
[7, '2026-07-20 17:15:00']
PPL: source=app-logs | stats avg(latency_ms) as avg_ms,
percentile(latency_ms, 95) as p95_ms by path
[812.05, 2072.4, '/api/checkout'] ← p95 が突出
[65.07, 117.2, '/api/cart']
[64.68, 112.5, '/api/products']
500 エラー 16 件はすべて /api/checkout、時間帯は 17:00〜17:30 に集中、レイテンシ p95 は他パスの約 20 倍——と、仕込んだインシデントを PPL レシピだけで特定できました。ERROR ログの本文も 16 件すべてが同一です。
PPL: source=app-logs | where status = 500 | top 5 message
[16, 'checkout failed: upstream timeout from payment-service (504) after 2000ms']
面白かったのは、ここで止まらず「本当にタイムアウトなのか」を数字で裏取りしてきた点です。
PPL: source=app-logs | where path = '/api/checkout'
| stats count() as cnt, avg(latency_ms) as avg_ms, min(latency_ms) as min_ms,
percentile(latency_ms, 95) as p95_ms by status
[49, 401.9, 86.9, 1960.6, 200]
[16, 2068.0, 2059.6, 2076.0, 500]
決め手は 500 の最小レイテンシが 2059.6ms であることです。16 件すべてが 2000ms の閾値直上に張り付いており、アプリケーション例外なら実行時間はもっとばらつくはずです。平常時との比較も取っています。
PPL: source=app-logs | where path = '/api/checkout'
and (`@timestamp` < TIMESTAMP('2026-07-20 17:00:00')
or `@timestamp` >= TIMESTAMP('2026-07-20 18:00:00'))
| stats count() as cnt, avg(latency_ms) as avg_ms, max(latency_ms) as max_ms
[37, 99.8, 119.0]
17 時台以外の checkout は 37 件すべてが 119.0ms 以内で、劣化はこの 1 時間に限定されています。一方で 17 時台の成功リクエスト 12 件も avg 1333.4ms（平常比 13 倍）まで遅く、完全停止ではなく負荷に対する部分的な飽和という読みが立ちます。
トラフィック側の変化も押さえていました。17 時台は全体 45 件（他時間帯は 16 件前後）、うち checkout が 28 件で、通常の 1〜4 件/時から約 10 倍です。エラー率は 16/28 で 57.1%。client_ip・trace_id とも 16 件すべて異なり、特定クライアント起因ではなく全ユーザーに影響していたことまで確認しています。
ただし、ログだけで到達できるのはここまでです。「payment-service が遅い」は web-api から見た直近のホップにすぎず、その先で何が起きているかはアプリケーションログに残っていません。この一段先は次の Trace analytics で埋めます。
一方、レシピにある ad コマンド（異常検出）はダメ元で試してみたところ、以下のエラーが返されました。
PPL: ... | ad time_field='@timestamp'
HTTP 500: "failed to find action ...MLTrainAndPredictionTaskAction"
OpenSearch Serverless には ML プラグインが載っていないため、ad のような ML 依存コマンドはマネージドドメイン専用と考えられます。
評価: PPL レシピは主要コマンド（head / where / stats / span / percentile / top / sort / match / distinct_count）がすべて OpenSearch Serverless で動作し、実戦的でした。「AOSS は _cat API 非対応なので PPL で代替する」という分岐まで書かれている点も丁寧です。レシピを順に流すだけで対象パスと時間帯までは機械的に絞れますが、そこから先——最小レイテンシで打ち切りを立証し、平常時ベースラインと突き合わせ、成功分の劣化まで見て「部分的な飽和」と言い切る——はエージェント側の詰めによるものでした。レシピは出発点で、証拠の積み上げ方まではスキルに書かれていません。
考察
Log analytics を一通り試して見えたことを、スキルの設計と実務での使いどころという観点から整理します。
PPL を書けなくてもログ分析を始められる
今回投げたのは日本語 1 行のプロンプトだけです。PPL の構文も、span() や percentile() の書き方も、@timestamp をバッククォートで囲む必要があることも、知らないまま結果にたどり着けました。ログ分析の手前にある「クエリ言語の学習コスト」を、スキルとエージェントが肩代わりしてくれる形です。
権限設計との相性も良好です。PPL は読み取り専用のコマンドしか持たないため、エージェントに渡す権限を読み取りに絞ったまま調査を完結できます。インシデント初動の一次切り分けという用途とはよく噛み合います。さらに「AOSS は _cat API 非対応なので PPL で代替する」といった環境差の分岐までスキルに書かれているので、エージェントが使えない API を叩いて空振りすることもありませんでした。
スキルが担保するのは「型」まで
今回の結果は、スキルが担保した部分とエージェントが詰めた部分にはっきり分かれます。スキルの担保範囲は discovery-first のワークフローと PPL レシピ集で、順に流すだけで対象パス /api/checkout と時間帯 17:00〜17:30 までは機械的に絞れます。
一方、500 の最小レイテンシ 2059.6ms から「アプリケーション例外ではなく 2000ms での打ち切り」と立証し、17 時台以外の 37 件（max 119.0ms）をベースラインに取り、成功リクエストまで平常比 13 倍遅い事実から「部分的な飽和」と結論する——この証拠の積み上げ方はレシピ集の外側にあります。
再現性が保証されるのは「どこが壊れているか」までで、「なぜそう言えるか」はエージェントの推論品質に乗ります。裏を返せば、レシピが探索の手数を省いたからこそ推論に寄せられた、とも言えます。
Serverless では動かないコマンドがある前提で使う
異常検出の ad コマンドは、ML プラグイン非搭載のため 500 エラーになりました。ML 依存コマンドはマネージドドメイン専用と考えられます。
ここで注意したいのは、スキルの中に環境差の分岐が書かれている箇所と書かれていない箇所が混在していることです。_cat API については「AOSS では使えないので PPL で代替」と明示されている一方、ad が Serverless で動かないことには触れられていません。スキルの記述を絶対視せず、動かなかったらそれ自体を環境の情報として拾い直す、くらいの距離感で使うのが実際的です。
スキルはある時点のナレッジをスナップショットしたものなので、環境差やサービスの更新に追い越されることは避けられません。事前に全コマンドの可否を洗い出すより、レシピを流して落ちたものを記録していくほうが結果的に早いはずです。
最後に
Agent Toolkit for AWS の amazon-opensearch-service スキルを使って、OpenSearch Serverless 上のアプリケーションログを PPL で分析してみました。プラグイン 1 つを入れて日本語のプロンプトを投げるだけで、インデックスの発見からマッピング確認、PPL でのエラー集計・レイテンシ分布・平常時との比較までが一続きで実行され、仕込んだインシデントの発生箇所・時間帯・性質まで到達できます。PPL を書いた経験がなくても始められる点は、ログ分析の入口として大きいと感じました。
OpenSearch を運用中の方は、まず読み取り系の操作（環境調査や PPL でのログ検索）から試してみるのがおすすめです。エージェントは与えた認証情報の範囲で何でも実行できるため、公式ドキュメントのセキュリティ考慮事項（最小権限・本番と検証の分離・実行前確認）もあわせてご確認ください。
