appinsights-instrumentation

appinsights-instrumentation スキルの概要

appinsights-instrumentation スキルは、汎用的な observability プロンプトよりも手戻りを減らしながら、Web アプリに Azure Application Insights のテレメトリを組み込めるよう支援するスキルです。単に「ログを有効化する」だけではなく、アプリの言語やホスティング形態に合った計測パスを選び、App Insights リソースを作成または既存のものに接続し、アプリに必要な APPLICATIONINSIGHTS_CONNECTION_STRING が確実に設定されるところまでを含めて扱います。

appinsights-instrumentation が向いているユーザー

このスキルは、Azure 上で動く Web アプリに observability を導入したい場合に特に相性が良く、次のようなケースで実用的です。

• Azure でホストされている ASP.NET Core アプリ
• Azure でホストされている Node.js アプリ
• Azure App Service を使っているチーム
• Bicep などの IaC をすでに使っていて、テレメトリ設定をきれいに追加したいリポジトリ

また、エージェントにリポジトリを調べさせてフレームワーク構成を推定し、auto-instrumentation でいけるのか、コード変更が必要なのかを判断させたい場合にも有効です。

ユーザーが最初に気にすること

appinsights-instrumentation を導入する前に、多くのユーザーがまず知りたいのは次の点です。

• 自分のアプリ構成でも使えるのか
• コード変更を避けられるのか
• どのファイルを編集する必要があるのか
• App Insights の connection string はどう作る、または見つけるのか
• インフラコードを更新すべきか、設定を手で入れるべきか

このスキルは、こうした導入判断の壁に対して、広すぎる「observability を追加して」という指示よりも直接的に答えやすいのが強みです。

主な差別化ポイント: auto instrumentation と手動 instrumentation の使い分け

appinsights-instrumentation skill の大きな価値は、すべてのアプリを同じように扱わないことです。対応している Azure App Service のケースではまず auto-instrumentation を優先し、それが使えない場合にだけ手動のコード変更へ切り替えます。

これは重要です。Azure App Service 側で対応しているなら、アプリケーションコードに触れずにテレメトリを有効化したいユーザーは多いためです。

リポジトリから確認できる対応パス

リポジトリ上の情報から見ると、実際に想定されているパスは次のとおりです。

• 対応する ASP.NET Core / Node.js アプリ向けの Azure App Service auto-instrumentation
• Azure.Monitor.OpenTelemetry.AspNetCore を使った ASP.NET Core の手動 instrumentation
• @azure/monitor-opentelemetry を使った Node.js の手動 instrumentation
• トップレベルの前提説明よりは範囲が広いものの、references/PYTHON.md にある Python 向けガイダンス

先に知っておきたい主な制約

このスキルは Azure 前提で、かつホスティング形態を強く意識した設計です。アプリが Azure 上で動いていない場合や、ベンダー中立な OpenTelemetry アーキテクチャの助言だけがほしい場合は、appinsights-instrumentation for Observability では少し対象が狭く感じるかもしれません。真価を発揮するのは、エージェントがアプリとデプロイ形態を確認したうえで、Azure Monitor / App Insights の流儀に沿って正しく適用できる場面です。

appinsights-instrumentation スキルの使い方

導入時の前提と、このスキルの配置場所

このスキルは github/awesome-copilot の skills/appinsights-instrumentation にあります。利用中のツールがスキル導入に対応しているなら、そのリポジトリに対する通常の add-skill フローで追加し、その後 Azure App Insights のセットアップを依頼するときに呼び出します。

このスキル専用のカスタム CLI が中心になっているわけではないため、導入判断で大事なのはパッケージ管理よりも、作業対象のワークスペースに次の情報がそろっているかです。

• アプリのソースコード
• デプロイ先やホスティングの手がかり
• Bicep や Terraform などの IaC ファイル
• 実行中の Azure アプリを特定できるだけのコンテキスト

まずはエージェントに適切な前提情報を渡す

appinsights-instrumentation usage を効果的にするには、いきなり「App Insights を追加して」と始めないことです。このスキルが重視するのは、次のようなアプリの前提情報です。

