Set up telemetry in an extension

APPLIES TO: Business Central 2020 release wave 2 and later

Configure an extension to send telemetry to Azure Application Insights so that you can monitor its use, errors, and performance. The configured resource can receive eligible extension telemetry from environments where the extension is installed and telemetry emission is enabled.

Extension telemetry helps publishers of per-tenant extensions and Marketplace apps investigate issues before partners and customers report them.

To set up extension telemetry:

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

Create an Application Insights resource in Azure if you don't have one. Learn more in 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 connection string to your extension

Starting with runtime 7.2, add the applicationInsightsConnectionString property to your extension's app.json file, as shown in this excerpt:

{
    "applicationInsightsConnectionString": "<ConnectionString>"
}

Replace <ConnectionString> with the connection string that you copied from the Application Insights resource. Learn more about its format in Connection strings in Application Insights.

Build the extension package, and then publish and install it. When the extension runs, it sends eligible telemetry events to the configured resource.

Before runtime version 7.2

For runtime versions earlier than 7.2, use the legacy applicationInsightsKey property instead. Set it to the instrumentation key from the Application Insights connection string, as shown in this excerpt:

{
    "applicationInsightsKey": "<InstrumentationKey>"
}

Replace <InstrumentationKey> with the value of InstrumentationKey in the connection string. Don't specify both applicationInsightsKey and applicationInsightsConnectionString in the same manifest.

Add feature or custom telemetry to your AL code

The platform emits eligible events associated with your extension, such as page views, incoming API requests, report execution, error dialogs, and threshold-triggered performance events. Learn more in Data logged to extension telemetry.

To log your own feature events, use the Feature Telemetry module in the System Application. Register a telemetry logger for your publisher before adding feature telemetry calls. Learn more in Using feature telemetry.

To specify custom event IDs, messages, and dimensions, use Session.LogMessage. Telemetry data-classification and privacy rules still apply. Learn more in Creating custom telemetry events.

Related information

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