Appinsights Instrumentation

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 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 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 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 for how to modify the C# code.
• If the app is a Node.js app, see NODEJS guide for how to modify the JavaScript/TypeScript code.
• If the app is a Python app, see PYTHON guide for how to modify the Python code.

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 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 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.

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.

• 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.

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.

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.

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.

logger = logging.getLogger("<your_logger_namespace>")
logger.setLevel(logging.INFO)

Then send telemetry events by calling its logging methods.

logger.info("info log")