Deploy Azure Monitor Application Insights Agent for on-premises servers

  • Article

Application Insights Agent (formerly named Status Monitor V2) is a PowerShell module published to the PowerShell Gallery. It replaces Status Monitor. Telemetry is sent to the Azure portal, where you can monitor your app.

For a complete list of supported autoinstrumentation scenarios, see Supported environments, languages, and resource providers.

Note

The module currently supports codeless instrumentation of ASP.NET and ASP.NET Core web apps hosted with IIS. Use an SDK to instrument Java and Node.js applications.

Note

Client-side monitoring is enabled by default for ASP.NET Core apps. If you want to disable client-side monitoring, define an environment variable in the server with the following information:

  • Name: APPINSIGHTS_JAVASCRIPT_ENABLED
  • Value: false

Application Insights Agent is located in the PowerShell Gallery.

PowerShell Gallery icon.

Instructions

  • To get started with concise code samples, see the Getting started tab.
  • For a deep dive on how to get started, see the Detailed instructions tab.
  • For PowerShell API reference, see the API reference tab.
  • For release note updates, see the Release notes tab.

This tab describes how to onboard to the PowerShell Gallery and download the ApplicationMonitor module. Included are the most common parameters that you need to get started. We also provide manual download instructions in case you don't have internet access.

Get a connection string

To get started, you need a connection string. For more information, see Connection strings.

Note

On March 31, 2025, support for instrumentation key ingestion will end. Instrumentation key ingestion will continue to work, but we'll no longer provide updates or support for the feature. Transition to connection strings to take advantage of new capabilities.

Run PowerShell as Admin with an elevated execution policy

Run as Admin

PowerShell needs Administrator-level permissions to make changes to your computer.

Execution policy

  • Description: By default, running PowerShell scripts is disabled. We recommend allowing RemoteSigned scripts for only the Current scope.
  • Reference: About Execution Policies and Set-ExecutionPolicy.
  • Command: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process.
  • Optional parameter:
    • -Force. Bypasses the confirmation prompt.

Example errors

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.

Prerequisites for PowerShell

Audit your instance of PowerShell by running the $PSVersionTable command. This command produces the following output:

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

These instructions were written and tested on a computer running Windows 10 and the following versions.

These steps prepare your server to download modules from PowerShell Gallery.

Note

PowerShell Gallery is supported on Windows 10, Windows Server 2016, and PowerShell 6+. For information about earlier versions, see Installing PowerShellGet.

  1. Run PowerShell as Admin with an elevated execution policy.

  2. Install the NuGet package provider.

    • Description: You need this provider to interact with NuGet-based repositories like PowerShell Gallery.
    • Reference: Install-PackageProvider.
    • Command: Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201.
    • Optional parameters:
      • -Proxy. Specifies a proxy server for the request.
      • -Force. Bypasses the confirmation prompt.

    You receive this prompt if NuGet isn't set up:

    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. Configure PowerShell Gallery as a trusted repository.

    • Description: By default, PowerShell Gallery is an untrusted repository.
    • Reference: Set-PSRepository.
    • Command: Set-PSRepository -Name "PSGallery" -InstallationPolicy Trusted.
    • Optional parameter:
      • -Proxy. Specifies a proxy server for the request.

    You receive this prompt if PowerShell Gallery isn't trusted:

    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"):

    You can confirm this change and audit all PSRepositories by running the Get-PSRepository command.

  4. Install the newest version of PowerShellGet.

    • Description: This module contains the tooling used to get other modules from PowerShell Gallery. Version 1.0.0.1 ships with Windows 10 and Windows Server. Version 1.6.0 or higher is required. To determine which version is installed, run the Get-Command -Module PowerShellGet command.
    • Reference: Installing PowerShellGet.
    • Command: Install-Module -Name PowerShellGet.
    • Optional parameters:
      • -Proxy. Specifies a proxy server for the request.
      • -Force. Bypasses the "already installed" warning and installs the latest version.

    You receive this error if you're not using the newest version of 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. Restart PowerShell. You can't load the new version in the current session. New PowerShell sessions load the latest version of PowerShellGet.

