setup-app-insights

プラグインの確認：node "${PLUGIN_ROOT}/scripts/check-version.js" を実行します。メッセージが出力された場合は、続行する前にユーザーに表示してください。

共通の指示：shared-instructions.md — 最初にお読みください。

Application Insights のセットアップ

app.json → expo.extra.appInsightsConfig を通じて、生成されたアプリで任意に利用できる、顧客が所有する Application Insights テレメトリを設定します。これはホスト／ランタイムの設定であり、コネクターやプランのセクションではありません。データモデル、ネイティブ機能マトリックス、コネクター一覧、画面には一切影響しません。

Application Insights はデフォルトでオフです。このスキルを実行する（または変更を承認する）ことが明示的なオプトインとなります。アプリの説明から同意を推測することはありません。

使用する場合

• /setup-app-insights — 既存のアプリで Application Insights を有効化、変更、または無効化します。
• リクエストが Application Insights の変更のみの場合、/edit-app から呼び出されます（Step 0.5 のファストパスでこちらに委任されます）。
• 例：「このアプリで Application Insights を有効にする」「このアプリが使用する Application Insights リソースを変更する」「このアプリの Application Insights を無効にする」

使用しない場合

• アプリ画面のカスタムイベントを追加または変更する場合 → まずここで Application Insights を設定してから、ソースの変更について /edit-app を続けて実行します。
• データモデル／コネクター／ネイティブ／デザイン／画面の変更 → 該当する /add-*、/setup-*、/edit-app、または /design-system スキルを使用します。
• 新しい Azure Application Insights リソースをプロビジョニングする場合 → 対象外です。このスキルで検出または受け入れるのは、既存のリソースです。

入力

• working_dir — プロジェクトルートの絶対パス（cwd から自動検出するか、オーケストレーターから渡されます）。
• --action <enable|change-resource|disable> — 任意です。省略した場合は、現在の状態と1つの質問から推定します。

Step 1 — 呼び出しモードを検出する

テレメトリチェックポイント：resolve_app_insights_mode

1. Check MOBILE_APP_ORCHESTRATING=1 AND explicit edit-app caller context
   → Mode A (invoked by /edit-app). Use the passed --working-dir. Return a status block.

2. Else resolve working_dir from cwd (must contain app.json with an expo object)
   → Mode B (standalone). Return a human summary.

古いシェルの値ではなく、 app-edit-routing.md の呼び出しスコープのコンテキストを使用してください。どちらのモードでも、設定の承認は Step 3 で行います。

Step 2 — 確認してアクションを決定する

テレメトリチェックポイント：determine_app_insights_action

存在する場合は、以下を読み取ります。

• <working_dir>/app.json
• <working_dir>/app/_layout.tsx
• <working_dir>/package.json
• <working_dir>/memory-bank.md

app.json が存在しない、不正な形式である、または expo オブジェクトがない場合は、変更せずに停止します（Mode A では BLOCKED）。未コミットの作業が app.json または app/_layout.tsx と重複する場合は、shared-instructions.md の変更ファイル重複に関する承認ルールに従ってください。

アクションを決定します。

• enable — appInsightsConfig.enabled が存在しないか false で、ユーザーが有効化を希望している場合。
• change-resource — すでに enabled: true で、ユーザーが別の接続先を希望している場合。
• disable — ユーザーが Application Insights の無効化を希望している場合。
• 意図が曖昧な場合は、現在の enabled 状態を踏まえた3つの選択肢を示して、AskUserQuestion を1回行います。

Step 3 — 変更内容のプレビューと承認

テレメトリチェックポイント：review_app_insights_change

内容を絞ったプレビューを1つ表示し、承認後にのみ続行します。

─── Application Insights ────────────────────────────
Action        <enable | change resource | disable>
Current       enabled: <true|false>
Configuration app.json → expo.extra.appInsightsConfig
Provider      app/_layout.tsx → PowerAppsProvider appConfig
Sensitive     connection string is never printed or stored in memory-bank.md

