What is mentioned by console applications

Application Insights for worker service applications (non-HTTP applications)

  • 14 minutes to read

The Application Insights SDK for Worker Service Applications is a new SDK that is perfect for non-HTTP workloads, such as: These include messaging, background tasks, console applications, and so on. These types of applications do not have inbound HTTP requests like a traditional ASP.NET / ASP.NET Core web application. Therefore, using Application Insights packages for ASP.NET and ASP.NET Core applications is not supported.

The new SDK does not collect telemetry data. Instead, it uses other well-known automatic Application Insights collectors, such as: B. DependencyCollector, PerfCounterCollector, ApplicationInsightsLoggingProvider etc. This SDK makes extension methods available in to enable and configure the collection of telemetry data.

Supported scenarios

The Application Insights SDK for worker service applications is perfect for non-HTTP applications, no matter where or how they're running. If your application is running and has a network connection to Azure, telemetry data can be collected. Application Insights monitoring is supported in any environment that supports .NET Core. This package can be used in the newly introduced .NET Core 3.0 worker service, background tasks in ASP.NET Core 2.1 / 2.2, console apps (.NET Core / .NET Framework), etc.

requirements

A valid Application Insights instrumentation key. This is required to send telemetry data to Application Insights. If you need to create a new Application Insights resource to get an instrumentation key, see Creating an Application Insights Resource.

Use the Application Insights SDK for worker service applications

  1. Install the Microsoft.ApplicationInsights.WorkerService package for the application. The following snippet of code shows the changes you need to add to your project's file.
  1. Call the extension method for to provide the instrumentation key. This method should be called at the beginning of the application. The exact location depends on the type of application.

  2. Get an instance or instance from the dependency injection (DI) container by calling or using constructor injection. This step triggers the setup of the module and the module for automatic collection.

Refer to the following sections for specific instructions for each type of application.

.NET Core 3.0 worker service application

You can find the full example here.

  1. Download and install .NET Core 3.0.

  2. Create a new worker service project using a Visual Studio project template or the command line.

  3. Install the Microsoft.ApplicationInsights.WorkerService package for the application.

  4. Add the method in your class, as shown in the following example:

  1. Change according to the following example.
  1. Set up the instrumentation key.

    You can provide an instrumentation key as an argument to. However, it is recommended to specify the instrumentation key in the configuration. The following sample code shows how to specify in an instrumentation key. Make sure to copy to the application root folder during publishing.

Alternatively, you can specify the instrumentation key in one of the following environment variables. or

Example: OR

Typically, it is used to set the instrumentation key for applications that are deployed as web jobs in web apps.

Note

An instrumentation key specified in the code takes precedence over the environment variable, which in turn takes precedence over other options.

ASP.NET Core background tasks with hosted services

This document describes how to create background tasks in an ASP.NET Core 2.1 / 2.2 application.

You can find the full example here.

  1. Install the Microsoft.ApplicationInsights.WorkerService package for the application.
  2. Add the method as shown in the following example:

The following code for is the background task logic.

  1. Set up the instrumentation key. Use the file from the example above for the .NET Core 3.0 worker service.

.NET Core / .NET Framework console application

As mentioned at the beginning of this article, the new package can be used to enable Application Insights telemetry even from a regular console application. This package is intended for and can therefore be used for console applications in .NET Core 2.0 or higher and .NET Framework 4.7.2 or higher.

You can find the full example here.

  1. Install the Microsoft.ApplicationInsights.WorkerService package for the application.

  2. Modify “Program.cs” according to the following example.

This console application uses the same standard and can be customized in the same way as the examples in the previous section.

Run the application

Run your application. The workers in the above examples make an HTTP call to "bing.com" every second and output some logs using. These lines are contained in a call to used to create an operation (named "operation" in this example). Application Insights collects these ILogger logs (by default, Warning severity or higher) and dependencies, and they are also correlated in a parent-child relationship. The correlation can also take place across processes and across network boundaries. If the call z. B. has been done for another monitored component, it is also correlated with the higher-level element.

This custom operation corresponds to an incoming web request in a typical web application. Although there is no need to use an operation, it works best with the correlation data model in Application Insights. It acts as a higher-level process, and all telemetry data generated in the worker iteration are treated as logically belonging to the same process. This approach also ensures that all telemetry data generated (automatically and manually) is the same. When sampling is based on, all telemetry data from a single iteration is either retained or deleted.

All telemetry data that Application Insights automatically collects is listed below.

Live metrics

Live metrics are a quick way to verify that Application Insights monitoring is properly configured. It can take a few minutes for the telemetry data to be displayed in the portal and in the analysis. In live metrics, on the other hand, the CPU utilization of the running process is displayed almost in real time. In addition, other telemetry data such as B. Requirements, dependencies or traces can be displayed.

ILogger logs

Logs issued with severity or higher are automatically collected. Refer to the ILogger documentation for information on customizing the log levels recorded in Application Insights.

Dependencies

By default, dependency collection is enabled. This article explains the dependencies that are automatically collected and the steps to follow up manually.

EventCounter

is enabled by default and collects a standard set of counters from .NET Core 3.0 apps. The EventCounter tutorial lists the standard set of performance counters collected. It also provides instructions on how to customize the list.

