使用英语阅读

通过

为本地服务器部署 Azure Monitor Application Insights 代理

  • 项目

Application Insights 代理（以前称为状态监视器 V2）是发布到 PowerShell 库的 PowerShell 模块。 它将替换状态监视器。 遥测数据将发送到 Azure 门户，你可以在其中监视应用。

有关支持的自动检测方案的完整列表，请参阅支持的环境、语言和资源提供程序。

备注

本模块当前支持通过 IIS 托管的 ASP.NET 和 ASP.NET Core web 应用的无代码检测。 使用 SDK 检测 Java 和 Node.js 应用程序。

Application Insights 代理位于 PowerShell 库中。

PowerShell 库图标。

说明

  • 若要开始使用简洁的代码示例，请参阅“入门”选项卡。
  • 若要深入了解如何开始使用，请参阅“详细说明”选项卡。
  • 有关 PowerShell API 参考，请参阅“API 参考”选项卡。
  • 有关发行说明更新，请参阅“发行说明”选项卡。

此选项卡介绍如何载入到 PowerShell 库和下载 ApplicationMonitor 模块。 包含了开始使用所需的最常见参数。 我们还提供手动下载说明，以防你无法访问 Internet。

获取连接字符串

若要开始，需要连接字符串。 有关详细信息，请参阅连接字符串。

备注

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

以管理员身份使用提升的执行策略运行 PowerShell

以管理员身份运行

PowerShell 需要拥有管理员级别的权限才能对计算机进行更改。

执行策略

  • 说明：默认禁用 PowerShell 脚本的运行。 我们建议仅允许在当前范围运行 RemoteSigned 脚本。
  • 参考：关于执行策略和 Set-ExecutionPolicy。
  • 命令：Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process。
  • 可选参数：
    • -Force。 跳过确认提示。

示例错误

Install-Module : The 'Install-Module' command was found in the module 'PowerShellGet', but the module could not be
loaded. For more information, run 'Import-Module PowerShellGet'.

Import-Module : File C:\Program Files\WindowsPowerShell\Modules\PackageManagement\1.3.1\PackageManagement.psm1 cannot
be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at https://go.microsoft.com/fwlink/?LinkID=135170.

PowerShell 先决条件

运行 $PSVersionTable 命令，审核 PowerShell 的实例。 该命令生成以下输出：

Name                           Value
----                           -----
PSVersion                      5.1.17763.316
PSEdition                      Desktop
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}
BuildVersion                   10.0.17763.316
CLRVersion                     4.0.30319.42000
WSManStackVersion              3.0
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1

这些说明是在运行 Windows 10 和以下版本的计算机上编写和测试的。

这些步骤准备服务器以从 PowerShell 库下载模块。

备注

Windows 10、Windows Server 2016 和 PowerShell 6+ 支持 PowerShell 库。 有关早期版本的信息，请参阅安装 PowerShellGet。

  1. 以管理员身份使用提升的执行策略运行 PowerShell。

  2. 安装 NuGet 包提供程序。

    • 说明：需要使用此提供程序才能与基于 NuGet 的存储库（例如 PowerShell 库）交互。
    • 参考：Install-PackageProvider。
    • 命令：Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201。
    • 可选参数：
      • -Proxy。 指定请求的代理服务器。
      • -Force。 跳过确认提示。

    如果未设置 NuGet，则会看到此提示：

    NuGet provider is required to continue
PowerShellGet requires NuGet provider version '2.8.5.201' or newer to interact with NuGet-based repositories.
The NuGet provider must be available in 'C:\Program Files\PackageManagement\ProviderAssemblies' or
'C:\Users\t\AppData\Local\PackageManagement\ProviderAssemblies'. You can also install the NuGet provider by running
'Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force'. Do you want PowerShellGet to install and import
the NuGet provider now?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"):

  3. 将 PowerShell 库配置为受信任的存储库。

    • 说明：默认情况下，PowerShell 库是不受信任的存储库。
    • 参考：Set-PSRepository。
    • 命令：Set-PSRepository -Name "PSGallery" -InstallationPolicy Trusted。
    • 可选参数：
      • -Proxy。 指定请求的代理服务器。

    如果 PowerShell 库不受信任，则会看到此提示：

    Untrusted repository
You are installing the modules from an untrusted repository.
If you trust this repository, change its InstallationPolicy value
by running the Set-PSRepository cmdlet. Are you sure you want to
install the modules from 'PSGallery'?
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"):

    可以通过运行 Get-PSRepository 命令来确认此更改并审核所有 PSRepositories。

  4. 安装最新版本的 PowerShellGet。

    • 说明：此模块包含用于从 PowerShell 库中获取其他模块的工具。 Windows 10 和 Windows Server 随附了版本 1.0.0.1。 需要 1.6.0 或更高版本。 若要确定安装了哪个版本，请运行 Get-Command -Module PowerShellGet 命令。
    • 参考：安装 PowerShellGet。
    • 命令：Install-Module -Name PowerShellGet。
    • 可选参数：
      • -Proxy。 指定请求的代理服务器。
      • -Force。 忽略“已安装”警告并安装最新版本。

    如果使用的不是最新 PowerShellGet 版本，则会看到此错误：

    Install-Module : A parameter cannot be found that matches parameter name 'AllowPrerelease'.
At line:1 char:20
Install-Module abc -AllowPrerelease
               ~~~~~~~~~~~~~~~~
CategoryInfo          : InvalidArgument: (:) [Install-Module], ParameterBindingException
FullyQualifiedErrorId : NamedParameterNotFound,Install-Module

  5. 重启 PowerShell。 无法在当前会话中加载新版本。 新 PowerShell 会话会加载最新版 PowerShellGet。