次のように尋ねます：Apply this Application Insights change?

Step 4 — 選択テレメトリを送信する

アクションの確認後、Mobile Apps の使用状況テレメトリを通じて選択内容を記録します（有効化／リソース変更の場合は enabled、無効化の場合は disabled）。

node "${PLUGIN_ROOT}/hooks/run-telemetry.js" \
  app-insights-selection \
  "<enabled-or-disabled>" \
  "<prompt-or-pretool>" \
  '<working_dir>'

呼び出し元を渡し、イベントの invocationSource がスキルの呼び出し方法と一致するようにします。Mode A（Skill ツール経由で /edit-app などの別のスキルから委任された場合）では pretool、Mode B（ユーザーが /setup-app-insights を直接実行した場合）では prompt を指定します。

このイベントは既存の Mobile Apps テレメトリ制御に従い、Application Insights のリソース詳細や接続文字列を含みません。失敗しても処理を続行し、スキルをブロックすることはありません。

Step 5a — enable / change-resource

テレメトリのチェックポイント：configure_app_insights_resource

現在の Azure CLI の ID から参照できる Application Insights リソースを検出します。

az resource list \
  --resource-type Microsoft.Insights/components \
  --query "[].{name:name,id:id,resourceGroup:resourceGroup,location:location}" \
  -o json

結果に応じて分岐します。

• 1 つ以上のリソースが返された場合： AskUserQuestion を使用して、ユーザーがリソースを選択できるようにします。設定する前に、選択されたコンポーネントがワークスペースベースであることを確認します。az resource list は、クラシックコンポーネントを含むすべての Microsoft.Insights/components を返します。クラシックコンポーネントは、このスキルの要件に準拠していません。選択されたリソースから properties.WorkspaceResourceId を読み取ります。

  WORKSPACE_RESOURCE_ID=$(
    az resource show \
      --ids "<selected-resource-id>" \
      --api-version 2020-02-02 \
      --query properties.WorkspaceResourceId \
      -o tsv
  )
  

  WORKSPACE_RESOURCE_ID が空の場合、そのリソースはクラシック（ワークスペースベースではない）コンポーネントです。設定しないでください。 ワークスペースベースの Application Insights リソースのみがサポートされていることを説明し、ユーザーに別のリソースを選択するか、以下の管理者への引き継ぎを利用してもらいます。それ以外の場合は、接続文字列を出力せずに取得します。

  APP_INSIGHTS_CONNECTION_STRING=$(
    az resource show \
      --ids "<selected-resource-id>" \
      --api-version 2020-02-02 \
      --query properties.ConnectionString \
      -o tsv
  )
  

• ログインしていない場合： az login を実行してから、リソースの検出をもう一度試すようユーザーに伝えます。

• サブスクリプション／リソースへのアクセス権がない場合、または承認に失敗した場合： Application Insights の Azure RBAC は、Power Platform および Entra アプリ登録のアクセス許可とは別であることを説明します。管理者への引き継ぎを提案します。管理者はワークスペースベースの Application Insights リソースを作成または選択し、その接続文字列をユーザーに提供できます。

• リソースが返されなかった場合： 管理者から提供された接続文字列を貼り付けるか、テレメトリを無効のままにするか、ユーザーに尋ねます。ユーザーに Azure リソースの作成を求めないでください。

貼り付けられた接続文字列を受け取るときは、AskUserQuestion の自由記述形式を使用し、回答をチャットやコマンド出力で繰り返さないでください。InstrumentationKey= が含まれていること、および IngestionEndpoint= が含まれているか、標準のパブリッククラウドの既定値を使用できることのみを検証します。接続文字列を memory-bank.md に保存しないでください。

<working_dir>/app.json を更新し、expo.extra.appInsightsConfig に次の内容を設定します。

