Monitoring and Analyzing Telemetry
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. | ![]() |
![]() |
See... | |
App key vault secrets | Provides information about the retrieval of secrets from Azure Key Vaults by extensions. | ![]() |
![]() |
![]() |
See... |
Authorization | Provides information about user sign-in attempts. Information includes success or failure indication, reason for failure, user type, and more. | ![]() |
See... | ||
Company lifecycle | Provides information about creating, copying, and deleting of companies. | ![]() |
![]() |
See... | |
Configuration package lifecycle | Provides information about operations done on configuration packages, including exporting, importing, applying, and deleting. | ![]() |
![]() |
See... | |
Database deadlocks[5] | Provides information about database deadlocks that occur. | ![]() |
![]() |
See... | |
Database lock timeouts | Provides information about database locks that have timed out. | ![]() |
![]() |
See... | |
Database wait statistics | Provides information about the wait categories and the wait times a query runs into. | ![]() |
![]() |
See... | |
Provides information about the success or failure of sending emails. | ![]() |
![]() |
See... | ||
Environment lifecycle [5] | Provides information about changes and operations on an environment, like updates, hotfixes, copy, move, delete, configuration changes,and more. | ![]() |
See... | ||
Error message quality[5] | Provides information about error messages that users thought were helpful or unhelpful. | ![]() |
![]() |
See... | |
Error method | Provides information about error dialogs that are shown to the users. | ![]() |
![]() |
See... | |
Extension lifecycle [2] | Provides information about the success or failure of extension-related operations, like publishing, synchronizing, installing, and more. | ![]() |
![]() |
![]() |
See... |
Extension update | Provides information about errors that occur and upgrade tags used when upgrading an extension. | ![]() |
![]() |
![]() |
See... |
Feature telemetry | Provides information about the usage and errors of features. | ![]() |
![]() |
See... | |
Field monitoring trace | Provides information about the usage of the field monitoring feature. | ![]() |
![]() |
See... | |
Job queue | Provides information about creating and running job queue entries. | ![]() |
![]() |
See... | |
Long running AL method trace[3] | Provides information about long running AL methods. | ![]() |
![]() |
![]() |
See... |
Long running operation (SQL query) | Provides information about SQL queries that take longer than expected to execute. | ![]() |
![]() |
![]() |
See... |
Page views | Provides information about the pages that users open in the modern client. | ![]() |
![]() |
See... | |
Permissions | Provides information about adding, removing, and assigning permission sets. | ![]() |
See... | ||
Permission error[5] | Provides information about errors related to permissions that users get. | ![]() |
![]() |
See... | |
Report generation | Provides information about the execution of reports. | ![]() |
![]() |
![]() |
See... |
Retention policy trace[3] | Provides information about the usage of the retention policy feature. | ![]() |
![]() |
See... | |
Incoming web service requests | Provides information about the execution time of incoming web service requests. | ![]() |
![]() |
![]() |
See... |
Outgoing web service requests | Provides information about the execution time of outgoing web service requests. | ![]() |
![]() |
![]() |
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. | ![]() |
![]() |
See... | |
Table index trace[3] | Provides information about the addition or removal of a table index. | ![]() |
![]() |
![]() |
See... |
Task scheduler lifecycle | Provides information the execution of scheduled tasks. | ![]() |
![]() |
See... | |
User checklists[5] | Provides information about when the status of a user checklist changes | ![]() |
![]() |
See... | |
Verbose logging enabled/disabled[5] | Provides information about when additional logging is enabled and disabled from the client. | ![]() |
![]() |
See... | |
Web service access key authentication | Provides information about the authentication of web server access keys on web service requests. | ![]() |
![]() |
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:
In the Azure portal, open your Application Insights resource.
In the Monitoring menu, select Logs.
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
Feedback
Submit and view feedback for