Skip to content

Commit de4f41c

Browse files
jborsecnikjborsecnik
authored
Merge pull request #188506 from AaronMaxwell/aaronmax-strings
[AppInsights][AaronMax] Connection string migration
2 parents 62e98b3 + 78fde73 commit de4f41c

File tree

3 files changed

+138
-0
lines changed

3 files changed

+138
-0
lines changed

‎articles/azure-monitor/app/media/migrate-from-instrumentation-keys-to-connection-strings/migrate-from-instrumentation-keys-to-connection-strings.png

91.5 KB
Loading

‎articles/azure-monitor/app/migrate-from-instrumentation-keys-to-connection-strings.md

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
title: Migrate from instrumentation keys to connection strings
3+
description: Learn the steps required to upgrade from Azure Monitor Application Insights instrumentation keys to connection strings
4+
ms.topic: conceptual
5+
ms.date: 02/14/2022
6+
---
7+
8+
# Migration process to connection strings for Application Insights resources
9+
10+
This guide walks through migrating from [instrumentation keys](separate-resources.md#about-resources-and-instrumentation-keys) to [connection strings](sdk-connection-string.md#overview).
11+
12+
## Prerequisites
13+
14+
- A [supported SDK version](#supported-sdk-versions)
15+
- An existing [application insights resource](create-workspace-resource.md)
16+
17+
## Migration process
18+
19+
1. Find your connection string displayed on the Overview blade of your Application Insights resource.
20+
21+
:::image type="content" source="media/migrate-from-instrumentation-keys-to-connection-strings/migrate-from-instrumentation-keys-to-connection-strings.png" alt-text="Screenshot displaying Application Insights overview and connection string" lightbox="media/migrate-from-instrumentation-keys-to-connection-strings/migrate-from-instrumentation-keys-to-connection-strings.png":::
22+
23+
2. Hover over the connection string and select the “Copy to clipboard” icon.
24+
25+
3. Configure the Application Insights SDK by following [How to set connection strings](sdk-connection-string.md#how-to-set-a-connection-string).
26+
27+
> [!IMPORTANT]
28+
> Using both a connection string and instrumentation key isn't recommended. Whichever was set last takes precedence.
29+
30+
## Migration at scale (for multiple subscriptions)
31+
32+
You can use environment variables to easily pass a connection string to the Application Insights SDK or Agent. If you hardcode an instrumentation key in your application code, that programming may take precedence before environment variables.
33+
34+
To set a connection string via environment variable, place the value of the connection string into an environment variable named “APPLICATIONINSIGHTS_CONNECTION_STRING”. This process can be automated in your Azure deployments. For example, the following ARM template shows how you can automatically include the correct connection string with an App Services deployment (be sure to include any other App Settings your app requires):
35+
36+
```JSON
37+
{
38+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
39+
"contentVersion": "1.0.0.0",
40+
"parameters": {
41+
"appServiceName": {
42+
"type": "string",
43+
"metadata": {
44+
"description": "Name of the App Services resource"
45+
}
46+
},
47+
"appServiceLocation": {
48+
"type": "string",
49+
"metadata": {
50+
"description": "Location to deploy the App Services resource"
51+
}
52+
},
53+
"appInsightsName": {
54+
"type": "string",
55+
"metadata": {
56+
"description": "Name of the existing Application Insights resource to use with this App Service. Expected to be in the same Resource Group."
57+
}
58+
}
59+
},
60+
"resources": [
61+
{
62+
"apiVersion": "2016-03-01",
63+
"name": "[parameters('appServiceName')]",
64+
"type": "microsoft.web/sites",
65+
"location": "[parameters('appServiceLocation')]",
66+
"properties": {
67+
"siteConfig": {
68+
"appSettings": [
69+
{
70+
"name": "APPLICATIONINSIGHTS_CONNECTION_STRING",
71+
"value": "[reference(concat('microsoft.insights/components/', parameters('appInsightsName')), '2015-05-01').ConnectionString]"
72+
}
73+
]
74+
},
75+
"name": "[parameters('appServiceName')]"
76+
}
77+
}
78+
]
79+
}
80+
81+
```
82+
## Supported SDK Versions
83+
84+
- .NET and .NET Core v2.12.0
85+
- Java v2.5.1 and Java 3.0
86+
- JavaScript v2.3.0
87+
- NodeJS v1.5.0
88+
- Python v1.0.0
89+
90+
## New capabilities
91+
92+
Just like instrumentation keys, connections strings identify a resource to associate your telemetry data with. Connection strings provide a single configuration setting and eliminate the need for multiple proxy settings. It's a reliable, secure, and useful technology for sending data to the monitoring service.
93+
94+
Connection strings allow you to take advantage of the latest capabilities of Application Insights.
95+
96+
- **Reliability:** Connection strings make telemetry ingestion more reliable by removing dependencies on global ingestion endpoints.
97+
98+
- **Security:** Connection strings allow authenticated telemetry ingestion by using [Azure AD authentication for Application Insights](azure-ad-authentication.md).
99+
100+
- **Customized endpoints (sovereign or hybrid cloud environments):** Endpoint settings allow sending data to a specific [Azure Government region](custom-endpoints.md#regions-that-require-endpoint-modification). ([see examples](sdk-connection-string.md#how-to-set-a-connection-string))
101+
102+
- **Privacy (regional endpoints)** – Connection strings ease privacy concerns by sending data to regional endpoints, ensuring data doesn't leave a geographic region.
103+
104+
## Troubleshooting
105+
106+
Follow these steps if data isn't arriving after migration:
107+
108+
1. Confirm you're using a supported SDK/agent that supports connection strings. If you use Application Insights integration in another Azure product offering, check its documentation on how to properly configure a connection string.
109+
110+
2. Confirm you aren't setting both an instrumentation key and connection string at the same time. Instrumentation key settings should be removed from your configuration.
111+
112+
3. Confirm your connection string is exactly as provided in the Azure portal.
113+
114+
## FAQ
115+
116+
### Where else can I find my connection string?
117+
The connection string is also included in the ARM resource properties for your Application Insights resource, under the field name “ConnectionString”.
118+
### How does this impact auto instrumentation?
119+
120+
Auto instrumentation scenarios aren't impacted.
121+
122+
### Is auto instrumentation affected?
123+
124+
You can't enable [Azure AD authentication](azure-ad-authentication.md) for [auto instrumentation](codeless-overview.md) scenarios. We have plans to address this limitation in the future.
125+
126+
### What is the difference between global and regional ingestion?
127+
128+
Global ingestion sends all telemetry data to a single endpoint, no matter where this data will end up or be stored. Regional ingestion allows you to define specific endpoints per region for data ingestion, ensuring data stays within a specific region during processing and storage.
129+
130+
### How do connection strings impact the billing?
131+
132+
Billing isn't impacted.
133+
134+
### Microsoft Q&A
135+
136+
Post questions to the [answers forum](https://docs.microsoft.com/answers/topics/24223/azure-monitor.html).

‎articles/azure-monitor/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -848,6 +848,8 @@ items:
848848
href: app/create-workspace-resource.md
849849
- name: Migrate to a workspace-based resource
850850
href: app/convert-classic-resource.md
851+
- name: Migrate to connection strings
852+
href: app/migrate-from-instrumentation-keys-to-connection-strings.md
851853
- name: Application dashboard
852854
displayName: dashboard, Application Insights dashboard
853855
href: app/overview-dashboard.md

0 commit comments

Comments
 (0)