• 言語
• フレームワーク
• ホスティング先
• デプロイ方式
• コード変更が許容されるかどうか

最初の依頼として良い例は次のようなものです。

• “Instrument this ASP.NET Core app running in Azure App Service. Prefer codeless setup if supported. If not, update code and Bicep.”
• “This Node.js app is deployed to Azure App Service from this repo. Find the entry file, add Azure Monitor instrumentation, and show the env var changes needed.”
• “Inspect this repo and tell me whether auto-instrumentation is possible or whether manual App Insights instrumentation is required.”

appinsights-instrumentation で最重要になる質問

リポジトリの記述では、エージェントは必ず「アプリがどこでホストされているか」を判断すべきと明示されています。ここがひとつ違うだけで、実行計画は大きく変わります。ホスティング情報を省くと、追加の確認往復が発生しやすくなります。

有用な回答例は次のようなものです。

• Azure App Service へのコードデプロイ
• Azure App Service のコンテナ実行
• Azure Container Apps
• ローカル環境のみ
• 不明なので repo とデプロイファイルから推定してほしい

最初に読むべきリポジトリファイル

appinsights-instrumentation install の質を見極めたい場合や、エージェントへの指示を精度よく出したい場合は、次の順番でファイルを見るのがおすすめです。

1. SKILL.md
2. references/AUTO.md
3. references/ASPNETCORE.md
4. references/NODEJS.md
5. examples/appinsights.bicep
6. scripts/appinsights.ps1
7. references/PYTHON.md

この順番が機能する理由は次のとおりです。

• SKILL.md で分岐ロジック全体がわかる
• AUTO.md でコード変更不要の条件が確認できる
• 各言語向けファイルで必要なパッケージとコード修正箇所が具体的に見える
• Bicep のサンプルでインフラ変更の形がつかめる
• PowerShell スクリプトから connection string や設定投入に関する Azure CLI 操作の方向性が読み取れる

auto instrumentation と手動 instrumentation の選び方

判断パターンとしては、次の流れが実践的です。

• アプリが Azure App Service 上の ASP.NET Core または Node.js なら、まず auto-instrumentation を確認する
• auto-instrumentation が未対応、不要、または自分たちのデプロイ手順では不透明すぎるなら、手動 instrumentation に切り替える
• チームがインフラを宣言的に管理しているなら、Portal で一度だけ設定するよりも、IaC とアプリ設定をまとめて更新する

これは appinsights-instrumentation guide の中でも実務的に特に強い部分で、不要なコード変更に時間を使わずに済みます。

ASP.NET Core を手動で instrumentation するワークフロー

ASP.NET Core について、リポジトリが示している流れは次のとおりです。

• パッケージを追加: dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
• using Azure.Monitor.OpenTelemetry.AspNetCore; を追加
• builder.Build() の前に builder.Services.AddOpenTelemetry().UseAzureMonitor(); を追加

そのうえで、App Insights の connection string は appsettings に安易に書くのではなく、環境変数経由で渡します。ここは重要な注意点です。多くのチームが設定をハードコードしたり、ローカル寄りの設定場所に置いたりして、デプロイ時にきれいに引き継げなくなるためです。

Node.js を手動で instrumentation するワークフロー

Node.js の実践的な流れは次のとおりです。

• パッケージを追加: npm install @azure/monitor-opentelemetry
• まず package.json の main フィールドなどからエントリファイルを特定する
• ファイルの先頭近くでライブラリを読み込む
  const { useAzureMonitor } = require("@azure/monitor-opentelemetry");
• useAzureMonitor(); を呼び出す

呼び出し順は重要です。先に環境変数を読み込み、そのあとで useAzureMonitor() を呼び、最後に残りのアプリを読み込む形にします。dotenv を使っている場合は、Azure Monitor の初期化より前に dotenv を初期化する必要があります。

App Insights リソースと connection string の扱い

導入時によく詰まるのは、コードへの instrumentation そのものより、リソース接続まわりです。このスキルはその両方をカバーします。

