Feedback Edit

Monitoring and Analyzing Telemetry

  • Article
  • 7 minutes to read

APPLIES TO: Business Central 2019 release wave 2 and later

Business Central emits telemetry data for various activities and operations on tenants and extensions. Monitoring telemetry gives you a look at the activities and general health of your tenants, so you can diagnose problems and analyze operations that affect performance. Application Insights is a service hosted within Azure that gathers telemetry data for analysis and presentation. Whether running Business Central online or on-premises, you can set your tenants up to send telemetry to Application Insights.

Tenant-level and extension-level telemetry

Application Insights can be enabled on two different levels:

  • Tenant

    When enabled on the tenant, either for a Business Central online tenant or on-premises Business Central Server instance, telemetry is emitted to a single Application Insights resource for gathering data on tenant-wide operations.

  • Extension

    With the Business Central 2020 release wave 2 and later, Application Insights can also be enabled on a per-extension basis by setting an Application Insights connection in the extension's manifest (app.json file). At runtime, certain events related to the extension are emitted to the Application Insights resource. This feature targets publishers of per-tenant extensions to give them insight into issues in their extension before partners and customers report them.

Both for tenant-level and extension-level telemetry, it is possible to craft custom telemetry messages directly from AL using the LogMessage Method. Learn more about AL at Programming in AL.

Available telemetry

In Application Insights, telemetry from Business Central is logged as traces. Currently, Business Central offers telemetry on the following operations:

Area Description Online On-premises Extension support More information
AppSource Submission Validation Provides information about validation when an extension is submitted to AppSource. check mark for feature. check mark for feature See...
App key vault secrets Provides information about the retrieval of secrets from Azure Key Vaults by extensions. check mark for feature.[1] check mark for feature[1] check mark for feature See...
Authorization Provides information about user sign-in attempts. Information includes success or failure indication, reason for failure, user type, and more. check mark for feature. See...
Company lifecycle Provides information about creating, copying, and deleting of companies. check mark for feature. check mark for feature See...
Configuration package lifecycle Provides information about operations done on configuration packages, including exporting, importing, applying, and deleting. check mark for feature. check mark for feature See...
Database deadlocks[5] Provides information about database deadlocks that occur. check mark for feature. check mark for feature See...
Database lock timeouts Provides information about database locks that have timed out. check mark for feature. check mark for feature See...
Database wait statistics Provides information about the wait categories and the wait times a query runs into. check mark for feature. check mark for feature See...
Email Provides information about the success or failure of sending emails. check mark for feature. check mark for feature See...
Environment lifecycle [5] Provides information about changes and operations on an environment, like updates, hotfixes, copy, move, delete, configuration changes,and more. check mark for feature. See...
Error message quality[5] Provides information about error messages that users thought were helpful or unhelpful. check mark for feature. check mark for feature See...
Error method Provides information about error dialogs that are shown to the users. check mark for feature. check mark for feature See...
Extension lifecycle [2] Provides information about the success or failure of extension-related operations, like publishing, synchronizing, installing, and more. check mark for feature. check mark for feature check mark for feature See...
Extension update Provides information about errors that occur and upgrade tags used when upgrading an extension. check mark for feature. check mark for feature check mark for feature See...
Feature telemetry Provides information about the usage and errors of features. check mark for feature. check mark for feature See...
Field monitoring trace Provides information about the usage of the field monitoring feature. check mark for feature. check mark for feature See...
Job queue Provides information about creating and running job queue entries. check mark for feature. check mark for feature See...
Long running AL method trace[3] Provides information about long running AL methods. check mark for feature. check mark for feature check mark for feature See...
Long running operation (SQL query) Provides information about SQL queries that take longer than expected to execute. check mark for feature. check mark for feature check mark for feature See...
Page views Provides information about the pages that users open in the modern client. check mark for feature. check mark for feature[4] See...
Permissions Provides information about adding, removing, and assigning permission sets. check mark for feature. See...
Permission error[5] Provides information about errors related to permissions that users get. check mark for feature. check mark for feature. See...
Report generation Provides information about the execution of reports. check mark for feature. check mark for feature check mark for feature See...
Retention policy trace[3] Provides information about the usage of the retention policy feature. check mark for feature. check mark for feature See...
Incoming web service requests Provides information about the execution time of incoming web service requests. check mark for feature. check mark for feature check mark for feature See...
Outgoing web service requests Provides information about the execution time of outgoing web service requests. check mark for feature. check mark for feature check mark for feature See...
Stopped sessions[5] Provides information about background sessions that were forcibly stopped from the admin center or by calling the StopSession method from AL. check mark for feature. check mark for feature See...
Table index trace[3] Provides information about the addition or removal of a table index. check mark for feature. check mark for feature check mark for feature See...
Task scheduler lifecycle Provides information the execution of scheduled tasks. check mark for feature. check mark for feature See...
User checklists[5] Provides information about when the status of a user checklist changes check mark for feature. check mark for feature See...
Verbose logging enabled/disabled[5] Provides information about when additional logging is enabled and disabled from the client. check mark for feature. check mark for feature See...
Web service access key authentication Provides information about the authentication of web server access keys on web service requests. check mark for feature. check mark for feature See...

