连接字符串Connection strings

概述Overview

连接字符串为 Application Insight 用户提供了单个配置设置,无需多个代理设置。Connection strings provide Application Insight users with a single configuration setting, eliminating the need for multiple proxy settings. 对于希望向监视服务发送数据的 Intranet Web 服务器、主权云或混合云环境非常有用。Highly useful for intranet web servers, sovereign or hybrid cloud environments looking to send in data to the monitoring service.

键值对为用户提供了一种简单的方式来为每个 Application Insights (AI) 服务/产品定义前缀后缀组合。The key value pairs provide an easy way for users to define a prefix suffix combination for each Application Insights (AI) service/ product.

重要

建议不要同时设置连接字符串和检测密钥。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.

方案概述Scenario overview

我们在其中将影响最大的此项设置可视化的客户方案:Customer scenarios where we visualize this having the most impact:

  • 防火墙例外或代理重定向Firewall exceptions or proxy redirects

    如果需要监视 Intranet Web 服务器,我们的早期解决方案会要求客户将各个服务终结点添加到你的配置中。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

    用户可以将数据发送到已定义的 Azure 中国区。Users can send data to a defined Azure China Region. 使用连接字符串可以定义 Intranet 服务器或混合云设置的终结点设置。Connection strings allow you to define endpoint settings for your intranet servers or hybrid cloud settings.

入门Getting started

如何查找我的连接字符串?Finding my connection string?

连接字符串显示在 Application Insights 资源的“概览”边栏选项卡上。Your connection string is displayed on the Overview blade of your Application Insights resource.

“概览”边栏选项卡上的连接字符串

架构Schema

最大长度Max length

连接的最大支持长度为 4096 个字符。The connection has a maximum supported length of 4096 characters.

键值对Key-value pairs

连接字符串由以分号分隔的键/值对表示的设置列表组成:key1=value1;key2=value2;key3=value3Connection string consists of a list of settings represented as key-value pairs separated by semicolon: key1=value1;key2=value2;key3=value3