{
  "expo": {
    "extra": {
      "appInsightsConfig": {
        "enabled": true,
        "connectionString": "<selected-or-pasted-connection-string>",
        "appId": "<appId>",
        "environment": "development",
        "includeUserId": false
      }
    }
  }
}

フィールドのルール：

• appId — 既存の空でない値を保持します。それ以外の場合は、expo.slug、次に package.json の name を使用します。
• environment / includeUserId — 既存の値を保持します。既定値はそれぞれ "development" と false です。ユーザー ID の収集を暗黙的に有効にしないでください。
• enabled: true を設定し、接続文字列のみを置き換えます。appInsightsConfig オブジェクトが存在しない場合は作成し、app.json の他のすべてのフィールドを保持します。

接続文字列を出力したり、別のエージェントに渡したり、native-app-plan.md または memory-bank.md に書き込んだり、要約に含めたりしないでください。

ランタイムに関する注意事項（以降の画面作業向け）

アプリでは @microsoft/applicationinsights-web と React Native の手動デバイスプラグインを使用します。最初のランタイムイベントは PowerAppsNative.ApplicationStarted です。これは、Dev Player でアプリを読み込んだ後の、決定的な取り込みチェックです。ランタイムには、意図的に異なる 2 つのロガーが用意されています。

import {
  getAppLogger,
  getCustomEventsLogger,
} from '@microsoft/power-apps-native-host';

• getAppLogger() はホスト／ランタイム用ロガーです。このイベントは Microsoft OneDS に引き続き送信され、設定された Application Insights リソースにも配信されます。
• getCustomEventsLogger() はアプリのカスタムイベント用です。設定された Application Insights リソースのみに送信され、カスタムイベントが無効の場合は何も行いません。
• カスタムイベントの呼び出しを生成するのは、ユーザーが明示的にイベントを要求した場合、または承認済みの画面仕様に Custom events の項目がある場合のみです。カスタムイベントに getAppLogger() を使用しないでください。
• テレメトリのプロパティには、承認済みのスカラー値（結果コード、所要時間、件数、画面 ID、操作名）を使用する必要があります。フォームの値、自由記述のテキスト、レコードのタイトル、氏名、メールアドレス、電話番号、トークン、正確な座標、ネストされたオブジェクト、完全な URL は決して含めないでください。

memory-bank.md に次の内容を保存します（接続文字列は保存しません）。

- Custom events: enabled
- Custom events app ID: <appId>
- Custom events resource ID: <selected-resource-id or admin-provided>
- Custom events destination: one customer-owned workspace-based Application Insights resource

Step 5b — 無効化

テレメトリのチェックポイント：disable_app_insights

enabled: false を設定し、connectionString を空にして、appId と environment がある場合は保持します。既存の値が明示的に承認済みで保持する必要がある場合を除き、includeUserId: false を維持します。Azure へのサインインやリソースの検出は必要ありません。

{
  "expo": {
    "extra": {
      "appInsightsConfig": {
        "enabled": false,
        "connectionString": "",
        "appId": "<appId>",
        "environment": "development",
        "includeUserId": false
      }
    }
  }
}

memory-bank.md に Custom events: disabled とアプリ ID を記録し、古いリソース ID／送信先の行を削除します。

Step 6 — プロバイダーの接続を確認する

テレメトリのチェックポイント：verify_app_insights_provider

app/_layout.tsx がルートの app.json をインポートし、オブジェクト全体を PowerAppsProvider に渡していることを確認します。

import appConfig from '../app.json';

<PowerAppsProvider appConfig={appConfig}>

いずれかが欠けている場合は、インポートと appConfig プロパティのみを修正し、その他すべてのプロバイダープロパティとレイアウトの動作を維持します。app/_layout.tsx が変更された場合に限り、npx --no-install tsc --noEmit を実行します。

変更後に Node で app.json を解析し、次の条件を確認します。

• enable／change-resource：enabled === true かつ connectionString が空ではないこと。
• disable：enabled === false かつ connectionString === "" であること。

