Azure Monitor Application Insights 代理 API 参考Azure Monitor Application Insights Agent API Reference

本文介绍属于 Az.ApplicationMonitor PowerShell 模块的 cmdlet。This article describes a cmdlet that's a member of the Az.ApplicationMonitor PowerShell module.

备注

  • 若要开始,需要一个检测密钥。To get started, you need an instrumentation key. 有关详细信息,请参阅创建资源For more information, see Create a resource.
  • 此 cmdlet 要求查看并接受我们的许可条款和隐私声明。This cmdlet requires that you review and accept our license and privacy statement.

重要

此 cmdlet 要求使用管理员权限和提升的执行策略建立 PowerShell 会话。This cmdlet requires a PowerShell session with Admin permissions and an elevated execution policy. 有关详细信息,请参阅以管理员身份使用提升的执行策略运行 PowerShellFor more information, see Run PowerShell as administrator with an elevated execution policy.

  • 此 cmdlet 要求查看并接受我们的许可条款和隐私声明。This cmdlet requires that you review and accept our license and privacy statement.
  • 检测引擎会增加额外的开销,默认情况下处于关闭状态。The instrumentation engine adds additional overhead and is off by default.

Enable-InstrumentationEngineEnable-InstrumentationEngine

通过设置一些注册表项启用检测引擎。Enables the instrumentation engine by setting some registry keys. 重启 IIS 以使这些更改生效。Restart IIS for the changes to take effect.

检测引擎可以补充 .NET SDK 收集的数据。The instrumentation engine can supplement data collected by the .NET SDKs. 它收集描述托管进程执行的事件和消息。It collects events and messages that describe the execution of a managed process. 这些事件和消息包括依赖项结果代码、HTTP 谓词和 SQL 命令文本These events and messages include dependency result codes, HTTP verbs, and SQL command text.

在以下情况下启用检测引擎:Enable the instrumentation engine if:

  • 已使用 Enable cmdlet 启用了监视,但未启用检测引擎。You've already enabled monitoring with the Enable cmdlet but didn't enable the instrumentation engine.
  • 已使用 .NET SDK 手动检测应用,并希望收集其他遥测数据。You've manually instrumented your app with the .NET SDKs and want to collect additional telemetry.

示例Examples

PS C:\> Enable-InstrumentationEngine

parametersParameters

-AcceptLicense-AcceptLicense

可选。Optional. 使用此开关可在无外设安装中接受许可条款和隐私声明。Use this switch to accept the license and privacy statement in headless installations.

-Verbose-Verbose

通用参数。Common parameter. 使用此开关可输出详细日志。Use this switch to output detailed logs.

输出Output

成功启用检测引擎的示例输出Example output from successfully enabling the instrumentation engine
Configuring IIS Environment for instrumentation engine...
Configuring registry for instrumentation engine...

Enable-ApplicationInsightsMonitoringEnable-ApplicationInsightsMonitoring

对目标计算机上的 IIS 应用启用无代码附加监视。Enables codeless attach monitoring of IIS apps on a target computer.

此 cmdlet 将修改 IIS applicationHost.config 并设置一些注册表项。This cmdlet will modify the IIS applicationHost.config and set some registry keys. 它还将创建 applicationinsights.ikey.config 文件,该文件定义每个应用使用的检测密钥。It will also create an applicationinsights.ikey.config file, which defines the instrumentation key used by each app. IIS 在启动时会加载 RedfieldModule,从而在应用程序启动时将 Application Insights SDK 注入到应用程序中。IIS will load the RedfieldModule on startup, which will inject the Application Insights SDK into applications as the applications start. 重启 IIS 以使更改生效。Restart IIS for your changes to take effect.

启用监视后,我们建议你使用实时指标快速检查应用是否正在向我们发送遥测数据。After you enable monitoring, we recommend that you use Live Metrics to quickly check if your app is sending us telemetry.

示例Examples

使用单个检测密钥的示例Example with a single instrumentation key

在此示例中,将为当前计算机上的所有应用分配一个检测密钥。In this example, all apps on the current computer are assigned a single instrumentation key.

PS C:\> Enable-ApplicationInsightsMonitoring -InstrumentationKey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

使用检测密钥映射的示例Example with an instrumentation key map