语法Syntax

  • InstrumentationKey(例如:00000000-0000-0000-0000-000000000000)连接字符串是必填字段。InstrumentationKey (ex: 00000000-0000-0000-0000-000000000000) The connection string is a required field.
  • Authorization(例如:ikey)(此设置为可选,因为目前我们仅支持 ikey 授权。)Authorization (ex: ikey) (This setting is optional because today we only support ikey authorization.)
  • EndpointSuffix(例如:applicationinsights.azure.cn)设置终结点后缀将指示 SDK 连接到哪个 Azure 云。EndpointSuffix (ex: applicationinsights.azure.cn) Setting the endpoint suffix will instruct the SDK which Azure cloud to connect to. SDK 将为各个服务组装终结点的其余部分。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(例如:https://dc.applicationinsights.azure.comIngestionEndpoint (ex: https://dc.applicationinsights.azure.com)
    • LiveEndpoint(例如:https://live.applicationinsights.azure.comLiveEndpoint (ex: https://live.applicationinsights.azure.com)
    • ProfilerEndpoint(例如:https://profiler.applicationinsights.azure.comProfilerEndpoint (ex: https://profiler.applicationinsights.azure.com)
    • SnapshotEndpoint(例如:https://snapshot.applicationinsights.azure.comSnapshotEndpoint (ex: https://snapshot.applicationinsights.azure.com)

终结点架构Endpoint schema

<prefix>.<suffix>

  • 前缀:定义某个服务。Prefix: Defines a service.
  • 后缀:定义公共域名。Suffix: Defines the common domain name.
有效后缀Valid suffixes

下面是有效后缀的列表Here's a list of valid suffixes

  • applicationinsights.azure.cnapplicationinsights.azure.cn
  • applicationinsights.usapplicationinsights.us

另请参阅:/azure-monitor/app/custom-endpoints#regions-that-require-endpoint-modificationSee also: /azure-monitor/app/custom-endpoints#regions-that-require-endpoint-modification

有效的前缀Valid prefixes

连接字符串示例Connection string examples

最小有效连接字符串Minimal valid connection string

InstrumentationKey=00000000-0000-0000-0000-000000000000;

在此示例中,仅设置了检测密钥。In this example, only the Instrumentation Key has been set.

  • 授权方案默认为“ikey”Authorization scheme defaults to "ikey"
  • 检测密钥:00000000-0000-0000-0000-000000000000Instrumentation Key: 00000000-0000-0000-0000-000000000000
  • 区域服务 URI 基于 SDK 默认值,并将连接到公共全局 Azure:The regional service URIs are based on the SDK defaults and will connect to the public global Azure:
    • 引入:https://dc.services.visualstudio.com/Ingestion: https://dc.services.visualstudio.com/
    • 实时指标:https://rt.services.visualstudio.com/Live metrics: https://rt.services.visualstudio.com/
    • 探查器:https://agent.azureserviceprofiler.net/Profiler: https://agent.azureserviceprofiler.net/
    • 调试程序:https://agent.azureserviceprofiler.net/Debugger: https://agent.azureserviceprofiler.net/

带有终结点后缀的连接字符串Connection string with endpoint suffix

InstrumentationKey=00000000-0000-0000-0000-000000000000;EndpointSuffix=ai.contoso.com;

在此示例中,此连接字符串指定终结点后缀,SDK 将构造服务终结点。In this example, this connection string specifies the endpoint suffix and the SDK will construct service endpoints.

  • 授权方案默认为“ikey”Authorization scheme defaults to "ikey"
  • 检测密钥:00000000-0000-0000-0000-000000000000Instrumentation Key: 00000000-0000-0000-0000-000000000000
  • 区域服务 URI 基于所提供的终结点后缀:The regional service URIs are based on provided endpoint suffix:
    • 引入:https://dc.ai.contoso.comIngestion: https://dc.ai.contoso.com
    • 实时指标:https://live.ai.contoso.comLive metrics: https://live.ai.contoso.com
    • 探查器:https://profiler.ai.contoso.comProfiler: https://profiler.ai.contoso.com
    • 调试程序:https://snapshot.ai.contoso.comDebugger: 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, this connection string specifies explicit overrides for every service. SDK 将使用所提供的确切终结点而不进行修改。The SDK will use the exact endpoints provided without modification.

  • 授权方案默认为“ikey”Authorization scheme defaults to "ikey"
  • 检测密钥:00000000-0000-0000-0000-000000000000Instrumentation Key: 00000000-0000-0000-0000-000000000000
  • 区域服务 URI 基于显式重写值:The regional service URIs are based on the explicit override values:
    • 引入:https://custom.com:111/Ingestion: https://custom.com:111/
    • 实时指标:https://custom.com:222/Live metrics: https://custom.com:222/
    • 探查器:https://custom.com:333/Profiler: https://custom.com:333/
    • 调试程序:https://custom.com:444/Debugger: https://custom.com:444/

如何设置连接字符串How to set a connection string

以下 SDK 版本支持连接字符串:Connection Strings are supported in the following SDK versions:

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

可以通过代码、环境变量或配置文件设置连接字符串。A connection string can be set by either in code, environment variable, or configuration file.

环境变量Environment variable

  • 连接字符串: APPLICATIONINSIGHTS_CONNECTION_STRINGConnection String: APPLICATIONINSIGHTS_CONNECTION_STRING

TelemetryConfiguration.ConnectionString: https://github.com/microsoft/ApplicationInsights-dotnet/blob/add45ceed35a817dc7202ec07d3df1672d1f610d/BASE/src/Microsoft.ApplicationInsights/Extensibility/TelemetryConfiguration.cs#L271-L274TelemetryConfiguration.ConnectionString: https://github.com/microsoft/ApplicationInsights-dotnet/blob/add45ceed35a817dc7202ec07d3df1672d1f610d/BASE/src/Microsoft.ApplicationInsights/Extensibility/TelemetryConfiguration.cs#L271-L274

.NET 显式设置:.NET Explicitly Set:

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

.NET 配置文件:.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 显式设置: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:NetCore config.json:

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