Step 6.5 — 操作の計測を提案する（enable／change-resource のみ）

テレメトリのチェックポイント：offer_operation_instrumentation

このスキルはテレメトリパイプラインを接続するだけで、画面や生成されたサービスは編集しません。Application Insights を有効にすると、アプリの読み込み、未処理エラー、ナビゲーションなどのホストレベルのシグナルは自動的に送信されますが、todo_created や order_deleted のようなドメインイベントはカスタムイベントであり、ソースコードの変更が必要です。こうした変更は /edit-app → screen-planner → screen-builder の担当であり、既存のスカラー値のみを許可する PII 禁止リストに従って、getCustomEventsLogger 経由で名前付きイベントを送信します。ここで後続作業を提案してください。このスキルから操作を計測することは決してありません。

このステップは、enable または change-resource が成功した後にのみ実行します。disable の場合は完全にスキップします。

• モード B（単独実行）： デフォルトをいいえにして、AskUserQuestion を 1 回実行します（計測はオプトイン方式で、Application Insights がデフォルトでオフであることに合わせます）。

  Application Insights は有効です。アプリの主要な操作（作成／更新／削除）について、カスタムイベントを追加しますか？

  • はい → スコープを限定した計測の概要を指定して /edit-app を呼び出し、通常の編集フローでエンティティ、画面、操作の境界を特定してもらいます（このスキルではデータモデルや画面を読み取りません）。

    Invoke skill: /edit-app
    
    Arguments:
      Add custom events at each successful create, update, and
      delete boundary for the app's main entities. Emit named events through
      getCustomEventsLogger with approved scalar properties only — no
      operation results, response payloads, form values, free text, record
      titles, personal identifiers, tokens, precise coordinates, nested
      objects, or complete URLs. Use trackScenario() for any duration.
    

  • いいえ → 通常のモード B の要約で終了します。

• モード A（/edit-app から呼び出された場合）： ユーザーに質問したり、ここから /edit-app を再度呼び出したりしないでください。オーケストレーターに戻ってループが発生します。代わりに、戻り値のブロックで後続の選択肢が利用可能であること（instrumentation_offer: available）を示し、高速パスの完了後に /edit-app がその選択肢を提示できるようにします。

サポート範囲

このスキルは既存の Application Insights リソースを検出または受け入れます。Azure リソースのプロビジョニングは行いません。ユーザーに Azure へのアクセス権がなく、管理者から提供された接続文字列もない場合は、処理を妨げずにテレメトリを無効のままにします。カスタムイベントがオフでもアプリは問題なく動作します。

戻り値

モード A（/edit-app から呼び出された場合）— ステータスブロック。最初の行はステータスコードです：

DONE
action: <enable|change-resource|disable>
enabled: <true|false>
app_id: <appId>
layout_patched: <yes|no>
instrumentation_offer: <available|none>

instrumentation_offer は、enable／change-resource が正常に完了した後にのみ available になります（ステップ 6.5 を参照）。disable の場合、またはテレメトリーを有効にしていない場合は none を使用します。注意事項（例：管理者から提供された文字列を検証できなかった場合）がある状態で適用した場合は DONE_WITH_CONCERNS: <list> を、必須の入力が利用できない場合は NEEDS_CONTEXT: <missing> を、app.json を使用できない場合は BLOCKED: <reason> を使用します。

モード B（単独実行）— ユーザー向けの要約：

このアプリの Application Insights を<有効化|更新|無効化>しました。 設定：app.json → expo.extra.appInsightsConfig リソースを変更する場合や、後で無効にする場合は、再度 /setup-app-insights を実行してください。

enable／change-resource の後、ユーザーがステップ 6.5 の提案を受け入れた場合は、操作のインストルメンテーションを /edit-app に引き継いだことを伝えてください。辞退した場合は、後で /edit-app を実行してカスタムの操作イベントを追加できることを伝えてください。