• Application Insights リソースを作成する、または既存のものを参照する
• connection string を取得する
• APPLICATIONINSIGHTS_CONNECTION_STRING を設定する
• 可能ならその設定を IaC に永続化する

リポジトリに examples/appinsights.bicep と scripts/appinsights.ps1 が含まれていることからも、このスキルが単なるソース編集ではなく、コード層とインフラ層の両方をまたいで使われる前提で作られていることがわかります。

結果が良くなるプロンプトの形

弱いプロンプト:

• “Add observability.”

より強いプロンプト:

• “Use the appinsights-instrumentation skill on this repo. First detect whether this is ASP.NET Core, Node.js, or Python and how it is hosted. Prefer Azure App Service auto-instrumentation if supported. Otherwise, make the minimum code and IaC changes needed to send telemetry to Azure Application Insights. Show the exact files to edit and explain how to set APPLICATIONINSIGHTS_CONNECTION_STRING.”

こちらが良い理由は次のとおりです。

• スタック判定を必須にしている
• auto 優先の方針が埋め込まれている
• ファイル単位の変更を要求している
• 見落とされやすい環境変数要件まで含めている

初回の出力後に確認すべきポイント

エージェントの回答を受け取ったら、計画を採用する前に次を確認してください。

• 言語だけでなく、ホスティング環境まで特定できているか
• 該当する場合に Azure App Service auto-instrumentation を先に検討しているか
• 言語に合った正しいパッケージを指定しているか
• 初期化がアプリ起動の十分早い段階に置かれているか
• connection string を環境変数として扱っているか
• リポジトリが IaC を使っているなら、その変更提案も含まれているか

これらが抜けている場合、その出力はスキルに沿ったものというより、汎用的な回答に寄っている可能性が高いです。

appinsights-instrumentation スキル FAQ

appinsights-instrumentation は普通のプロンプトより優れていますか？

多くの場合は yes です。特に、実際のリポジトリに対して Azure App Insights をセットアップしたいなら有利です。汎用プロンプトだと、ホスティング依存の分岐、auto-instrumentation の選択肢、connection string の具体的な扱いが抜けやすくなります。Azure 固有の抜け漏れを減らしたいなら、appinsights-instrumentation skill の方が向いています。

このスキルは初心者向けですか？

難しすぎるわけではありませんが、完全に入門者向けというよりは実務寄りです。最低限、デプロイに関する基本的な質問に答えられるか、エージェントに repo を調べさせられる前提があります。初心者でも、次の情報を渡せば十分使いやすくなります。

• アプリの言語 / フレームワーク
• Azure のホスティング種別
• App Service を使っているかどうか
• インフラをコード管理しているかどうか

この情報がないと、信頼できる計画を出す前に追加確認が必要になります。

Azure App Service でしか使えませんか？

いいえ。ただし、最も価値のある判断ロジックが現れるのは Azure App Service です。そこで auto-instrumentation が使える可能性があるためです。その経路以外でも、手動 instrumentation、リソース作成、connection string 設定の支援には引き続き使えます。

Python にも対応していますか？

リポジトリには references/PYTHON.md が含まれているため、Python 向けのガイダンスは存在します。ただし、トップレベルの前提説明では ASP.NET Core と Node.js が中心です。Python 対応は有用な参照経路として見つつ、実際のホスティング形態に合うかは本番利用前に確認した方が安全です。

どんな場合は appinsights-instrumentation を使わない方がよいですか？

次のようなケースでは appinsights-instrumentation は優先度が下がります。

• アプリが Azure 以外でホストされていて、クラウド非依存の observability ガイダンスがほしい
• 初期の App Insights 有効化ではなく、高度なカスタム tracing 設計が必要
• すでに成熟した OpenTelemetry instrumentation があり、小さな調整だけで十分
• 主な作業が instrumentation ではなく、ダッシュボード、アラート、KQL である

このスキルは Azure リソースを実際に作成してくれますか？

examples/appinsights.bicep のようなインフラ例に沿ってリソース設定を案内することはできますが、実際に作成されるかどうかは、エージェントの権限とワークフロー次第です。実務では、環境で許可されている IaC や CLI 手順を正確に出させる用途で使うのが現実的です。