在本示例中:In this example:

  • MachineFilter 使用 '.*' 通配符匹配当前计算机。MachineFilter matches the current computer by using the '.*' wildcard.
  • AppFilter='WebAppExclude' 提供 null 检测密钥。AppFilter='WebAppExclude' provides a null instrumentation key. 不会检测指定的应用。The specified app won't be instrumented.
  • AppFilter='WebAppOne' 为指定的应用分配唯一的检测密钥。AppFilter='WebAppOne' assigns the specified app a unique instrumentation key.
  • AppFilter='WebAppTwo' 为指定的应用分配唯一的检测密钥。AppFilter='WebAppTwo' assigns the specified app a unique instrumentation key.
  • 最后,AppFilter 还使用 '.*' 通配符来匹配按以前规则不匹配的所有 Web 应用,并分配一个默认的检测密钥。Finally, AppFilter also uses the '.*' wildcard to match all web apps that aren't matched by the earlier rules and assign a default instrumentation key.
  • 添加空格以提高可读性。Spaces are added for readability.
PS C:\> Enable-ApplicationInsightsMonitoring -InstrumentationKeyMap 
    @(@{MachineFilter='.*';AppFilter='WebAppExclude'},
      @{MachineFilter='.*';AppFilter='WebAppOne';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx1'}},
      @{MachineFilter='.*';AppFilter='WebAppTwo';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx2'}},
      @{MachineFilter='.*';AppFilter='.*';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxdefault'}})

parametersParameters

-InstrumentationKey-InstrumentationKey

必需。Required. 使用此参数提供单个检测密钥以供目标计算机上的所有应用使用。Use this parameter to supply a single instrumentation key for use by all apps on the target computer.

-InstrumentationKeyMap-InstrumentationKeyMap

必需。Required. 使用此参数可提供多个检测密钥以及每个应用使用的检测密钥映射。Use this parameter to supply multiple instrumentation keys and a mapping of the instrumentation keys used by each app. 通过设置 MachineFilter,可以为多台计算机创建单个安装脚本。You can create a single installation script for several computers by setting MachineFilter.

重要

应用将按照提供规则的顺序与规则相匹配。Apps will match against rules in the order that the rules are provided. 因此,你应该首先指定最特定的规则,最后指定最通用的规则。So you should specify the most specific rules first and the most generic rules last.

架构Schema

@(@{MachineFilter='.*';AppFilter='.*';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'}})

  • MachineFilter 是计算机或 VM 名称所需的 C# 正则表达式。MachineFilter is a required C# regex of the computer or VM name.
    • “.*”将匹配所有项'.*' will match all
    • “ComputerName”将仅匹配具有指定确切名称的计算机。'ComputerName' will match only computers with the exact name specified.
  • AppFilter 是 IIS 站点名称所需的 C# 正则表达式。AppFilter is a required C# regex of the IIS Site Name. 可以通过运行命令 get-iissite 获取服务器上的站点列表。You can get a list of sites on your server by running the command get-iissite.
    • “.*”将匹配所有项'.*' will match all
    • “SiteName”将仅匹配具有指定确切名称的 IIS 站点。'SiteName' will match only the IIS Site with the exact name specified.
  • 需要 InstrumentationKey 才能监视与上述两个筛选器匹配的应用。InstrumentationKey is required to enable monitoring of apps that match the preceding two filters.
    • 如果要定义排除监视的规则,请将此值保留为 null。Leave this value null if you want to define rules to exclude monitoring.

-EnableInstrumentationEngine-EnableInstrumentationEngine

可选。Optional. 使用此开关可让检测引擎收集执行托管进程期间发生的事件和相关消息。Use this switch to enable the instrumentation engine to collect events and messages about what's happening during the execution of a managed process. 这些事件和消息包括依赖项结果代码、HTTP 谓词和 SQL 命令文本。These events and messages include dependency result codes, HTTP verbs, and SQL command text.

检测引擎会增加开销,默认情况下处于关闭状态。The instrumentation engine adds overhead and is off by default.

-AcceptLicense-AcceptLicense

可选。Optional. 使用此开关可在无外设安装中接受许可条款和隐私声明。Use this switch to accept the license and privacy statement in headless installations.

-IgnoreSharedConfig-IgnoreSharedConfig

当你使用一组 Web 服务器时,你可能正在使用共享配置When you have a cluster of web servers, you might be using a shared configuration. HttpModule 无法注入此共享配置。The HttpModule can't be injected into this shared configuration. 此脚本将失败,并提示需要额外的安装步骤。This script will fail with the message that extra installation steps are required. 使用此开关可忽略该检查并继续安装必备组件。Use this switch to ignore this check and continue installing prerequisites. 有关详细信息,请参阅已知与 iis 共享配置的冲突For more information, see known conflict-with-iis-shared-configuration

-Verbose-Verbose

通用参数。Common parameter. 使用此开关可显示详细日志。Use this switch to display detailed logs.

-WhatIf-WhatIf

通用参数。Common parameter. 使用此开关可以测试和验证输入参数,而无需真正启用监视。Use this switch to test and validate your input parameters without actually enabling monitoring.

输出Output

成功启用后的示例输出Example output from a successful enablement

Initiating Disable Process
Applying transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config'
'C:\Windows\System32\inetsrv\config\applicationHost.config' backed up to 'C:\Windows\System32\inetsrv\config\applicationHost.config.backup-2019-03-26_08-59-52z'
in :1,237
No element in the source document matches '/configuration/location[@path='']/system.webServer/modules/add[@name='ManagedHttpModuleHelper']'
Not executing RemoveAll (transform line 1, 546)
Transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config' was successfully applied. Operation: 'disable'
GAC Module will not be removed, since this operation might cause IIS instabilities
Configuring IIS Environment for codeless attach...
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]
Configuring IIS Environment for instrumentation engine...
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]
Configuring registry for instrumentation engine...
Successfully disabled Application Insights Status Monitor
Installing GAC module 'C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\0.2.0\content\Runtime\Microsoft.AppInsights.IIS.ManagedHttpModuleHelper.dll'
Applying transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config'
Found GAC module Microsoft.AppInsights.IIS.ManagedHttpModuleHelper.ManagedHttpModuleHelper, Microsoft.AppInsights.IIS.ManagedHttpModuleHelper, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35
'C:\Windows\System32\inetsrv\config\applicationHost.config' backed up to 'C:\Windows\System32\inetsrv\config\applicationHost.config.backup-2019-03-26_08-59-52z_1'
Transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config' was successfully applied. Operation: 'enable'
Configuring IIS Environment for codeless attach...
Configuring IIS Environment for instrumentation engine...
Configuring registry for instrumentation engine...
Updating app pool permissions...
Successfully enabled Application Insights Status Monitor

Disable-InstrumentationEngineDisable-InstrumentationEngine

通过删除一些注册表项来禁用检测引擎。Disables the instrumentation engine by removing some registry keys. 重启 IIS 以使这些更改生效。Restart IIS for the changes to take effect.

示例Examples

PS C:\> Disable-InstrumentationEngine

parametersParameters

-Verbose-Verbose

通用参数。Common parameter. 使用此开关可输出详细日志。Use this switch to output detailed logs.

输出Output

成功禁用检测引擎的示例输出Example output from successfully disabling the instrumentation engine
Configuring IIS Environment for instrumentation engine...
Registry: removing 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]'
Registry: removing 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]'
Registry: removing 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]'
Configuring registry for instrumentation engine...

Disable-ApplicationInsightsMonitoringDisable-ApplicationInsightsMonitoring

在目标计算机上禁用监视。Disables monitoring on the target computer. 此 cmdlet 将删除对 IIS applicationHost.config 的编辑并删除注册表项。This cmdlet will remove edits to the IIS applicationHost.config and remove registry keys.

示例Examples

PS C:\> Disable-ApplicationInsightsMonitoring

parametersParameters

-Verbose-Verbose

通用参数。Common parameter. 使用此开关可显示详细日志。Use this switch to display detailed logs.

输出Output

成功禁用监视的示例输出Example output from successfully disabling monitoring
Initiating Disable Process
Applying transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config'
'C:\Windows\System32\inetsrv\config\applicationHost.config' backed up to 'C:\Windows\System32\inetsrv\config\applicationHost.config.backup-2019-03-26_08-59-00z'
in :1,237
No element in the source document matches '/configuration/location[@path='']/system.webServer/modules/add[@name='ManagedHttpModuleHelper']'
Not executing RemoveAll (transform line 1, 546)
Transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config' was successfully applied. Operation: 'disable'
GAC Module will not be removed, since this operation might cause IIS instabilities
Configuring IIS Environment for codeless attach...
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]
Configuring IIS Environment for instrumentation engine...
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]
Configuring registry for instrumentation engine...
Successfully disabled Application Insights Status Monitor

