Setting up telemetry in an app/extension

APPLIES TO: Business Central 2020 release wave 2 and later

This article describes how to set up an extension to send telemetry data to Azure Application Insights for monitoring and analyzing. For each environment where the app/extension is installed, Business Central emits telemetry data for several operations that occur when extension code is run.

The app telemetry feature targets publishers of per-tenant or appsource extensions to give them insight into issues in their extensions before partners and customers report them. You get data for all customers across the install base of the app/extension.

Setting up telemetry in an App/Extension requires only 2-3 steps.

1. Get an Application Insights resource in Azure.
2. Add the Application Insights information to the app/extension.
3. Optionally, add feature telemetry or custom telemetry calls to your AL code.

Get an Application Insights resource in Azure

The first thing to do is to create an Application Insights resource in Azure if you don't have one. For more information, see Create an Application Insights resource.

The Azure Application Insights resource is assigned a connection string, which you can see on the Overview page for the resource in Azure. Copy this connection string because you'll need it to enable telemetry in the app/extension.

Add the Application Insights information to the app/extension

The next step is to enable telemetry in your app/extension. You do this by adding the "applicationInsightsConnectionString" setting to the extension's app.json as shown:

"applicationInsightsConnectionString": "<connection string>"

Replace <connection string> with the string that you copied in the Azure Application Insights overview. For more information about the format of the Azure Application Insights connection string, see Connection Strings.

When done, build the extension package, then publish and install it as usual. When the extension is run from Business Central, Azure Application Insights gathers the telemetry data for viewing and analyzing.

Before runtime version 7.2

Up until runtime version 7.2 you can't use the "applicationInsightsConnectionString" setting. Instead you have to use the "applicationInsightsKey" setting, which is added using only the instrumentation key from the Azure Application Insights connection string as shown:

"applicationInsightsKey": "<instrumentation key>"

Where <instrumentation key> is replaced by the key denoted in the connection string as InstrumentationKey=<instrumentation key>;<some other parameters>.

Adding feature telemetry or custom telemetry calls to your AL code

When you have enabled telemetry for your app/extension, the Business Central platform emits telemetry events that happen in the context of the AL code of the app/extension. For example, you get telemetry events when users interact with pages from your app/extension, when REST APIs from your app/extension are called, or when reports from your app/extension are rendered. You get telemetry events when users get error dialogs raised in pages from your app/extension, and when your AL code consumes excessive resources on the Business Central server or database.

You might also want to log your own events to telemetry. The easiest way to do this is to use the feature usage module in the System Application. For more information, see Using Feature telemetry. If you want full control of the structure of the events you send to telemetry, then you can also use the raw Session.LogMessage. For more information, see Creating custom telemetry events.

See also

Get started with AL
Publishing and installing extensions
JSON files
Instrumenting an application for telemetry
Data logged to app/extension telemetry
Viewing telemetry data in Azure Application Insights
Using feature telemetry
Creating custom telemetry events