Merge pull request #525 from JasonYeMSFT/chuye/appinsights-instrumentation-skill

codemillmatt · web-flow · commit 750dff407bae · 2026-01-09T13:42:16.000-10:00
feat: add appinsights-instrumentation skill thanks @JasonYeMSFT
diff --git a/docs/README.skills.md b/docs/README.skills.md
@@ -22,6 +22,7 @@ Skills differ from other primitives by supporting bundled assets (scripts, code
 
 | Name | Description | Bundled Assets |
 | ---- | ----------- | -------------- |
+| [appinsights-instrumentation](../skills/appinsights-instrumentation/SKILL.md) | Instrument a webapp to send useful telemetry data to Azure App Insights | `LICENSE.txt`<br />`examples/appinsights.bicep`<br />`references/ASPNETCORE.md`<br />`references/AUTO.md`<br />`references/NODEJS.md`<br />`references/PYTHON.md`<br />`scripts/appinsights.ps1` |
 | [azure-role-selector](../skills/azure-role-selector/SKILL.md) | When user is asking for guidance for which role to assign to an identity given desired permissions, this agent helps them understand the role that will meet the requirements with least privilege access and how to apply that role. | `LICENSE.txt` |
 | [github-issues](../skills/github-issues/SKILL.md) | Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, or manage issue workflows. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", or any GitHub issue management task. | `references/templates.md` |
 | [nuget-manager](../skills/nuget-manager/SKILL.md) | Manage NuGet packages in .NET projects/solutions. Use this skill when adding, removing, or updating NuGet package versions. It enforces using `dotnet` CLI for package management and provides strict procedures for direct file edits only when updating versions. | None |
diff --git a/skills/appinsights-instrumentation/LICENSE.txt b/skills/appinsights-instrumentation/LICENSE.txt
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2025 (c) Microsoft Corporation.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE
diff --git a/skills/appinsights-instrumentation/SKILL.md b/skills/appinsights-instrumentation/SKILL.md
@@ -0,0 +1,48 @@
+---
+name: appinsights-instrumentation
+description: 'Instrument a webapp to send useful telemetry data to Azure App Insights'
+---
+
+# AppInsights instrumentation
+
+This skill enables sending telemetry data of a webapp to Azure App Insights for better observability of the app's health.
+
+## When to use this skill
+
+Use this skill when the user wants to enable telemetry for their webapp.
+
+## Prerequisites
+
+The app in the workspace must be one of these kinds
+
+- An ASP.NET Core app hosted in Azure
+- A Node.js app hosted in Azure
+
+## Guidelines
+
+### Collect context information
+
+Find out the (programming language, application framework, hosting) tuple of the application the user is trying to add telemetry support in. This determines how the application can be instrumented. Read the source code to make an educated guess. Confirm with the user on anything you don't know. You must always ask the user where the application is hosted (e.g. on a personal computer, in an Azure App Service as code, in an Azure App Service as container, in an Azure Container App, etc.). 
+
+### Prefer auto-instrument if possible
+
+If the app is a C# ASP.NET Core app hosted in Azure App Service, use [AUTO guide](references/AUTO.md) to help user auto-instrument the app.
+
+### Manually instrument
+
+Manually instrument the app by creating the AppInsights resource and update the app's code. 
+
+#### Create AppInsights resource
+
+Use one of the following options that fits the environment.
+
+- Add AppInsights to existing Bicep template. See [examples/appinsights.bicep](examples/appinsights.bicep) for what to add. This is the best option if there are existing Bicep template files in the workspace.
+- Use Azure CLI. See [scripts/appinsights.ps1](scripts/appinsights.ps1) for what Azure CLI command to execute to create the App Insights resource.
+
+No matter which option you choose, recommend the user to create the App Insights resource in a meaningful resource group that makes managing resources easier. A good candidate will be the same resource group that contains the resources for the hosted app in Azure.
+
+#### Modify application code
+
+- If the app is an ASP.NET Core app, see [ASPNETCORE guide](references/ASPNETCORE.md) for how to modify the C# code.
+- If the app is a Node.js app, see [NODEJS guide](references/NODEJS.md) for how to modify the JavaScript/TypeScript code.
+- If the app is a Python app, see [PYTHON guide](references/PYTHON.md) for how to modify the Python code.
diff --git a/skills/appinsights-instrumentation/examples/appinsights.bicep b/skills/appinsights-instrumentation/examples/appinsights.bicep
@@ -0,0 +1,30 @@
+@description('Location for all resources')
+param location string = resourceGroup().location
+
+@description('Name for new Application Insights')
+param name string
+
+// Create Log Analytics Workspace
+resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2022-10-01' = {
+  name: '${name}-workspace'
+  location: location
+  properties: {
+    sku: {
+      name: 'PerGB2018'
+    }
+    retentionInDays: 30
+  }
+}
+
+// Create Application Insights
+resource applicationInsights 'Microsoft.Insights/components@2020-02-02' = {
+  name: name
+  location: location
+  kind: 'web'
+  properties: {
+    Application_Type: 'web'
+    WorkspaceResourceId: logAnalyticsWorkspace.id
+  }
+}
+
+output connectionString string = applicationInsights.properties.ConnectionString
diff --git a/skills/appinsights-instrumentation/references/ASPNETCORE.md b/skills/appinsights-instrumentation/references/ASPNETCORE.md
@@ -0,0 +1,29 @@
+## Modify code
+
+Make these necessary changes to the app.
+
+- Install client library
+```
+dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
+```
+
+- Configure the app to use Azure Monitor
+An ASP.NET Core app typically has a Program.cs file that "builds" the app. Find this file and apply these changes.
+  - Add `using Azure.Monitor.OpenTelemetry.AspNetCore;` at the top
+  - Before calling `builder.Build()`, add this line `builder.Services.AddOpenTelemetry().UseAzureMonitor();`.
+
+> Note: since we modified the code of the app, the app needs to be deployed to take effect.
+
+## Configure App Insights connection string
+
+The App Insights resource has a connection string. Add the connection string as an environment variable of the running app. You can use Azure CLI to query the connection string of the App Insights resource. See [scripts/appinsights.ps1](scripts/appinsights.ps1) for what Azure CLI command to execute for querying the connection string.
+
+After getting the connection string, set this environment variable with its value.
+
+```
+"APPLICATIONINSIGHTS_CONNECTION_STRING={your_application_insights_connection_string}"
+```
+
+If the app has IaC template such as Bicep or terraform files representing its cloud instance, this environment variable should be added to the IaC template to be applied in each deployment. Otherwise, use Azure CLI to manually apply the environment variable to the cloud instance of the app. See [scripts/appinsights.ps1](scripts/appinsights.ps1) for what Azure CLI command to execute for setting this environment variable.
+
+> Important: Don't modify appsettings.json. It was a deprecated way to configure App Insights. The environment variable is the new recommended way.
diff --git a/skills/appinsights-instrumentation/references/AUTO.md b/skills/appinsights-instrumentation/references/AUTO.md
@@ -0,0 +1,13 @@
+# Auto-instrument app
+
+Use Azure Portal to auto-instrument a webapp hosted in Azure App Service for App Insights without making any code changes. Only the following types of app can be auto-instrumented. See [supported environments and resource providers](https://learn.microsoft.com/azure/azure-monitor/app/codeless-overview#supported-environments-languages-and-resource-providers).
+
+- ASP.NET Core app hosted in Azure App Service
+- Node.js app hosted in Azure App Service
+
+Construct a url to bring the user to the Application Insights blade in Azure Portal for the App Service App.
+```
+https://portal.azure.com/#resource/subscriptions/{subscription_id}/resourceGroups/{resource_group_name}/providers/Microsoft.Web/sites/{app_service_name}/monitoringSettings
+```
+
+Use the context or ask the user to get the subscription_id, resource_group_name, and the app_service_name hosting the webapp.
diff --git a/skills/appinsights-instrumentation/references/NODEJS.md b/skills/appinsights-instrumentation/references/NODEJS.md
@@ -0,0 +1,28 @@
+## Modify code
+
+Make these necessary changes to the app.
+
+- Install client library
+```
+npm install @azure/monitor-opentelemetry
+```
+
+- Configure the app to use Azure Monitor
+A Node.js app typically has an entry file that is listed as the "main" property in package.json. Find this file and apply these changes in it.
+  - Require the client library at the top. `const { useAzureMonitor } = require("@azure/monitor-opentelemetry");`
+  - Call the setup method. `useAzureMonitor();`
+
+> Note: The setup method should be called as early as possible but it must be after the environment variables are configured since it needs the App Insights connection string from the environment variable. For example, if the app uses dotenv to load environment variables, the setup method should be called after it but before anything else.
+> Note: since we modified the code of the app, it needs to be deployed to take effect.
+
+## Configure App Insights connection string
+
+The App Insights resource has a connection string. Add the connection string as an environment variable of the running app. You can use Azure CLI to query the connection string of the App Insights resource. See [scripts/appinsights.ps1] for what Azure CLI command to execute for querying the connection string.
+
+After getting the connection string, set this environment variable with its value.
+
+```
+"APPLICATIONINSIGHTS_CONNECTION_STRING={your_application_insights_connection_string}"
+```
+
+If the app has IaC template such as Bicep or terraform files representing its cloud instance, this environment variable should be added to the IaC template to be applied in each deployment. Otherwise, use Azure CLI to manually apply the environment variable to the cloud instance of the app. See what Azure CLI command to execute for setting this environment variable.
diff --git a/skills/appinsights-instrumentation/references/PYTHON.md b/skills/appinsights-instrumentation/references/PYTHON.md
@@ -0,0 +1,48 @@
+## Modify code
+
+Make these necessary changes to the app.
+
+- Install client library
+```
+pip install azure-monitor-opentelemetry
+```
+
+- Configure the app to use Azure Monitor
+Python applications send telemetry via the logger class in Python standard library. Create a module that configures and creates a logger that can send telemetry.
+
+```python
+import logging
+from azure.monitor.opentelemetry import configure_azure_monitor
+
+configure_azure_monitor(
+    logger_name="<your_logger_namespace>"
+)
+logger = logging.getLogger("<your_logger_namespace>")
+```
+
+> Note: since we modified the code of the app, it needs to be deployed to take effect.
+
+## Configure App Insights connection string
+
+The App Insights resource has a connection string. Add the connection string as an environment variable of the running app. You can use Azure CLI to query the connection string of the App Insights resource. See [scripts/appinsights.ps1] for what Azure CLI command to execute for querying the connection string.
+
+After getting the connection string, set this environment variable with its value.
+
+```
+"APPLICATIONINSIGHTS_CONNECTION_STRING={your_application_insights_connection_string}"
+```
+
+If the app has IaC template such as Bicep or terraform files representing its cloud instance, this environment variable should be added to the IaC template to be applied in each deployment. Otherwise, use Azure CLI to manually apply the environment variable to the cloud instance of the app. See what Azure CLI command to execute for setting this environment variable.
+
+## Send data
+
+Create a logger that is configured to send telemetry.
+```python
+logger = logging.getLogger("<your_logger_namespace>")
+logger.setLevel(logging.INFO)
+```
+
+Then send telemetry events by calling its logging methods.
+```python
+logger.info("info log")
+```
diff --git a/skills/appinsights-instrumentation/scripts/appinsights.ps1 b/skills/appinsights-instrumentation/scripts/appinsights.ps1
@@ -0,0 +1,20 @@
+# Create App Insights resource (3 steps)
+## Add the Application Insights extension
+az extension add -n application-insights
+## Create a Log Analytics workspace
+az monitor log-analytics workspace create --resource-group $resourceGroupName --workspace-name $logAnalyticsWorkspaceName --location $azureRegionName
+## Create the Application Insights resource
+az monitor app-insights component create --app $applicationInsightsResourceName --location $azureRegionName --resource-group $resourceGroupName --workspace $logAnalyticsWorkspaceName
+
+# Query connection string of App Insights
+az monitor app-insights component show --app $applicationInsightsResourceName --resource-group $resourceGroupName --query connectionString --output tsv
+
+# Set environment variable of App Service
+az webapp config appsettings set --resource-group $resourceGroupName --name $appName --settings $key=$value
+
+# Set environment variable of Container App
+# Or update an existing container app
+az containerapp update -n $containerAppName -g $resourceGroupName --set-env-vars $key=$value
+
+# Set environment variable of Function App
+az functionapp config appsettings set --name $functionName --resource-group $ResourceGroupName --settings $key=$value
