Connection strings

This article shows how to use connection strings.

Overview

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.

Don't use a connection string and instrumentation key simultaneously. Whichever was set last will take precedence.

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 Azure Monitor FAQ. 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 Azure Government 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.

Screenshot that shows the Application Insights overview and connection string.

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). The connection string 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 will instruct the SDK on which Azure cloud to connect to. The SDK will assemble 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.com)
    • LiveEndpoint (for example, https://live.applicationinsights.azure.com)
    • ProfilerEndpoint (for example, https://profiler.monitor.azure.com)
    • SnapshotEndpoint (for example, https://snapshot.monitor.azure.com)

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

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. It's not considered a security token or key. If you want to protect your AI resource from misuse, the ingestion endpoint provides authenticated telemetry ingestion options based on Azure Active Directory (Azure AD).

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 Azure AD-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=ai.contoso.com;

In this example, the connection string specifies the endpoint suffix and the SDK will construct 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.ai.contoso.com
    • Live metrics: https://live.ai.contoso.com
    • Profiler: https://profiler.ai.contoso.com
    • Debugger: https://snapshot.ai.contoso.com

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 will use 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://southcentralus.in.applicationinsights.azure.com/

In this example, the connection string specifies the South Central US 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://southcentralus.in.applicationinsights.azure.com/

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 property TelemetryConfiguration.ConnectionString or ApplicationInsightsServiceOptions.ConnectionString.

.NET explicitly set:

var configuration = new TelemetryConfiguration
{
    ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000;"
};

.NET config file:

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings">
    <ConnectionString>InstrumentationKey=00000000-0000-0000-0000-000000000000</ConnectionString>
</ApplicationInsights>

.NET Core explicitly set:

public void ConfigureServices(IServiceCollection services)
{
    var options = new ApplicationInsightsServiceOptions { ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000;" };
    services.AddApplicationInsightsTelemetry(options: options);
}

.NET Core config.json:

{
  "ApplicationInsights": {
    "ConnectionString" : "InstrumentationKey=00000000-0000-0000-0000-000000000000;"
    }
  }

Next steps

Get started at runtime with:

Get started at development time with: