Skip to content

Commit 0e89451

Browse files
AarDavMaxAarDavMax
committed
Update app service rp integration
1 parent 5745871 commit 0e89451

1 file changed

Lines changed: 284 additions & 12 deletions

File tree

‎articles/app-service/monitor-app-service.md‎

Lines changed: 284 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -47,52 +47,324 @@ Application Insights is an Azure Monitor feature that helps you monitor availabi
4747
> [!NOTE]
4848
> Use a connection string to connect your app to Application Insights. For more information, see [Connection strings in Application Insights](/azure/azure-monitor/app/connection-strings).
4949
50-
To enable Application Insights for any supported language, open your app in the Azure portal, select **Application Insights** > **Enable**, create or select an Application Insights resource, and then select **Apply monitoring settings**. App Service restarts the app.
50+
> [!IMPORTANT]
51+
> If App Service autoinstrumentation and code-based instrumentation are both enabled, the app uses the code-based instrumentation settings. Use one instrumentation method to avoid duplicate telemetry.
52+
53+
Open your app in the Azure portal, select **Application Insights** > **Enable**, create or select an Application Insights resource, and then select **Apply monitoring settings**. App Service restarts the app.
54+
55+
For infrastructure as code, include the Application Insights resource or connection string that your monitoring approach requires, and add the App Service settings in the following tabs. The examples in each tab show only the `siteConfig.appSettings` entries. Keep any other app settings that your app already uses. For more information about managing app settings, see [Configure App Service app settings](configure-common.md#configure-app-settings).
5156

5257
#### [ASP.NET Core](#tab/aspnetcore)
5358

54-
Use **Recommended** to collect telemetry. Use **Disabled** to turn off App Service autoinstrumentation for ASP.NET Core.
59+
##### Support and requirements
5560

56-
> [!NOTE]
57-
> Only .NET [Long Term Support](https://dotnet.microsoft.com/platform/support/policy/dotnet-core) (LTS) releases are supported. [Trim self-contained deployments](/dotnet/core/deploying/trimming/trim-self-contained) aren't supported. Use [manual instrumentation](/azure/azure-monitor/app/opentelemetry-overview) instead.
61+
Use App Service autoinstrumentation with supported .NET [Long Term Support](https://dotnet.microsoft.com/platform/support/policy/dotnet-core) releases. [Trim self-contained deployments](/dotnet/core/deploying/trimming/trim-self-contained) aren't supported. For unsupported scenarios or advanced customization, [instrument through code](/azure/azure-monitor/app/opentelemetry-enable?tabs=aspnetcore).
62+
63+
##### Enable in the Azure portal
64+
65+
After you create or select an Application Insights resource, choose **Recommended** to collect telemetry or **Disabled** to turn off App Service autoinstrumentation.
66+
67+
##### Configure monitoring
68+
69+
To customize sampling, telemetry enrichment, or instrumentation beyond the built-in experience, [instrument through code](/azure/azure-monitor/app/opentelemetry-enable?tabs=aspnetcore).
70+
71+
##### Client-side monitoring
72+
73+
Client-side monitoring is enabled by default when you use **Recommended**. To turn it off, add the `APPINSIGHTS_JAVASCRIPT_ENABLED` app setting and set it to `false`, then restart the app.
74+
75+
##### Deploy at scale
76+
77+
Add these app settings to your deployment:
78+
79+
| App setting | Value | Purpose |
80+
|---|---|---|
81+
| `ApplicationInsightsAgent_EXTENSION_VERSION` | `~2` on Windows or `~3` on Linux | Turns on runtime monitoring. |
82+
| `XDT_MicrosoftApplicationInsights_Mode` | `recommended` or `disabled` | Sets the collection mode. |
83+
| `XDT_MicrosoftApplicationInsights_PreemptSdk` | `1` | Enables App Service interop with the Application Insights SDK for ASP.NET Core. |
84+
85+
The following example uses Linux. Use `~2` on Windows.
86+
87+
<details>
88+
<summary>Example template snippet</summary>
89+
90+
```json
91+
"siteConfig": {
92+
"appSettings": [
93+
{
94+
"name": "ApplicationInsightsAgent_EXTENSION_VERSION",
95+
"value": "~3"
96+
},
97+
{
98+
"name": "XDT_MicrosoftApplicationInsights_Mode",
99+
"value": "recommended"
100+
},
101+
{
102+
"name": "XDT_MicrosoftApplicationInsights_PreemptSdk",
103+
"value": "1"
104+
}
105+
]
106+
}
107+
```
108+
109+
</details>
58110

59111
#### [.NET](#tab/net)
60112

113+
##### Support and requirements
114+
61115
Use **Recommended** or **Basic** for ASP.NET apps.
62116

63-
- **Basic** collects usage trends, correlation from availability results to transactions, host-process unhandled exceptions, and more accurate application performance monitoring (APM) metrics under load when sampling is enabled.
64-
- **Recommended** includes **Basic** and adds CPU, memory, and I/O trends plus correlation across request and dependency boundaries.
117+
##### Enable in the Azure portal
118+
119+
After you create or select an Application Insights resource, choose a collection level for ASP.NET monitoring.
120+
121+
| Collection level | Description |
122+
|---|---|
123+
| **Basic** | Collects usage trends and correlates availability results to transactions. Collects host-process unhandled exceptions. Improves application performance monitoring (APM) metrics under load when sampling is enabled. |
124+
| **Recommended** | Collects everything in **Basic** and adds CPU, memory, and I/O trends plus correlation across request and dependency boundaries. |
125+
126+
##### Configure monitoring
127+
128+
To configure adaptive sampling through App Service app settings, use the `MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor_*` prefix. Common settings include:
129+
130+
- `MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor_InitialSamplingPercentage`
131+
- `MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor_MinSamplingPercentage`
132+
- `MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor_EvaluationInterval`
133+
- `MicrosoftAppInsights_AdaptiveSamplingTelemetryProcessor_MaxTelemetryItemsPerSecond`
134+
135+
For more information, see [Configure adaptive sampling for ASP.NET applications](/azure/azure-monitor/app/sampling#configuring-adaptive-sampling-for-aspnet-applications).
136+
137+
##### Client-side monitoring
138+
139+
Client-side monitoring is off by default. To turn it on, add the `APPINSIGHTS_JAVASCRIPT_ENABLED` app setting and set it to `true`, then restart the app. To turn it off, remove the app setting or set it to `false`. Don't use `APPINSIGHTS_JAVASCRIPT_ENABLED` with `urlCompression`.
140+
141+
##### Deploy at scale
142+
143+
Add these app settings to your deployment:
144+
145+
| App setting | Value | Purpose |
146+
|---|---|---|
147+
| `ApplicationInsightsAgent_EXTENSION_VERSION` | `~2` | Turns on runtime monitoring. |
148+
| `XDT_MicrosoftApplicationInsights_Mode` | `default` or `recommended` | Sets the collection mode. `default` maps to **Basic**. |
149+
| `InstrumentationEngine_EXTENSION_VERSION` | `~1` | Turns on the binary rewrite engine. This setting can increase cold start time. |
150+
| `XDT_MicrosoftApplicationInsights_BaseExtensions` | `~1` | Captures SQL and Azure Table text with dependency calls. This setting requires `InstrumentationEngine_EXTENSION_VERSION` and can increase cold start time. |
151+
152+
<details>
153+
<summary>Example template snippet</summary>
154+
155+
```json
156+
"siteConfig": {
157+
"appSettings": [
158+
{
159+
"name": "ApplicationInsightsAgent_EXTENSION_VERSION",
160+
"value": "~2"
161+
},
162+
{
163+
"name": "XDT_MicrosoftApplicationInsights_Mode",
164+
"value": "recommended"
165+
},
166+
{
167+
"name": "InstrumentationEngine_EXTENSION_VERSION",
168+
"value": "~1"
169+
},
170+
{
171+
"name": "XDT_MicrosoftApplicationInsights_BaseExtensions",
172+
"value": "~1"
173+
}
174+
]
175+
}
176+
```
177+
178+
</details>
65179

66180
#### [Java](#tab/java)
67181

68-
App Service adds the Application Insights Java 3.x agent and starts collecting telemetry.
182+
##### Support and requirements
183+
184+
App Service adds the Application Insights Java 3.x agent and starts collecting telemetry. For Spring Boot native image apps, use the [Azure Monitor OpenTelemetry Distro / Application Insights in Spring Boot native image Java application](https://aka.ms/AzMonSpringNative) instead.
185+
186+
##### Enable in the Azure portal
187+
188+
After you create or select an Application Insights resource, App Service starts collecting telemetry with the attached Java agent.
189+
190+
##### Configure monitoring
191+
192+
If you don't provide Java agent configuration, App Service uses the default configuration. To customize the agent, paste valid JSON into the Azure portal. Exclude the connection string and preview settings. After you save the configuration, App Service stores it in the `APPLICATIONINSIGHTS_CONFIGURATION_FILE` app setting.
193+
194+
For supported settings, see [Configuration options: Azure Monitor Application Insights for Java](/azure/azure-monitor/app/java-standalone-config). To add custom telemetry, see [Add, modify, and filter telemetry](/azure/azure-monitor/app/opentelemetry-add-modify?tabs=java#modify-telemetry).
195+
196+
##### Client-side monitoring
69197

70-
For Spring Boot native image apps, use the [Azure Monitor OpenTelemetry Distro / Application Insights in Spring Boot native image Java application](https://aka.ms/AzMonSpringNative) instead.
198+
To enable client-side monitoring, use the [Browser SDK Loader (Preview)](/azure/azure-monitor/app/javascript-sdk?tabs=javascriptwebsdkloaderscript#add-the-javascript-code) with the Java agent. For more information, see [Configuration options: Azure Monitor Application Insights for Java](/azure/azure-monitor/app/java-standalone-config#browser-sdk-loader-preview).
71199

72-
For agent configuration, see [Configuration options: Azure Monitor Application Insights for Java](/azure/azure-monitor/app/java-standalone-config). To add custom telemetry, see [Add, modify, and filter telemetry](/azure/azure-monitor/app/opentelemetry-add-modify?tabs=java#modify-telemetry).
200+
##### Deploy at scale
201+
202+
Add these app settings to your deployment:
203+
204+
| App setting | Value | Purpose |
205+
|---|---|---|
206+
| `ApplicationInsightsAgent_EXTENSION_VERSION` | `~2` on Windows or `~3` on Linux | Turns on runtime monitoring. |
207+
| `XDT_MicrosoftApplicationInsights_Java` | `0` or `1` | Turns the Java agent on or off on Windows. |
208+
209+
If you deploy custom Java agent configuration, also add `APPLICATIONINSIGHTS_CONFIGURATION_FILE` with the agent JSON. The following example uses Linux. On Windows, also set `XDT_MicrosoftApplicationInsights_Java` to `1`.
210+
211+
<details>
212+
<summary>Example template snippet</summary>
213+
214+
```json
215+
"siteConfig": {
216+
"appSettings": [
217+
{
218+
"name": "ApplicationInsightsAgent_EXTENSION_VERSION",
219+
"value": "~3"
220+
},
221+
{
222+
"name": "APPLICATIONINSIGHTS_CONFIGURATION_FILE",
223+
"value": "<valid Java agent JSON>"
224+
}
225+
]
226+
}
227+
```
228+
229+
</details>
73230

74231
#### [Node.js](#tab/nodejs)
75232

233+
##### Support and requirements
234+
76235
App Service supports Node.js autoinstrumentation on Linux for code-based apps and custom containers, and on Windows for code-based apps. This integration is in public preview.
77236

78-
To configure the attached agent, set `APPLICATIONINSIGHTS_CONFIGURATION_CONTENT` or `APPLICATIONINSIGHTS_CONFIGURATION_FILE` in App Service app settings. For supported options, see [Node.js configuration](https://github.com/microsoft/ApplicationInsights-node.js#configuration).
237+
##### Enable in the Azure portal
238+
239+
After you create or select an Application Insights resource, App Service starts collecting telemetry with the attached Node.js agent.
240+
241+
##### Configure monitoring
242+
243+
Set `APPLICATIONINSIGHTS_CONFIGURATION_CONTENT` to a JSON string or set `APPLICATIONINSIGHTS_CONFIGURATION_FILE` to a file path that contains valid JSON.
244+
245+
```json
246+
{
247+
"samplingPercentage": 80,
248+
"enableAutoCollectExternalLoggers": true,
249+
"enableAutoCollectExceptions": true,
250+
"enableAutoCollectHeartbeat": true,
251+
"enableSendLiveMetrics": true
252+
}
253+
```
254+
255+
For supported options, see [Node.js configuration](https://github.com/microsoft/ApplicationInsights-node.js#configuration).
256+
257+
##### Client-side monitoring
258+
259+
To enable client-side monitoring, [add the JavaScript SDK to your application](/azure/azure-monitor/app/javascript-sdk?tabs=javascriptwebsdkloaderscript#add-the-javascript-code).
260+
261+
##### Deploy at scale
262+
263+
Add these app settings to your deployment:
264+
265+
| App setting | Value | Purpose |
266+
|---|---|---|
267+
| `ApplicationInsightsAgent_EXTENSION_VERSION` | `~2` on Windows or `~3` on Linux | Turns on runtime monitoring. |
268+
| `XDT_MicrosoftApplicationInsights_NodeJS` | `0` or `1` | Turns the Node.js agent on or off on Windows. |
269+
270+
If you want to deploy agent configuration with the app, add `APPLICATIONINSIGHTS_CONFIGURATION_CONTENT` or `APPLICATIONINSIGHTS_CONFIGURATION_FILE` too. The following example uses Linux. On Windows, also set `XDT_MicrosoftApplicationInsights_NodeJS` to `1`.
271+
272+
<details>
273+
<summary>Example template snippet</summary>
274+
275+
```json
276+
"siteConfig": {
277+
"appSettings": [
278+
{
279+
"name": "ApplicationInsightsAgent_EXTENSION_VERSION",
280+
"value": "~3"
281+
},
282+
{
283+
"name": "APPLICATIONINSIGHTS_CONFIGURATION_CONTENT",
284+
"value": "{ \"samplingPercentage\": 80 }"
285+
}
286+
]
287+
}
288+
```
289+
290+
</details>
79291

80292
#### [Python](#tab/python)
81293

294+
##### Support and requirements
295+
82296
Python autoinstrumentation is supported for Python 3.9 through 3.13 on Linux App Service apps that are deployed as code. Custom containers aren't supported.
83297

298+
Don't use App Service autoinstrumentation if your app already uses manual OpenTelemetry instrumentation, such as the [Azure Monitor OpenTelemetry Distro](/azure/azure-monitor/app/opentelemetry-enable?tabs=python) or the [Azure Monitor OpenTelemetry Exporter](/python/api/overview/azure/monitor-opentelemetry-exporter-readme). This setup sends duplicate telemetry.
299+
84300
Live Metrics isn't available for App Service Python autoinstrumentation. If you need Live Metrics, use the [Azure Monitor OpenTelemetry Distro](/azure/azure-monitor/app/opentelemetry-enable?tabs=python).
85301

302+
##### Enable in the Azure portal
303+
304+
After you create or select an Application Insights resource, App Service starts collecting telemetry for your Python app.
305+
306+
##### Configure monitoring
307+
86308
App Service collects logs from the root logger and autoinstruments common libraries, including `Django`, `FastAPI`, `Flask`, `psycopg2`, `requests`, `urllib`, and `urllib3`.
87309

88310
For Django apps, set `DJANGO_SETTINGS_MODULE` in your App Service app settings.
89311

90-
To collect telemetry from other libraries, add supported OpenTelemetry community instrumentation libraries to your app's `requirements.txt` file. App Service detects installed instrumentations automatically. For more information, see [OpenTelemetry community instrumentations](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation).
312+
To collect telemetry from other libraries, add supported OpenTelemetry community instrumentation packages to your app's `requirements.txt` file. App Service detects installed instrumentations automatically. For more information, see [OpenTelemetry community instrumentations](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation).
313+
314+
You can configure Python autoinstrumentation with OpenTelemetry environment variables. Common settings include:
315+
316+
| App setting | Use |
317+
|---|---|
318+
| `OTEL_SERVICE_NAME` or `OTEL_RESOURCE_ATTRIBUTES` | Sets the service name or other resource attributes. |
319+
| `OTEL_TRACES_SAMPLER_ARG` | Sets the trace sampling ratio from `0` to `1`. |
320+
| `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS` | Disables specific instrumentations with a comma-separated list. |
321+
| `OTEL_LOGS_EXPORTER`, `OTEL_METRICS_EXPORTER`, `OTEL_TRACES_EXPORTER` | Turns off signal export when you set the value to `None`. |
322+
323+
For the full list, see [OpenTelemetry environment variables](https://opentelemetry.io/docs/reference/specification/sdk-environment-variables/).
324+
325+
##### Client-side monitoring
326+
327+
To enable client-side monitoring, [add the JavaScript SDK to your application](/azure/azure-monitor/app/javascript-sdk?tabs=javascriptwebsdkloaderscript#add-the-javascript-code).
91328

92-
To configure Python autoinstrumentation, set [OpenTelemetry environment variables](https://opentelemetry.io/docs/reference/specification/sdk-environment-variables/) in App Service app settings.
329+
##### Deploy at scale
330+
331+
Add these app settings to your deployment:
332+
333+
| App setting | Value | Purpose |
334+
|---|---|---|
335+
| `APPLICATIONINSIGHTS_CONNECTION_STRING` | Your Application Insights connection string | Connects the app to your Application Insights resource. |
336+
| `ApplicationInsightsAgent_EXTENSION_VERSION` | `~3` | Turns on runtime monitoring on Linux App Service. |
337+
338+
Add optional OpenTelemetry app settings, such as `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_TRACES_SAMPLER_ARG`, or `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS`, if your deployment needs them.
339+
340+
<details>
341+
<summary>Example template snippet</summary>
342+
343+
```json
344+
"siteConfig": {
345+
"appSettings": [
346+
{
347+
"name": "APPLICATIONINSIGHTS_CONNECTION_STRING",
348+
"value": "<connection string>"
349+
},
350+
{
351+
"name": "ApplicationInsightsAgent_EXTENSION_VERSION",
352+
"value": "~3"
353+
},
354+
{
355+
"name": "OTEL_SERVICE_NAME",
356+
"value": "<service name>"
357+
}
358+
]
359+
}
360+
```
361+
362+
</details>
93363

94364
---
95365

366+
If you run into issues, use [Troubleshoot Application Insights integration with Azure App Service](/troubleshoot/azure/azure-monitor/app-insights/telemetry/troubleshoot-app-service-issues).
367+
96368
[!INCLUDE [horz-monitor-resource-types](~/reusable-content/ce-skilling/azure/includes/azure-monitor/horizontals/horz-monitor-resource-types.md)]
97369
For more information about the resource types for App Service, see [App Service monitoring data reference](monitor-app-service-reference.md).
98370

0 commit comments

Comments
 (0)