Get-ApplicationInsightsMonitoringConfigGet-ApplicationInsightsMonitoringConfig

获取配置文件并将值输出到控制台。Gets the config file and prints the values to the console.

示例Examples

PS C:\> Get-ApplicationInsightsMonitoringConfig

parametersParameters

不需要参数。No parameters required.

输出Output

读取配置文件的示例输出Example output from reading the config file
RedfieldConfiguration:
Filters:
0)InstrumentationKey:  AppFilter: WebAppExclude MachineFilter: .*
1)InstrumentationKey: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx2 AppFilter: WebAppTwo MachineFilter: .*
2)InstrumentationKey: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxdefault AppFilter: .* MachineFilter: .*

Get-ApplicationInsightsMonitoringStatusGet-ApplicationInsightsMonitoringStatus

此 cmdlet 提供有关状态监视器的故障排除信息。This cmdlet provides troubleshooting information about Status Monitor. 使用此 cmdlet 调查监视状态、PowerShell 模块的版本,以及检查正在运行的进程。Use this cmdlet to investigate the monitoring status, version of the PowerShell Module, and to inspect the running process. 此 cmdlet 将报告监视所需的版本信息和密钥文件相关信息。This cmdlet will report version information and information about key files required for monitoring.

示例Examples

示例:应用程序状态Example: Application status

