Connection strings

Article
09/24/2024

This article shows how to use connection strings.

Overview

Note

The following documentation relies on the Application Insights classic API. The long-term plan for Application Insights is to collect data using OpenTelemetry. For more information, see Enable Azure Monitor OpenTelemetry for .NET, Node.js, Python and Java applications and our OpenTelemetry Roadmap. Migration guidance is available for .NET, Node.js, and Python.

Connection strings define where to send telemetry data.

Key-value pairs provide an easy way for users to define a prefix suffix combination for each Application Insights service or product.

Note

On March 31, 2025, support for instrumentation key ingestion will end. Instrumentation key ingestion will continue to work, but we'll no longer provide updates or support for the feature. Transition to connection strings to take advantage of new capabilities.

Scenario overview

Scenarios most affected by this change:

Firewall exceptions or proxy redirects:

In cases where monitoring for intranet web server is required, our earlier solution asked you to add individual service endpoints to your configuration. For more information, see the Can I monitor an intranet web server?. Connection strings offer a better alternative by reducing this effort to a single setting. A simple prefix, suffix amendment, allows automatic population and redirection of all endpoints to the right services.
Sovereign or hybrid cloud environments:

Users can send data to a defined Microsoft Azure operated by 21Vianet Region. By using connection strings, you can define endpoint settings for your intranet servers or hybrid cloud settings.

Get started

Review the following sections to get started.

Find your connection string

Your connection string appears in the Overview section of your Application Insights resource.

Schema

Schema elements are explained in the following sections.

Max length

The connection has a maximum supported length of 4,096 characters.

Key-value pairs

A connection string consists of a list of settings represented as key-value pairs separated by a semicolon: key1=value1;key2=value2;key3=value3

Syntax