Manually track additional telemetry data

Although the SDK automatically collects telemetry as explained above, in most cases the user will need to send additional telemetry to Application Insights. The recommended way to track additional telemetry is to get an instance of from the dependency injection and then call one of the supported API methods on it. Another typical use case is custom tracking of operations. This approach is illustrated in the worker examples above.

Configure the Application Insights SDK

The default used by the Worker Service SDK is similar to the automatic configuration in an ASP.NET or ASP.NET Core application, but it does not have the TelemetryInitializers that are used to enrich telemetry from.

You can customize the Application Insights SDK for worker service applications to change the default configuration. ASP.NET Core SDK for Application Insights users may know how to customize configuration using ASP.NET Core's built-in dependency injection. The WorkerService SDK is based on similar principles. Make almost all of the changes in the section by calling the appropriate methods for, as described below.

Note

If you are using this SDK, changing the configuration by changing is not supported and the changes will have no effect.

Using ApplicationInsightsServiceOptions

You can change some general settings by passing the method, as in the following example:

Note that in this SDK it is in the namespace while in the ASP.NET Core SDK it is in the namespace.

Frequently used settings in

attitudeDESCRIPTIONdefault
EnableQuickPulseMetricStreamActivate / deactivate the "LiveMetrics" featuretrue
EnableAdaptiveSamplingEnable / disable adaptive samplingtrue
EnableHeartbeatActivate / deactivate the heartbeats feature that sends a user-defined metric called "HeartBeatState" at regular intervals (default value: 15 minutes) with information about the runtime such as .NET version, information about the Azure environment, etc., if applicable.true
AddAutoCollectedMetricExtractorEnable / disable the extractor for AutoCollectedMetrics, which is a telemetry processor that sends pre-aggregated metrics on requirements / dependencies before sampling.true
EnableDiagnosticsTelemetryModule activate / deactivate. If you disable this setting, the following settings will be ignored:,,.true

The current list can be found under the configurable settings in.

Spot checks

The Application Insights SDK for worker service applications supports both fixed and adaptive sampling. Adaptive sampling is enabled by default. Sampling can be disabled using the option in ApplicationInsightsServiceOptions.

The following example can be used to configure additional settings for sampling.

For more information, see the Sampling Document.

Adding TelemetryInitializers

With telemetry initializers, you define the properties that are sent with all telemetry data.

Add each new one to the container and the SDK will automatically add it to the.

Removal of TelemetryInitializer elements

Telemetry initializers are provided by default. If you want to remove all or just specific telemetry initializers, you can use the following sample code to calling to use.

Adding telemetry processors

You can add custom telemetry processors using the extension method in. In complex filtering scenarios, telemetry processors give you more precise control over what information is included or excluded from the telemetry data sent to Application Insights. Use the following example.

Configure or remove standard TelemetryModule elements

Application Insights uses telemetry modules to automatically collect telemetry data on specific workloads without the need for manual tracking.

The modules listed below are activated by default. They are responsible for the automatic collection of telemetry data. You can disable them or customize their default behavior.

  • (There is currently an issue with this telemetry module. For a temporary workaround, see GitHub issue 1689.)

To configure standard elements, use the extension method in. This is shown in the example below.

Configure the telemetry channel

The default channel is. You can overwrite this as shown in the following example.

Dynamic deactivation of telemetry

If you want to conditionally and dynamically disable telemetry, you can resolve an instance with an ASP.NET Core dependency injection container anywhere in your code and set a flag for it.

frequently asked Questions

How can I track telemetry data that is not automatically collected?

Get an instance of by passing the dependency through the constructor (Constructor Injection) and calling the required method. It is not recommended to create new instances. A singleton instance of is already registered in the container that is used for all other telemetry data. You should only create a new instance if it requires a configuration that differs from that for the other telemetry data.

Can I use the Visual Studio IDE to onboard Application Insights into a worker service project?

Onboarding with the Visual Studio IDE is currently only supported for ASP.NET / ASP.NET Core applications. This document will be updated when Visual Studio supports onboarding of worker service applications.

Can I enable Application Insights monitoring using tools like Status Monitor?

No. The status monitor and the status monitor v2 currently only support ASP.NET 4.x.

Are all features supported when I run my application on Linux?

Yes. Feature support for this SDK is the same on all platforms. However, the following exceptions apply:

  • Performance counters are only supported on Windows, with the exception of the display of process CPU / memory in live metrics.
  • Even if it is enabled by default, the channel does not automatically create a local storage folder when the application runs on Linux or macOS to temporarily save the telemetry data in the event of network problems. Because of this limitation, telemetry data will be lost if there are temporary network or server problems. The workaround is to configure a local folder for the channel:

Sample applications

.NET Core Console Application Use this example if you are using a console application written in .NET Core (2.0 or higher) or .NET Framework (4.7.2 or higher).

ASP .NET Core Background Tasks with Hosted Services Use this example if you are creating background tasks in ASP.NET Core 2.1 / 2.2 according to the official instructions (here).

.NET Core 3.0 Worker Service Use this example if you have a .NET Core 3.0 Worker Service application according to the official guide (here).

Open source SDK

For the latest updates and bug fixes, see the release notes.

Next Steps