这些步骤将从 PowerShell 库下载 Az.ApplicationMonitor 模块。

  1. 确保满足 PowerShell 库的所有先决条件。
  2. 以管理员身份使用提升的执行策略运行 PowerShell。
  3. 安装 Az.ApplicationMonitor 模块。
    • 参考：Install-Module。
    • 命令：Install-Module -Name Az.ApplicationMonitor。
    • 可选参数：
      • -Proxy。 指定请求的代理服务器。
      • -AllowPrerelease。 允许安装 alpha 和 beta 版本。
      • -AcceptLicense。 跳过“接受许可证”提示
      • -Force。 忽略“不受信任的存储库”警告。

手动下载并安装模块（脱机选项）

如果出于任何原因无法连接到 PowerShell 模块，可以手动下载并安装 Az.ApplicationMonitor 模块。

手动下载最新的 nupkg 文件

  1. 转到 https://www.powershellgallery.com/packages/Az.ApplicationMonitor 。
  2. 在“版本历史记录”表中选择文件的最新版本。
  3. 在“安装选项”下选择“手动下载”。

选项 1：安装到 PowerShell 模块目录中

将手动下载的 PowerShell 模块安装到 PowerShell 目录中，使之可被 PowerShell 会话发现。 有关详细信息，请参阅安装 PowerShell 模块。

使用 Expand-Archive (v1.0.1.0) 将 nupkg 作为 zip 文件解压缩

  • 说明：基础版本的 Microsoft.PowerShell.Archive (v1.0.1.0) 无法解压缩 nupkg 文件。 使用 .zip 扩展名重命名文件。

  • 参考：Expand-Archive。

  • 命令：

    $pathToNupkg = "C:\az.applicationmonitor.0.3.0-alpha.nupkg"
$pathToZip = ([io.path]::ChangeExtension($pathToNupkg, "zip"))
$pathToNupkg | rename-item -newname $pathToZip
$pathInstalledModule = "$Env:ProgramFiles\WindowsPowerShell\Modules\az.applicationmonitor"
Expand-Archive -LiteralPath $pathToZip -DestinationPath $pathInstalledModule
使用 Expand-Archive (v1.1.0.0) 解压缩 nupkg

  • 说明：使用最新版本的 Expand-Archive 解压缩 nupkg 文件但不更改扩展名。

  • 参考：Expand-Archive 和 Microsoft.PowerShell.Archive。

  • 命令：

    $pathToNupkg = "C:\az.applicationmonitor.0.2.1-alpha.nupkg"
$pathInstalledModule = "$Env:ProgramFiles\WindowsPowerShell\Modules\az.applicationmonitor"
Expand-Archive -LiteralPath $pathToNupkg -DestinationPath $pathInstalledModule

选项 2：手动解压缩并导入 nupkg

将手动下载的 PowerShell 模块安装到 PowerShell 目录中，使之可被 PowerShell 会话发现。 有关详细信息，请参阅安装 PowerShell 模块。

若要将模块安装到任何其他目录中，请使用 Import-Module 手动导入模块。

重要

DLL 会通过相对路径进行安装。 请将此包的内容存储到所需的运行时目录中，并确认访问权限允许读取但不允许写入。

  1. 将扩展名更改为“.zip”，并将包的内容解压缩到所需的安装目录中。
  2. 找到 Az.ApplicationMonitor.psd1 的文件路径。
  3. 以管理员身份使用提升的执行策略运行 PowerShell。
  4. 通过 Import-Module Az.ApplicationMonitor.psd1 命令加载模块。

通过代理路由流量

监视专用 Intranet 中的计算机时，需要通过代理路由 HTTP 流量。

用于从 PowerShell 库下载并安装 Az.ApplicationMonitor 的 PowerShell 命令支持 -Proxy 参数。 编写安装脚本时，请查看上述说明。

Application Insights SDK 需要将应用的遥测数据发送给 Microsoft。 建议在 web.config 文件中配置应用的代理设置。 有关详细信息，请参阅如何实现实现代理直通？。

启用监视

使用 Enable-ApplicationInsightsMonitoring 命令以启用监视。

有关如何使用此 cmdlet 的详细说明，请参阅 API 参考。

常见问题

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

Application Insights 代理是否支持代理安装？

是的。 可以通过多种方式下载 Application Insights 代理：

  • 如果计算机可以访问 Internet，则可以使用 -Proxy 参数登录到 PowerShell 库。
  • 还可以手动下载此模块，并将其安装到计算机上或直接使用它。

上述每个选项都在详细说明中进行了说明。

Application Insights 代理是否支持 ASP.NET Core 应用程序？

是的。 在 Application Insights Agent 2.0.0 及更高版本中，支持在 IIS 中托管的 ASP.NET Core 应用程序。

如何验证启用是否成功？

如何实现代理直通？

若要实现代理直通，请配置计算机级代理或应用程序级代理。 请参阅 DefaultProxy。

示例 Web.config：

<system.net>
    <defaultProxy>
    <proxy proxyaddress="http://xx.xx.xx.xx:yyyy" bypassonlocal="true"/>
    </defaultProxy>
</system.net>

故障排除

请参阅专用疑难解答文章。

测试应用程序主机与引入服务之间的连接性

Application Insights SDK 和代理发送遥测，将其作为 REST 调用引入到引入终结点。 可以使用原始 REST 客户端通过 PowerShell 或使用 curl 命令，测试从 Web 服务器或应用程序主机计算机到引入服务终结点的连接。 请参阅排查 Azure Monitor Application Insights 中缺失应用程序遥测的问题。

后续步骤

查看遥测：

添加更多遥测：

使用 Application Insights 代理执行更多操作：