| title | description | ms.topic | author | ms.author | ms.date | ms.custom | ms.reviewer |
|---|---|---|---|---|---|---|---|
Connection strings in Azure Application Insights | Microsoft Docs |
How to use connection strings. |
conceptual |
timothymothra |
tilee |
01/17/2020 |
devx-track-js, devx-track-csharp |
mbullwin |
Connection strings provide Application Insight users with a single configuration setting, eliminating the need for multiple proxy settings. Highly useful for intranet web servers, sovereign or hybrid cloud environments looking to send in data to the monitoring service.
The key value pairs provide an easy way for users to define a prefix suffix combination for each Application Insights (AI) service/ product.
Important
We don't recommend setting both Connection String and Instrumentation key. In the event that a user does set both, whichever was set last will take precedence.
Tip
We recommend the use of connection strings over instrumentation keys.
Customer scenarios where we visualize this having the most impact:
-
Firewall exceptions or proxy redirects
In cases where monitoring for intranet web server is required, our earlier solution asked customers to add individual service endpoints to your configuration. For more information, see here. 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. Connection strings allow you to define endpoint settings for your intranet servers or hybrid cloud settings.
Your connection string is displayed on the Overview blade of your Application Insights resource.
The connection has a maximum supported length of 4096 characters.
Connection string consists of a list of settings represented as key-value pairs separated by semicolon:
key1=value1;key2=value2;key3=value3
InstrumentationKey(ex: 00000000-0000-0000-0000-000000000000) The connection string is a required field.Authorization(ex: ikey) (This setting is optional because today we only support ikey authorization.)EndpointSuffix(ex: applicationinsights.azure.cn) Setting the endpoint suffix will instruct the SDK 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(ex:https://dc.applicationinsights.azure.com)LiveEndpoint(ex:https://live.applicationinsights.azure.com)ProfilerEndpoint(ex:https://profiler.monitor.azure.com)SnapshotEndpoint(ex:https://snapshot.monitor.azure.com)
<prefix>.<suffix>
- Prefix: Defines a service.
- Suffix: Defines the common domain name.
Here's a list of valid suffixes
- applicationinsights.azure.cn
- applicationinsights.us
See also: Regions that require endpoint modification
- Telemetry Ingestion:
dc - Live Metrics:
live - Profiler:
profiler - Snapshot:
snapshot
InstrumentationKey=00000000-0000-0000-0000-000000000000;
In this example, only the Instrumentation Key has been set.
- Authorization scheme defaults to "ikey"
- Instrumentation Key: 00000000-0000-0000-0000-000000000000
- The regional service URIs are based on the SDK defaults and will connect to the public global Azure:
- Ingestion:
https://dc.services.visualstudio.com/ - Live metrics:
https://rt.services.visualstudio.com/ - Profiler:
https://profiler.monitor.azure.com/ - Debugger:
https://snapshot.monitor.azure.com/
- Ingestion:
InstrumentationKey=00000000-0000-0000-0000-000000000000;EndpointSuffix=ai.contoso.com;
In this example, this 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 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
- Ingestion:
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, this 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/
- Ingestion:
Connection Strings are supported in the following SDK versions:
- .NET and .NET Core v2.12.0
- Java v2.5.1 and Java 3.0
- JavaScript v2.3.0
- NodeJS v1.5.0
- Python v1.0.0
A connection string can be set by either in code, environment variable, or configuration file.
- Connection String:
APPLICATIONINSIGHTS_CONNECTION_STRING
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>NetCore Explicitly Set:
public void ConfigureServices(IServiceCollection services)
{
var options = new ApplicationInsightsServiceOptions { ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000;" };
services.AddApplicationInsightsTelemetry(options: options);
}NetCore config.json:
{
"ApplicationInsights": {
"ConnectionString" : "InstrumentationKey=00000000-0000-0000-0000-000000000000;"
}
}You can set the connection string in the applicationinsights.json configuration file:
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
}See connection string configuration for more details.
For Application Insights Java 2.x, you can set the connection string in the ApplicationInsights.xml 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>Important: JavaScript doesn't support the use of Environment Variables.
Using the snippet:
The current Snippet (listed below) is version "5", the version is encoded in the snippet as sv:"#" and the current version is also available on GitHub.
<script type="text/javascript">
!function(T,l,y){var S=T.location,k="script",D="instrumentationKey",C="ingestionendpoint",I="disableExceptionTracking",E="ai.device.",b="toLowerCase",w="crossOrigin",N="POST",e="appInsightsSDK",t=y.name||"appInsights";(y.name||T[e])&&(T[e]=t);var n=T[t]||function(d){var g=!1,f=!1,m={initialize:!0,queue:[],sv:"5",version:2,config:d};function v(e,t){var n={},a="Browser";return n[E+"id"]=a[b](),n[E+"type"]=a,n["ai.operation.name"]=S&&S.pathname||"_unknown_",n["ai.internal.sdkVersion"]="javascript:snippet_"+(m.sv||m.version),{time:function(){var e=new Date;function t(e){var t=""+e;return 1===t.length&&(t="0"+t),t}return e.getUTCFullYear()+"-"+t(1+e.getUTCMonth())+"-"+t(e.getUTCDate())+"T"+t(e.getUTCHours())+":"+t(e.getUTCMinutes())+":"+t(e.getUTCSeconds())+"."+((e.getUTCMilliseconds()/1e3).toFixed(3)+"").slice(2,5)+"Z"}(),iKey:e,name:"Microsoft.ApplicationInsights."+e.replace(/-/g,"")+"."+t,sampleRate:100,tags:n,data:{baseData:{ver:2}}}}var h=d.url||y.src;if(h){function a(e){var t,n,a,i,r,o,s,c,u,p,l;g=!0,m.queue=[],f||(f=!0,t=h,s=function(){var e={},t=d.connectionString;if(t)for(var n=t.split(";"),a=0;a<n.length;a++){var i=n[a].split("=");2===i.length&&(e[i[0][b]()]=i[1])}if(!e[C]){var r=e.endpointsuffix,o=r?e.location:null;e[C]="https://"+(o?o+".":"")+"dc."+(r||"services.visualstudio.com")}return e}(),c=s[D]||d[D]||"",u=s[C],p=u?u+"/v2/track":d.endpointUrl,(l=[]).push((n="SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details)",a=t,i=p,(o=(r=v(c,"Exception")).data).baseType="ExceptionData",o.baseData.exceptions=[{typeName:"SDKLoadFailed",message:n.replace(/\./g,"-"),hasFullStack:!1,stack:n+"\nSnippet failed to load ["+a+"] -- Telemetry is disabled\nHelp Link: https://go.microsoft.com/fwlink/?linkid=2128109\nHost: "+(S&&S.pathname||"_unknown_")+"\nEndpoint: "+i,parsedStack:[]}],r)),l.push(function(e,t,n,a){var i=v(c,"Message"),r=i.data;r.baseType="MessageData";var o=r.baseData;return o.message='AI (Internal): 99 message:"'+("SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details) ("+n+")").replace(/\"/g,"")+'"',o.properties={endpoint:a},i}(0,0,t,p)),function(e,t){if(JSON){var n=T.fetch;if(n&&!y.useXhr)n(t,{method:N,body:JSON.stringify(e),mode:"cors"});else if(XMLHttpRequest){var a=new XMLHttpRequest;a.open(N,t),a.setRequestHeader("Content-type","application/json"),a.send(JSON.stringify(e))}}}(l,p))}function i(e,t){f||setTimeout(function(){!t&&m.core||a()},500)}var e=function(){var n=l.createElement(k);n.src=h;var e=y[w];return!e&&""!==e||"undefined"==n[w]||(n[w]=e),n.onload=i,n.onerror=a,n.onreadystatechange=function(e,t){"loaded"!==n.readyState&&"complete"!==n.readyState||i(0,t)},n}();y.ld<0?l.getElementsByTagName("head")[0].appendChild(e):setTimeout(function(){l.getElementsByTagName(k)[0].parentNode.appendChild(e)},y.ld||0)}try{m.cookie=l.cookie}catch(p){}function t(e){for(;e.length;)!function(t){m[t]=function(){var e=arguments;g||m.queue.push(function(){m[t].apply(m,e)})}}(e.pop())}var n="track",r="TrackPage",o="TrackEvent";t([n+"Event",n+"PageView",n+"Exception",n+"Trace",n+"DependencyData",n+"Metric",n+"PageViewPerformance","start"+r,"stop"+r,"start"+o,"stop"+o,"addTelemetryInitializer","setAuthenticatedUserContext","clearAuthenticatedUserContext","flush"]),m.SeverityLevel={Verbose:0,Information:1,Warning:2,Error:3,Critical:4};var s=(d.extensionConfig||{}).ApplicationInsightsAnalytics||{};if(!0!==d[I]&&!0!==s[I]){var c="onerror";t(["_"+c]);var u=T[c];T[c]=function(e,t,n,a,i){var r=u&&u(e,t,n,a,i);return!0!==r&&m["_"+c]({message:e,url:t,lineNumber:n,columnNumber:a,error:i}),r},d.autoExceptionInstrumented=!0}return m}(y.cfg);function a(){y.onInit&&y.onInit(n)}(T[t]=n).queue&&0===n.queue.length?(n.queue.push(a),n.trackPageView({})):a()}(window,document,{
src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js", // The SDK URL Source
// name: "appInsights", // Global SDK Instance name defaults to "appInsights" when not supplied
// ld: 0, // Defines the load delay (in ms) before attempting to load the sdk. -1 = block page load and add to head. (default) = 0ms load after timeout,
// useXhr: 1, // Use XHR instead of fetch to report failures (if available),
crossOrigin: "anonymous", // When supplied this will add the provided value as the cross origin attribute on the script tag
// onInit: null, // Once the application insights instance has loaded and initialized this callback function will be called with 1 argument -- the sdk instance (DO NOT ADD anything to the sdk.queue -- As they won't get called)
cfg: { // Application Insights Configuration
connectionString:"InstrumentationKey=00000000-0000-0000-0000-000000000000;"
}});
</script>Note
For readability and to reduce possible JavaScript errors, all of the possible configuration options are listed on a new line in snippet code above, if you don't want to change the value of a commented line it can be removed.
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();const appInsights = require("applicationinsights");
appInsights.setup("InstrumentationKey=00000000-0000-0000-0000-000000000000;");
appInsights.start();We recommend 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))Get started at runtime with:
Get started at development time with: