Application Insights 中的连接字符串

项目
11/11/2024

连接字符串指定检测的应用程序应向哪个 Application Insights 资源发送遥测数据。连接字符串由多个设置组成，每个设置都表示为键值对，并用分号分隔。此合并的配置方法消除了对多个代理设置的需求，从而简化了设置过程。

重要

连接字符串包含 ikey，后者是引入服务用于将遥测与特定 Application Insights 资源关联的唯一标识符。 Ikey 唯一标识符不是安全令牌或安全密钥，因此不被视为机密。

如果要保护 Application Insights 资源不被滥用，请使用引入终结点，它提供基于 Microsoft Entra ID 的、经身份验证的遥测引入选项。

注意

对检测密钥引入的支持将于 2025 年 3 月 31 日结束。检测密钥引入功能将会继续工作，但我们将不再为该功能提供更新或支持。转换为连接字符串，以利用新功能。

连接字符串功能

可靠性：连接字符串通过删除全局引入终结点上的依赖项提高遥测引入的可靠性。
安全性：连接字符串允许通过使用 Application Insights 的 Microsoft Entra 身份验证引入经过身份验证的遥测。
自定义终结点（主权或混合云环境）：终结点设置允许将数据发送到特定的 Azure 政府区域。（请参阅示例。）
隐私（区域终结点）：连接字符串通过将数据发送到区域终结点来解决隐私问题，从而确保数据不会离开某一地理区域。

查找连接字符串

连接字符串显示在 Application Insights 资源的“概述”部分。

架构

以下部分对架构元素进行了说明。

最大长度

连接的受支持的最大长度为 4,096 个字符。

键值对

连接字符串包含一系列以键值对形式表示的设置（以分号分隔）：key1=value1;key2=value2;key3=value3

语法

InstrumentationKey（例如 00000000-0000-0000-0000-000000000000）。 InstrumentationKey 是必填字段。
Authorization（例如 ikey）。此设置为可选，因为目前我们仅支持 ikey 授权。
EndpointSuffix（例如 applicationinsights.azure.cn）。设置终结点后缀是告知 SDK 连接到哪个 Azure 云。 SDK 会为各个服务组装终结点的其余部分。
显式终结点。任何服务均可在连接字符串中显式重写：
- IngestionEndpoint（例如 https://dc.applicationinsights.azure.cn）
- LiveEndpoint（例如 https://live.applicationinsights.azure.cn）
- ProfilerEndpoint（例如 https://profiler.monitor.azure.cn）
- SnapshotEndpoint（例如 https://snapshot.monitor.azure.cn）

终结点架构

<prefix>.<suffix>

前缀：定义某个服务。
后缀：定义公共域名。

有效后缀

applicationinsights.azure.cn
applicationinsights.us

有关详细信息，请参阅需要修改终结点的区域。

有效的前缀

遥测引入：dc
实时指标：live
探查器：profiler
快照：snapshot

连接字符串示例

下面是连接字符串的一些示例。

带有终结点后缀的连接字符串

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

在此示例中，连接字符串指定世纪互联运营的 Microsoft Azure 中的终结点后缀，SDK 构建服务终结点：

授权方案默认为“ikey”
检测密钥：00000000-0000-0000-0000-000000000000
区域服务 URI 基于所提供的终结点后缀：
- 引入：https://dc.applicationinsights.azure.cn
- 实时指标：https://live.applicationinsights.azure.cn
- 探查器：https://profiler.applicationinsights.azure.cn
- 调试程序：https://snapshot.applicationinsights.azure.cn

带有显式终结点重写的连接字符串

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/;

在此示例中，连接字符串指定每个服务的显式重写。 SDK 使用所提供的确切终结点而不进行修改：

授权方案默认为“ikey”
检测密钥：00000000-0000-0000-0000-000000000000
区域服务 URI 基于显式重写值：
- 引入：https://custom.com:111/
- 实时指标：https://custom.com:222/
- 探查器：https://custom.com:333/
- 调试程序：https://custom.com:444/

带有显式区域的连接字符串

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

在此示例中，连接字符串指定“中国东部 2”区域：

授权方案默认为“ikey”
检测密钥：00000000-0000-0000-0000-000000000000
区域服务 URI 基于显式重写值：
- 引入：https://chinaeast2.in.applicationinsights.azure.cn/

在 Azure CLI 中运行以下命令，列出可用区域：

az account list-locations -o table

设置连接字符串

所有 OpenTelemetry 产品/服务以及以下 SDK 版本和更高版本都支持连接字符串：

.NET v2.12.0
JavaScript v2.3.0
NodeJS v1.5.0
Python v1.0.0

可以通过代码、环境变量或配置文件设置连接字符串。

环境变量

连接字符串：APPLICATIONINSIGHTS_CONNECTION_STRING

代码示例

语言	经典 API	OpenTelemetry
ASP.NET Core	Application Insights SDK	AzMon OTel 分发版
.NET Framework	Application Insights SDK	AzMon 导出程序
Java	空值	Java 代理
JavaScript	JavaScript (Web) SDK 加载程序脚本	空值
Node.js	Application Insights SDK	AzMon OTel 分发版
Python	OpenCensus Python SDK	AzMon OTel 分发版

常见问题解答

本部分提供常见问题的解答。

新的 Azure 区域是否需要使用连接字符串？

新的 Azure 区域要求使用连接字符串而不是检测密钥。连接字符串会标识出要与遥测数据相关联的资源。它还允许你修改可供你的资源将其用作遥测目标的终结点。复制连接字符串，并将其添加到应用程序的代码或添加到环境变量中。

是否应该使用连接字符串或检测密钥？

建议使用连接字符串，而不是检测密钥。

后续步骤

在运行时开始使用：

在开发时开始使用：

通过