InstrumentationKey (for example, 00000000-0000-0000-0000-000000000000). InstrumentationKey is a required field.
Authorization (for example, ikey). This setting is optional because today we only support ikey authorization.
EndpointSuffix (for example, applicationinsights.azure.cn). Setting the endpoint suffix tells the SDK which Azure cloud to connect to. The SDK assembles the rest of the endpoint for individual services.
Explicit endpoints. Any service can be explicitly overridden in the connection string:
- IngestionEndpoint (for example, https://dc.applicationinsights.azure.cn)
- LiveEndpoint (for example, https://live.applicationinsights.azure.cn)
- ProfilerEndpoint (for example, https://profiler.monitor.azure.cn)
- SnapshotEndpoint (for example, https://snapshot.monitor.azure.cn)

Endpoint schema

<prefix>.<suffix>

Prefix: Defines a service.
Suffix: Defines the common domain name.

Valid suffixes

applicationinsights.azure.cn
applicationinsights.us

For more information, see Regions that require endpoint modification.

Valid prefixes

Telemetry Ingestion: dc
Live Metrics: live
Profiler: profiler
Snapshot: snapshot

Is the connection string a secret?

The connection string contains an ikey, which is a unique identifier used by the ingestion service to associate telemetry to a specific Application Insights resource. These ikey unique identifiers aren't security tokens or security keys. If you want to protect your AI resource from misuse,the ingestion endpoint provides authenticated telemetry ingestion options based on Microsoft Entra ID.

Note

The Application Insights JavaScript SDK requires the connection string to be passed in during initialization and configuration. It's viewable in plain text in client browsers. There's no easy way to use the Microsoft Entra ID-based authentication for browser telemetry. We recommend that you consider creating a separate Application Insights resource for browser telemetry if you need to secure the service telemetry.

Connection string examples

Here are some examples of connection strings.

Connection string with an endpoint suffix

InstrumentationKey=00000000-0000-0000-0000-000000000000;EndpointSuffix=applicationinsights.azure.cn;

In this example, the connection string specifies the endpoint suffix in Microsoft Azure operated by 21Vianet and the SDK constructs service endpoints.

Authorization scheme defaults to "ikey"
Instrumentation key: 00000000-0000-0000-0000-000000000000
The regional service URIs are based on the provided endpoint suffix:
- Ingestion: https://dc.applicationinsights.azure.cn
- Live metrics: https://live.applicationinsights.azure.cn
- Profiler: https://profiler.applicationinsights.azure.cn
- Debugger: https://snapshot.applicationinsights.azure.cn

Connection string with explicit endpoint overrides

InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://custom.com:111/;LiveEndpoint=https://custom.com:222/;ProfilerEndpoint=https://custom.com:333/;SnapshotEndpoint=https://custom.com:444/;

In this example, the connection string specifies explicit overrides for every service. The SDK uses the exact endpoints provided without modification:

Authorization scheme defaults to "ikey"
Instrumentation key: 00000000-0000-0000-0000-000000000000
The regional service URIs are based on the explicit override values:
- Ingestion: https://custom.com:111/
- Live metrics: https://custom.com:222/
- Profiler: https://custom.com:333/
- Debugger: https://custom.com:444/

Connection string with an explicit region

InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://chinaeast2.in.applicationinsights.azure.cn/

In this example, the connection string specifies the China East 2 region.

Authorization scheme defaults to "ikey"
Instrumentation key: 00000000-0000-0000-0000-000000000000
The regional service URIs are based on the explicit override values:
- Ingestion: https://chinaeast2.in.applicationinsights.azure.cn/

Run the following command in the Azure CLI to list available regions:

az account list-locations -o table

Set a connection string

Connection strings are supported in the following SDK versions:

.NET v2.12.0
Java v2.5.1 and Java 3.0
JavaScript v2.3.0
NodeJS v1.5.0
Python v1.0.0

You can set a connection string in code or by using an environment variable or a configuration file.

Environment variable

Connection string: APPLICATIONINSIGHTS_CONNECTION_STRING

Code samples

Set the connection string in the appsettings.json file:

{
  "ApplicationInsights": {
    "ConnectionString" : "InstrumentationKey=00000000-0000-0000-0000-000000000000;EndpointSuffix=applicationinsights.azure.cn;IngestionEndpoint=https://{region}.in.applicationinsights.azure.cn/;LiveEndpoint=https://{region}.livediagnostics.monitor.azure.cn/"
    }
}

Retrieve the connection string in Program.cs when registering the ApplicationInsightsTelemetry service:

var options = new ApplicationInsightsServiceOptions { ConnectionString = app.Configuration["ApplicationInsights:ConnectionString"] };
builder.Services.AddApplicationInsightsTelemetry(options: options);

Set the property TelemetryConfiguration.ConnectionString or ApplicationInsightsServiceOptions.ConnectionString.

Explicitly set the connection string in code:

var configuration = new TelemetryConfiguration
{
    ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000;EndpointSuffix=applicationinsights.azure.cn;IngestionEndpoint=https://{region}.in.applicationinsights.azure.cn/;LiveEndpoint=https://{region}.livediagnostics.monitor.azure.cn/"
};

Set the connection string using a configuration file:

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings">
    <ConnectionString>InstrumentationKey=00000000-0000-0000-0000-000000000000;EndpointSuffix=applicationinsights.azure.cn;IngestionEndpoint=https://{region}.in.applicationinsights.azure.cn/;LiveEndpoint=https://{region}.livediagnostics.monitor.azure.cn/</ConnectionString>
</ApplicationInsights>

You can set the connection string in the applicationinsights.json configuration file:

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;EndpointSuffix=applicationinsights.azure.cn;IngestionEndpoint=https://{region}.in.applicationinsights.azure.cn/;LiveEndpoint=https://{region}.livediagnostics.monitor.azure.cn/"
}

For more information, see Connection string configuration.

JavaScript doesn't support the use of environment variables. You have two options:

To use the JavaScript (Web) SDK Loader Script, see JavaScript (Web) SDK Loader Script.

Manual setup:

import { ApplicationInsights } from '@microsoft/applicationinsights-web'

const appInsights = new ApplicationInsights({ config: {
   connectionString: 'InstrumentationKey=00000000-0000-0000-0000-000000000000;EndpointSuffix=applicationinsights.azure.cn;'
   /* ...Other Configuration Options... */
} });
appInsights.loadAppInsights();
appInsights.trackPageView();

const appInsights = require("applicationinsights");
appInsights.setup("InstrumentationKey=00000000-0000-0000-0000-000000000000;EndpointSuffix=applicationinsights.azure.cn;IngestionEndpoint=https://{region}.in.applicationinsights.azure.cn/;LiveEndpoint=https://{region}.livediagnostics.monitor.azure.cn/");
appInsights.start();

We recommend that users set the environment variable.

To explicitly set the connection string:

from opencensus.ext.azure.trace_exporter import AzureExporter
from opencensus.trace.samplers import ProbabilitySampler
from opencensus.trace.tracer import Tracer

tracer = Tracer(exporter=AzureExporter(connection_string='InstrumentationKey=00000000-0000-0000-0000-000000000000;EndpointSuffix=applicationinsights.azure.cn;IngestionEndpoint=https://{region}.in.applicationinsights.azure.cn/;LiveEndpoint=https://{region}.livediagnostics.monitor.azure.cn/'), sampler=ProbabilitySampler(1.0))

Frequently asked questions

This section provides answers to common questions.

Do new Azure regions require the use of connection strings?

New Azure regions require the use of connection strings instead of instrumentation keys. Connection string identifies the resource that you want to associate with your telemetry data. It also allows you to modify the endpoints your resource uses as a destination for your telemetry. Copy the connection string and add it to your application's code or to an environment variable.

Should I use connection strings or instrumentation keys?

We recommend that you use connection strings instead of instrumentation keys.

Next steps

Get started at runtime with:

Get started at development time with:

Connection strings

Overview

Scenario overview

Get started

Find your connection string

Schema

Max length

Key-value pairs

Syntax

Endpoint schema

Valid suffixes

Valid prefixes

Is the connection string a secret?

Connection string examples

Connection string with an endpoint suffix

Connection string with explicit endpoint overrides

Connection string with an explicit region

Set a connection string

Environment variable

Code samples

Frequently asked questions

Do new Azure regions require the use of connection strings?

Should I use connection strings or instrumentation keys?

Next steps

Additional resources