appinsights-instrumentation スキルを改善する方法

appinsights-instrumentation にはデプロイ全体像を最初から渡す

appinsights-instrumentation usage を改善する最速の方法は、デプロイの全体像を最初に渡すことです。

• ソースの言語とフレームワーク
• Azure のホスティングサービス
• デプロイ方法
• 使われている infra-as-code ファイル
• Portal での変更が許可されているか

これにより、このスキルで起きやすい最大の失敗、つまり「技術的には正しいが、運用モデルに合っていない経路を選んでしまう」問題を減らせます。

編集依頼の前に、まず判断を求める

品質の高い進め方は次の順です。

1. エージェントにアプリとホスティングを分類させる
2. auto-instrumentation が対応しているか確認させる
3. そのあとでファイル編集や IaC パッチを依頼する

この順番が有効なのは、このスキルの主要な分岐が文法的な編集ではなく、アーキテクチャ判断にあるためです。

エージェントに見るべきファイルを明示する

リポジトリが大きい場合は、確認箇所を明示した方が精度が上がります。

• ASP.NET Core なら Program.cs
• Node.js なら package.json とエントリファイル
• インフラ設定なら Bicep または Terraform ファイル
• ホスティングがわかるデプロイマニフェストやワークフロー

こうすることで、起動ファイルを取り違えた浅い修正や、環境変数を入れるべき IaC の場所の見落としを防ぎやすくなります。

一般論ではなく、ファイル単位の差分を求める

より実装に近い appinsights-instrumentation guide 出力を得たいなら、次を明示的に依頼します。

• どのファイルを変更するか
• どのパッケージをどう入れるか
• 起動時初期化をどこに置くか
• 環境変数をどこへ追加するか
• App Insights リソースとアプリ設定に対する IaC 追加内容

これにより、このスキルを助言テキストから、実行可能な実装計画へ引き上げられます。

よくある失敗パターン

特に注意したい品質リスクは次のとおりです。

• ホスティング確認を飛ばす
• auto-instrumentation の選択肢を見落とす
• アプリ起動の遅すぎるタイミングで telemetry を初期化する
• connection string を不適切な場所に設定する
• コードだけ更新してデプロイ時設定を忘れる
• Azure 上で動くアプリなのに、ローカルの app settings を正とみなしてしまう

このあたりは、二度見レビューの価値が特に高いポイントです。

appinsights-instrumentation の出力を改善する追加入力

最初の回答が汎用的すぎる場合は、次のような修正プロンプトが有効です。

• “Re-run appinsights-instrumentation with hosting-aware decisions. Confirm whether this Azure App Service app qualifies for auto-instrumentation before proposing code changes.”
• “Revise this plan to include the exact file edits, package command, and IaC changes for APPLICATIONINSIGHTS_CONNECTION_STRING.”
• “Compare manual instrumentation vs auto-instrumentation for this repo and recommend one based on the deployment files present.”

コンパイル成功だけでなく observability の成立を検証する

成功条件は、アプリがビルドできることだけではありません。実際に telemetry が流れることまで確認できるよう、エージェントに次を定義させると有効です。

• connection string をどこから取得するのか
• どのデプロイ手順でその設定が適用されるのか
• どのリクエストや起動処理で telemetry が発生する想定なのか
• デプロイ後に Azure 側でどのシグナルが見えるはずか

こうすることで、appinsights-instrumentation for Observability は、本番で起こりがちなサイレントな設定ミスにも対応しやすくなります。

実務で appinsights-instrumentation を最大限活かす使い方

このスキルを継続的に活かしたいなら、周辺のプロンプト運用を次の形で定着させるのがおすすめです。

• いつもホスティング情報を含める
• 毎回 auto と manual の比較を求める
• インフラ変更とコード変更をセットで求める
• デプロイ後の検証チェックリストを必ず要求する

このパターンはリポジトリの構成とよく噛み合っており、短い一行依頼よりもはるかに良い結果につながります。