1This signal is only emitted to the Application Insights resource that's specified in the extension.

2Introduced in Business Central 2020 release wave 1, version 16.3. For extension telemetry, this signal was introduced in 2020 release wave 2, version 17.1.

3Introduced in Business Central 2020 release wave 1, version 17.1. For extension telemetry, this signal was introduced in 2021 release wave 1, version 18.1.

4Introduced in Business Central 2021 release wave 1, version 18.

5Introduced in Business Central 2022 release wave 1, version 20.

Enable Application Insights

To send telemetry data to Application Insights, you must have an Application Insights resource in Azure. Once you have the Application Insights resource, you can start to configure your tenants and extensions to send telemetry data to it. Learn more at Enable Sending Telemetry to Application Insights.

Note

For extensions, see Sending Extension Telemetry to Azure Application Insights.

Control telemetry cost

Azure Application Insights is billed based on the volume of telemetry data your application sends (data ingestion) and how long time you want data to be available (data retention).

Check the Azure Application Insights documentation for up-to-date information on pricing: https://azure.microsoft.com/pricing/details/monitor/.

Control data ingestion cost

To reduce data ingestion cost, you can:

  • sample to only ingest a percentage of the inbound data (learn more at Sampling in Application Insights.
  • set a daily limit of how much data can be ingested.
  • set alerts on cost thresholds being exceeded to get notified if this happens.
  • use a custom endpoint (learn more in the section below).

Except for using a custom endpoint, you find the options for controlling data ingestion cost in Azure Application Insights, under configure, usage, and estimated costs.

Use a custom endpoint

Azure Application Insights support overriding the standard data ingestion endpoint provided in the connection string (available in the Azure Application Insights portal). This means that you can send telemetry data to your own component to do post-processing such as filtering or enrichment before ingesting data into your data source of choice (such as an Azure SQL database, a datalake, Azure Log Analytics, Azure Application Insights, or a third-party data store).

You can override the ingestion endpoint by using the IngestionEndpoint key in the Azure Application Insights connection string. Learn more in the documentation: Overriding the Azure Application Insights standard connection string.

Reducing data retention cost

To reduce data retention cost, you can

  • use the default retention for Application Insights resources (currently 90 days). Different retention periods can be selected for each Application Insights resource. The full set of available retention periods is 30, 60, 90, 120, 180, 270, 365, 550, or 730 days.
  • purge data from your Application Insights resource using a set of user-defined filters. See Components - Purge for examples.

Viewing telemetry data in Application Insights

Telemetry from Business Central is stored in Azure Monitor Logs in the traces table. You can view collected data by writing log queries using Kusto query language (KQL). Learn more at Logs in Azure Monitor and Overview of log queries in Azure Monitor.

As a simple example, follow these steps:

  1. In the Azure portal, open your Application Insights resource.

  2. In the Monitoring menu, select Logs.

  3. On the New Query tab, enter the following to get the last 100 traces:

    traces
| take 100
| sort by timestamp desc

About custom dimensions

Each trace has a customDimensions column that includes a set of dimensions containing metrics specific to the trace. Each of these custom dimensions has a limit of 8000 characters. When logging an event with a dimension exceeding 8000 characters, the Business Central server adds additional overflow dimension keys to the event to contain the excess characters. There can be up to two additional overflow dimension keys, each with a maximum 8000 characters. The overflow dimension keys are named <dimension_key_name>_1 and <dimension_key_name>_2, where <dimension_key> is the name of the original dimension key. So if the custom dimension key is extensionCompilationDependencyList, then the overflow dimension keys would be extensionCompilationDependencyList_1 and extensionCompilationDependencyList_2.

Note

The 8000 character limit is governed by the Application Insights API.

Application Insights sample code

To make it easier to get started using Application Insights, samples of KQL code are available in the Business Central BCTech repository on GitHub.

Business Central telemetry FAQ

The Business Central BCTech repository on GitHub has an extensive FAQ on telemetry in Azure Application Insights.

See also

Telemetry Event IDs
Enable Sending Telemetry to Application Insights
Working with Administration Tools
Business Central Administration Center
Managing Environments
Managing Tenant Notifications
Introduction to Automation APIs
LogMessage Method