运行 Get-ApplicationInsightsMonitoringStatus 命令来显示网站的监视状态。Run the command Get-ApplicationInsightsMonitoringStatus to display the monitoring status of web sites.


PS C:\Windows\system32> Get-ApplicationInsightsMonitoringStatus

IIS Websites:

SiteName               : Default Web Site
ApplicationPoolName    : DefaultAppPool
SiteId                 : 1
SiteState              : Stopped

SiteName               : DemoWebApp111
ApplicationPoolName    : DemoWebApp111
SiteId                 : 2
SiteState              : Started
ProcessId              : not found

SiteName               : DemoWebApp222
ApplicationPoolName    : DemoWebApp222
SiteId                 : 3
SiteState              : Started
ProcessId              : 2024
Instrumented           : true
InstrumentationKey     : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx123

SiteName               : DemoWebApp333
ApplicationPoolName    : DemoWebApp333
SiteId                 : 4
SiteState              : Started
ProcessId              : 5184
AppAlreadyInstrumented : true

在此示例中,In this example;

  • 计算机标识符是一个匿名 ID,用于唯一标识服务器。Machine Identifier is an anonymous ID used to uniquely identify your server. 如果你创建支持请求,我们需要该 ID 来查找你的服务器的日志。If you create a support request, we'll need this ID to find logs for your server.
  • “默认网站”在 IIS 中处于“已停止”状态Default Web Site is Stopped in IIS
  • DemoWebApp111 已在 IIS 中启动,但尚未收到任何请求。DemoWebApp111 has been started in IIS, but hasn't received any requests. 此报告显示没有正在运行的进程(ProcessId:找不到)。This report shows that there's no running process (ProcessId: not found).
  • DemoWebApp222 正在运行且正受监视(已检测:是)。DemoWebApp222 is running and is being monitored (Instrumented: true). 根据用户配置,此站点的检测密钥 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx123 匹配。Based on the user configuration, Instrumentation Key xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx123 was matched for this site.
  • DemoWebApp333 已使用 Application Insights SDK 进行手动检测。DemoWebApp333 has been manually instrumented using the Application Insights SDK. 状态监视器检测到 SDK,不会监视此站点。Status Monitor detected the SDK and won't monitor this site.

示例:PowerShell 模块信息Example: PowerShell module information

运行 Get-ApplicationInsightsMonitoringStatus -PowerShellModule 命令可显示有关当前模块的信息:Run the command Get-ApplicationInsightsMonitoringStatus -PowerShellModule to display information about the current module:


PS C:\> Get-ApplicationInsightsMonitoringStatus -PowerShellModule

PowerShell Module version:
0.4.0-alpha

Application Insights SDK version:
2.9.0.3872

Executing PowerShell Module Assembly:
Microsoft.ApplicationInsights.Redfield.Configurator.PowerShell, Version=2.8.14.11432, Culture=neutral, PublicKeyToken=31bf3856ad364e35

PowerShell Module Directory:
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\0.2.2\content\PowerShell