These steps download the Az.ApplicationMonitor module from PowerShell Gallery.

  1. Ensure that all prerequisites for PowerShell Gallery are met.
  2. Run PowerShell as Admin with an elevated execution policy.
  3. Install the Az.ApplicationMonitor module.
    • Reference: Install-Module.
    • Command: Install-Module -Name Az.ApplicationMonitor.
    • Optional parameters:
      • -Proxy. Specifies a proxy server for the request.
      • -AllowPrerelease. Allows installation of alpha and beta releases.
      • -AcceptLicense. Bypasses the "Accept License" prompt
      • -Force. Bypasses the "Untrusted Repository" warning.

Download and install the module manually (offline option)

If for any reason you can't connect to the PowerShell module, you can manually download and install the Az.ApplicationMonitor module.

Manually download the latest nupkg file

  1. Go to https://www.powershellgallery.com/packages/Az.ApplicationMonitor.
  2. Select the latest version of the file in the Version History table.
  3. Under Installation Options, select Manual Download.

Option 1: Install into a PowerShell modules directory

Install the manually downloaded PowerShell module into a PowerShell directory so it's discoverable by PowerShell sessions. For more information, see Installing a PowerShell Module.

Unzip nupkg as a zip file by using Expand-Archive (v1.0.1.0)

  • Description: The base version of Microsoft.PowerShell.Archive (v1.0.1.0) can't unzip nupkg files. Rename the file with the .zip extension.

  • Reference: Expand-Archive.

  • Command:

    $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
Unzip nupkg by using Expand-Archive (v1.1.0.0)

  • Description: Use a current version of Expand-Archive to unzip nupkg files without changing the extension.

  • Reference: Expand-Archive and Microsoft.PowerShell.Archive.

  • Command:

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

Option 2: Unzip and import nupkg manually

Install the manually downloaded PowerShell module into a PowerShell directory so it's discoverable by PowerShell sessions. For more information, see Installing a PowerShell Module.

If you're installing the module into any other directory, manually import the module by using Import-Module.

Important

DLLs will install via relative paths. Store the contents of the package in your intended runtime directory and confirm that access permissions allow read but not write.

  1. Change the extension to ".zip" and extract the contents of the package into your intended installation directory.
  2. Find the file path of Az.ApplicationMonitor.psd1.
  3. Run PowerShell as Admin with an elevated execution policy.
  4. Load the module by using the Import-Module Az.ApplicationMonitor.psd1 command.

Route traffic through a proxy

When you monitor a computer on your private intranet, you need to route HTTP traffic through a proxy.

The PowerShell commands to download and install Az.ApplicationMonitor from the PowerShell Gallery support a -Proxy parameter. Review the preceding instructions when you write your installation scripts.

The Application Insights SDK needs to send your app's telemetry to Microsoft. We recommend that you configure proxy settings for your app in your web.config file. For more information, see How do I achieve proxy passthrough?.

Enable monitoring

Use the Enable-ApplicationInsightsMonitoring command to enable monitoring.

See the API reference for a detailed description of how to use this cmdlet.

Frequently asked questions

This section provides answers to common questions.

Does Application Insights Agent support proxy installations?

Yes. There are multiple ways to download Application Insights Agent:

  • If your computer has internet access, you can onboard to the PowerShell Gallery by using -Proxy parameters.
  • You can also manually download the module and either install it on your computer or use it directly.

Each of these options is described in the detailed instructions.

Does Application Insights Agent support ASP.NET Core applications?

Yes. In Application Insights Agent 2.0.0 and later, ASP.NET Core applications hosted in IIS are supported.

How do I verify that the enablement succeeded?

  • You can use the Get-ApplicationInsightsMonitoringStatus cmdlet to verify that enablement succeeded.

  • Use Live Metrics to quickly determine if your app is sending telemetry.

  • You can also use Log Analytics to list all the cloud roles currently sending telemetry:

    union * | summarize count() by cloud_RoleName, cloud_RoleInstance

How do I achieve proxy passthrough?

To achieve proxy passthrough, configure a machine-level proxy or an application-level proxy. See DefaultProxy.

Example Web.config:

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

Troubleshooting

See the dedicated troubleshooting article.

Test connectivity between your application host and the ingestion service

Application Insights SDKs and agents send telemetry to get ingested as REST calls to our ingestion endpoints. You can test connectivity from your web server or application host machine to the ingestion service endpoints by using raw REST clients from PowerShell or curl commands. See Troubleshoot missing application telemetry in Azure Monitor Application Insights.

Next steps

View your telemetry:

Add more telemetry:

Do more with Application Insights Agent: