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.

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

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

.NET 5.0+

1. Set the instrumentation key in the appsettings.json file:

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

2. Retrieve the instrumentation key in Program.cs when registering the ApplicationInsightsTelemetry service:

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

Note

When deploying applications to Azure in production scenarios, consider placing instrumentation keys or other configuration secrets in secure locations such as App Service configuration settings or Azure Key Vault. Avoid including secrets in your application code or checking them into source control where they might be exposed or misused. The preceding code example will also work if the instrumentation key is stored in App Service configuration settings. Learn more about configuring App Service settings.

.NET Framework

Set the property TelemetryConfiguration.ConnectionString or ApplicationInsightsServiceOptions.ConnectionString.

Explicitly set the instrumentation key in code:

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

Set the instrumentation key 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</ConnectionString>
</ApplicationInsights>

Java

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

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
}

For more information, see Connection string configuration.

JavaScript

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

• To use the SDK Loader Script, see SDK Loader Script.
• Manual setup:

  import { ApplicationInsights } from '@microsoft/applicationinsights-web'
  
  const appInsights = new ApplicationInsights({ config: {
     connectionString: 'InstrumentationKey=00000000-0000-0000-0000-000000000000;'
     /* ...Other Configuration Options... */
  } });
  appInsights.loadAppInsights();
  appInsights.trackPageView();
  

Node.js

const appInsights = require("applicationinsights");
appInsights.setup("InstrumentationKey=00000000-0000-0000-0000-000000000000;");
appInsights.start();

Python

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'), sampler=ProbabilitySampler(1.0))

Next steps

Get started at runtime with:

• Azure VM and Azure Virtual Machine Scale Sets IIS-hosted apps
• IIS server
• Web Apps feature of Azure App Service

Get started at development time with:

• ASP.NET
• ASP.NET Core
• Java
• Node.js
• Python