Runtime Paths:
ParentDirectory (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content

ConfigurationPath (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\applicationInsights.ikey.config

ManagedHttpModuleHelperPath (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AppInsights.IIS.ManagedHttpModuleHelper.dll

RedfieldIISModulePath (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.RedfieldIISModule.dll

InstrumentationEngine86Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation32\MicrosoftInstrumentationEngine_x86.dll

InstrumentationEngine64Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\MicrosoftInstrumentationEngine_x64.dll

InstrumentationEngineExtensionHost86Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation32\Microsoft.ApplicationInsights.ExtensionsHost_x86.dll

InstrumentationEngineExtensionHost64Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\Microsoft.ApplicationInsights.ExtensionsHost_x64.dll

InstrumentationEngineExtensionConfig86Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation32\Microsoft.InstrumentationEngine.Extensions.config

InstrumentationEngineExtensionConfig64Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\Microsoft.InstrumentationEngine.Extensions.config

ApplicationInsightsSdkPath (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.dll

示例:运行时状态Example: Runtime status

可以检查已检测计算机上的进程以查看是否已加载所有 DLL。You can inspect the process on the instrumented computer to see if all DLLs are loaded. 如果监视正常工作,则至少应加载 12 个 DLL。If monitoring is working, at least 12 DLLs should be loaded.

运行命令 Get-ApplicationInsightsMonitoringStatus -InspectProcessRun the command Get-ApplicationInsightsMonitoringStatus -InspectProcess:

PS C:\> Get-ApplicationInsightsMonitoringStatus -InspectProcess

iisreset.exe /status
Status for IIS Admin Service ( IISADMIN ) : Running
Status for Windows Process Activation Service ( WAS ) : Running
Status for Net.Msmq Listener Adapter ( NetMsmqActivator ) : Running
Status for Net.Pipe Listener Adapter ( NetPipeActivator ) : Running
Status for Net.Tcp Listener Adapter ( NetTcpActivator ) : Running
Status for World Wide Web Publishing Service ( W3SVC ) : Running

handle64.exe -accepteula -p w3wp
BF0: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.ServerTelemetryChannel.dll
C58: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.AzureAppServices.dll
C68: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.DependencyCollector.dll
C78: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.WindowsServer.dll
C98: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.Web.dll
CBC: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.PerfCounterCollector.dll
DB0: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.Agent.Intercept.dll
B98: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.RedfieldIISModule.dll
BB4: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.RedfieldIISModule.Contracts.dll
BCC: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.Redfield.Lightup.dll
BE0: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.dll

listdlls64.exe -accepteula w3wp
0x0000000019ac0000  0x127000  C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\MicrosoftInstrumentationEngine_x64.dll
0x00000000198b0000  0x4f000   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\Microsoft.ApplicationInsights.ExtensionsHost_x64.dll
0x000000000c460000  0xb2000   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\Microsoft.ApplicationInsights.Extensions.Base_x64.dll
0x000000000ad60000  0x108000  C:\Windows\TEMP\2.4.0.0.Microsoft.ApplicationInsights.Extensions.Intercept_x64.dll

parametersParameters

(不带参数)(No parameters)

默认情况下,此 cmdlet 会报告 Web 应用程序的监视状态。By default, this cmdlet will report the monitoring status of web applications. 使用此选项来查看是否已成功检测应用程序。Use this option to review if your application was successfully instrumented. 也可查看哪个检测密钥已与站点匹配。You can also review which Instrumentation Key was matched to your site.

-PowerShellModule-PowerShellModule

可选。Optional. 使用此开关报告监视所需的 DLL 的版本号和路径。Use this switch to report the version numbers and paths of DLLs required for monitoring. 如果需要标识任何 DLL 的版本(包括 Application Insights SDK),请使用此选项。Use this option if you need to identify the version of any DLL, including the Application Insights SDK.

-InspectProcess-InspectProcess

可选。Optional. 使用此开关报告 IIS 是否正在运行。Use this switch to report whether IIS is running. 它还将下载外部工具,以确定是否将必要的 DLL 加载到 IIS 运行时。It will also download external tools to determine if the necessary DLLs are loaded into the IIS runtime.

如果此过程因任何原因失败,你可以手动运行这些命令:If this process fails for any reason, you can run these commands manually:

  • iisreset.exe /statusiisreset.exe /status
  • handle64.exe -p w3wp | findstr /I "InstrumentationEngine AI.handle64.exe -p w3wp | findstr /I "InstrumentationEngine AI. ApplicationInsights"ApplicationInsights"
  • listdlls64.exe w3wp | findstr /I "InstrumentationEngine AI ApplicationInsights"listdlls64.exe w3wp | findstr /I "InstrumentationEngine AI ApplicationInsights"

-Force-Force

可选。Optional. 仅与 InspectProcess 一起使用。Used only with InspectProcess. 使用此开关可跳过在下载其他工具之前出现的用户提示。Use this switch to skip the user prompt that appears before additional tools are downloaded.

Set-ApplicationInsightsMonitoringConfigSet-ApplicationInsightsMonitoringConfig

在不进行完全重新安装的情况下设置配置文件。Sets the config file without doing a full reinstallation. 重启 IIS 以使更改生效。Restart IIS for your changes to take effect.

重要

此 cmdlet 需要具有管理员权限的 PowerShell 会话。This cmdlet requires a PowerShell session with Admin permissions.

示例Examples

使用单个检测密钥的示例Example with a single instrumentation key

在此示例中,将为当前计算机上的所有应用分配一个检测密钥。In this example, all apps on the current computer will be assigned a single instrumentation key.

PS C:\> Enable-ApplicationInsightsMonitoring -InstrumentationKey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

使用检测密钥映射的示例Example with an instrumentation key map

在本示例中:In this example:

  • MachineFilter 使用 '.*' 通配符匹配当前计算机。MachineFilter matches the current computer by using the '.*' wildcard.
  • AppFilter='WebAppExclude' 提供 null 检测密钥。AppFilter='WebAppExclude' provides a null instrumentation key. 不会检测指定的应用。The specified app won't be instrumented.
  • AppFilter='WebAppOne' 为指定的应用分配唯一的检测密钥。AppFilter='WebAppOne' assigns the specified app a unique instrumentation key.
  • AppFilter='WebAppTwo' 为指定的应用分配唯一的检测密钥。AppFilter='WebAppTwo' assigns the specified app a unique instrumentation key.
  • 最后,AppFilter 还使用 '.*' 通配符来匹配按以前规则不匹配的所有 Web 应用,并分配一个默认的检测密钥。Finally, AppFilter also uses the '.*' wildcard to match all web apps that aren't matched by the earlier rules and assign a default instrumentation key.
  • 添加空格以提高可读性。Spaces are added for readability.
Enable-ApplicationInsightsMonitoring -InstrumentationKeyMap `
       @(@{MachineFilter='.*';AppFilter='WebAppExclude'},
          @{MachineFilter='.*';AppFilter='WebAppOne';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx1'}},
          @{MachineFilter='.*';AppFilter='WebAppTwo';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx2'}},
          @{MachineFilter='.*';AppFilter='.*';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxdefault'}})

parametersParameters

-InstrumentationKey-InstrumentationKey

必需。Required. 使用此参数提供单个检测密钥以供目标计算机上的所有应用使用。Use this parameter to supply a single instrumentation key for use by all apps on the target computer.

-InstrumentationKeyMap-InstrumentationKeyMap

必需。Required. 使用此参数可提供多个检测密钥以及每个应用使用的检测密钥映射。Use this parameter to supply multiple instrumentation keys and a mapping of the instrumentation keys used by each app. 通过设置 MachineFilter,可以为多台计算机创建单个安装脚本。You can create a single installation script for several computers by setting MachineFilter.

重要

应用将按照提供规则的顺序与规则相匹配。Apps will match against rules in the order that the rules are provided. 因此,你应该首先指定最特定的规则,最后指定最通用的规则。So you should specify the most specific rules first and the most generic rules last.

架构Schema

@(@{MachineFilter='.*';AppFilter='.*';InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'})

  • MachineFilter 是计算机或 VM 名称所需的 C# 正则表达式。MachineFilter is a required C# regex of the computer or VM name.
    • “.*”将匹配所有项'.*' will match all
    • “ComputerName”将仅匹配具有指定名称的计算机。'ComputerName' will match only computers with the specified name.
  • AppFilter 是计算机或 VM 名称所需的 C# 正则表达式。AppFilter is a required C# regex of the computer or VM name.
    • “.*”将匹配所有项'.*' will match all
    • “ApplicationName”将仅匹配具有指定名称的 IIS 应用。'ApplicationName' will match only IIS apps with the specified name.
  • 需要 InstrumentationKey 才能监视与上述两个筛选器匹配的应用。InstrumentationKey is required to enable monitoring of the apps that match the preceding two filters.
    • 如果要定义排除监视的规则,请将此值保留为 null。Leave this value null if you want to define rules to exclude monitoring.

-Verbose-Verbose

通用参数。Common parameter. 使用此开关可显示详细日志。Use this switch to display detailed logs.

输出Output

默认情况下没有输出。By default, no output.

通过 -InstrumentationKey 设置配置文件的示例详细输出Example verbose output from setting the config file via -InstrumentationKey
VERBOSE: Operation: InstallWithIkey
VERBOSE: InstrumentationKeyMap parsed:
Filters:
0)InstrumentationKey: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx AppFilter: .* MachineFilter: .*
VERBOSE: set config file
VERBOSE: Config File Path:
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\applicationInsights.ikey.config
通过 -InstrumentationKeyMap 设置配置文件的示例详细输出Example verbose output from setting the config file via -InstrumentationKeyMap
VERBOSE: Operation: InstallWithIkeyMap
VERBOSE: InstrumentationKeyMap parsed:
Filters:
0)InstrumentationKey:  AppFilter: WebAppExclude MachineFilter: .*
1)InstrumentationKey: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx2 AppFilter: WebAppTwo MachineFilter: .*
2)InstrumentationKey: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxdefault AppFilter: .* MachineFilter: .*
VERBOSE: set config file
VERBOSE: Config File Path:
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\applicationInsights.ikey.config

Start-ApplicationInsightsMonitoringTraceStart-ApplicationInsightsMonitoringTrace

从无代码附加运行时收集 ETW 事件Collects ETW Events from the codeless attach runtime. 此 cmdlet 是运行 PerfView 的替代方法。This cmdlet is an alternative to running PerfView.

收集的事件将实时输出到控制台,并保存到 ETL 文件。Collected events will be printed to the console in real-time and saved to an ETL file. 可以通过 PerfView 打开该输出 ETL 文件,以用于进一步的调查。The output ETL file can be opened by PerfView for further investigation.

此 cmdlet 将一直运行到它达到超时持续时间(默认值为 5 分钟)或被手动停止 (Ctrl + C)。This cmdlet will run until it reaches the timeout duration (default 5 minutes) or is stopped manually (Ctrl + C).

示例Examples

如何收集事件How to collect events

通常,我们会要求你收集事件,以调查未检测应用程序的原因。Normally we would ask that you collect events to investigate why your application isn't being instrumented.

在 IIS 启动时以及在应用程序启动时,无代码附加运行时将发出 ETW 事件。The codeless attach runtime will emit ETW events when IIS starts up and when your application starts up.

若要收集这些事件,请执行以下操作:To collect these events:

  1. 在具有管理权限的 cmd 控制台中,执行 iisreset /stop 以关闭 IIS 和所有 Web 应用。In a cmd console with admin privileges, execute iisreset /stop To turn off IIS and all web apps.
  2. 执行此 cmdletExecute this cmdlet
  3. 在具有管理权限的 cmd 控制台中,执行 iisreset /start 以启动 IIS。In a cmd console with admin privileges, execute iisreset /start To start IIS.
  4. 尝试浏览到你的应用。Try to browse to your app.
  5. 在应用完成加载后,你可以手动停止它 (Ctrl + C) 或等待超时。After your app finishes loading, you can manually stop it (Ctrl + C) or wait for the timeout.

要收集的事件What events to collect

收集事件时,你有下面三个选择:You have three options when collecting events:

  1. 使用开关 -CollectSdkEvents 收集从 Application Insights SDK 发出的事件。Use the switch -CollectSdkEvents to collect events emitted from the Application Insights SDK.
  2. 使用开关 -CollectRedfieldEvents 收集由状态监视器和 Redfield 运行时发出的事件。Use the switch -CollectRedfieldEvents to collect events emitted by Status Monitor and the Redfield Runtime. 在诊断 IIS 和应用程序启动时,这些日志非常有用。These logs are helpful when diagnosing IIS and application startup.
  3. 使用这两个开关可收集这两种事件类型。Use both switches to collect both event types.
  4. 默认情况下,如果未指定任何开关,将收集这两种事件类型。By default, if no switch is specified both event types will be collected.

parametersParameters

-MaxDurationInMinutes-MaxDurationInMinutes

可选。Optional. 使用此参数可设置此脚本应收集事件的时长。Use this parameter to set how long this script should collect events. 默认值为 5 分钟。Default is 5 minutes.

-LogDirectory-LogDirectory

可选。Optional. 使用此开关可设置 ETL 文件的输出目录。Use this switch to set the output directory of the ETL file. 默认情况下,此文件将在 PowerShell 模块目录中创建。By default, this file will be created in the PowerShell Modules directory. 完整路径将在脚本执行期间显示。The full path will be displayed during script execution.

-CollectSdkEvents-CollectSdkEvents

可选。Optional. 使用此开关可收集 Application Insights SDK 事件。Use this switch to collect Application Insights SDK events.

-CollectRedfieldEvents-CollectRedfieldEvents

可选。Optional. 使用此开关可从状态监视器和 Redfield 运行时收集事件。Use this switch to collect events from Status Monitor and the Redfield runtime.

-Verbose-Verbose

通用参数。Common parameter. 使用此开关可输出详细日志。Use this switch to output detailed logs.

输出Output

应用程序启动日志的示例Example of application startup logs

PS C:\Windows\system32> Start-ApplicationInsightsMonitoringTrace -ColectRedfieldEvents
Starting...
Log File: C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\logs\20190627_144217_ApplicationInsights_ETW_Trace.etl
Tracing enabled, waiting for events.
Tracing will timeout in 5 minutes. Press CTRL+C to cancel.

2:42:31 PM EVENT: Microsoft-ApplicationInsights-IIS-ManagedHttpModuleHelper Trace Resolved variables to: MicrosoftAppInsights_ManagedHttpModulePath='C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.RedfieldIISModule.dll', MicrosoftAppInsights_ManagedHttpModuleType='Microsoft.ApplicationInsights.RedfieldIISModule.RedfieldIISModule'
2:42:31 PM EVENT: Microsoft-ApplicationInsights-IIS-ManagedHttpModuleHelper Trace Resolved variables to: MicrosoftDiagnosticServices_ManagedHttpModulePath2='', MicrosoftDiagnosticServices_ManagedHttpModuleType2=''
2:42:31 PM EVENT: Microsoft-ApplicationInsights-IIS-ManagedHttpModuleHelper Trace Environment variable 'MicrosoftDiagnosticServices_ManagedHttpModulePath2' or 'MicrosoftDiagnosticServices_ManagedHttpModuleType2' is null, skipping managed dll loading
2:42:31 PM EVENT: Microsoft-ApplicationInsights-IIS-ManagedHttpModuleHelper Trace MulticastHttpModule.constructor, success, 70 ms
2:42:31 PM EVENT: Microsoft-ApplicationInsights-RedfieldIISModule Trace Current assembly 'Microsoft.ApplicationInsights.RedfieldIISModule, Version=2.8.18.27202, Culture=neutral, PublicKeyToken=f23a46de0be5d6f3' location 'C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.RedfieldIISModule.dll'
2:42:31 PM EVENT: Microsoft-ApplicationInsights-RedfieldIISModule Trace Matched filter '.*'~'STATUSMONITORTE', '.*'~'DemoWithSql'
2:42:31 PM EVENT: Microsoft-ApplicationInsights-RedfieldIISModule Trace Lightup assembly calculated path: 'C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.Redfield.Lightup.dll'
2:42:31 PM EVENT: Microsoft-ApplicationInsights-FrameworkLightup Trace Loaded applicationInsights.config from assembly's resource Microsoft.ApplicationInsights.Redfield.Lightup, Version=2.8.18.27202, Culture=neutral, PublicKeyToken=f23a46de0be5d6f3/Microsoft.ApplicationInsights.Redfield.Lightup.ApplicationInsights-recommended.config
2:42:34 PM EVENT: Microsoft-ApplicationInsights-FrameworkLightup Trace Successfully attached ApplicationInsights SDK
2:42:34 PM EVENT: Microsoft-ApplicationInsights-RedfieldIISModule Trace RedfieldIISModule.LoadLightupAssemblyAndGetLightupHttpModuleClass, success, 2687 ms
2:42:34 PM EVENT: Microsoft-ApplicationInsights-RedfieldIISModule Trace RedfieldIISModule.CreateAndInitializeApplicationInsightsHttpModules(lightupHttpModuleClass), success
2:42:34 PM EVENT: Microsoft-ApplicationInsights-IIS-ManagedHttpModuleHelper Trace ManagedHttpModuleHelper, multicastHttpModule.Init() success, 3288 ms
2:42:35 PM EVENT: Microsoft-ApplicationInsights-IIS-ManagedHttpModuleHelper Trace Resolved variables to: MicrosoftAppInsights_ManagedHttpModulePath='C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.RedfieldIISModule.dll', MicrosoftAppInsights_ManagedHttpModuleType='Microsoft.ApplicationInsights.RedfieldIISModule.RedfieldIISModule'
2:42:35 PM EVENT: Microsoft-ApplicationInsights-IIS-ManagedHttpModuleHelper Trace Resolved variables to: MicrosoftDiagnosticServices_ManagedHttpModulePath2='', MicrosoftDiagnosticServices_ManagedHttpModuleType2=''
2:42:35 PM EVENT: Microsoft-ApplicationInsights-IIS-ManagedHttpModuleHelper Trace Environment variable 'MicrosoftDiagnosticServices_ManagedHttpModulePath2' or 'MicrosoftDiagnosticServices_ManagedHttpModuleType2' is null, skipping managed dll loading
2:42:35 PM EVENT: Microsoft-ApplicationInsights-IIS-ManagedHttpModuleHelper Trace MulticastHttpModule.constructor, success, 0 ms
2:42:35 PM EVENT: Microsoft-ApplicationInsights-RedfieldIISModule Trace RedfieldIISModule.CreateAndInitializeApplicationInsightsHttpModules(lightupHttpModuleClass), success
2:42:35 PM EVENT: Microsoft-ApplicationInsights-IIS-ManagedHttpModuleHelper Trace ManagedHttpModuleHelper, multicastHttpModule.Init() success, 0 ms
Timeout Reached. Stopping...

后续步骤Next steps

查看遥测:View your telemetry:

添加更多遥测:Add more telemetry:

使用 Application Insights 代理执行更多操作:Do more with Application Insights Agent:

  • 使用我们的指南对 Application Insights 代理进行故障排除Use our guide to troubleshoot Application Insights Agent.