Describe and analyze telemetry
Telemetry can be enabled on two different levels:
Environment-level telemetry
Telemetry can be enabled for a Business Central online environment or on-premises Business Central Server instance. When enabled on the environment, telemetry is emitted to a single Azure Application Insights resource for gathering data on operations that happen on the environment.
App/extension-level telemetry
Telemetry can also be enabled on a per-extension basis. Enabling telemetry is done by setting an Azure Application Insights connection string in the app's manifest (app.json file). At runtime, certain events related to the app/extension are emitted to the Azure Application Insights resource. This feature targets publishers of per-tenant extensions or Microsoft AppSource apps. It gives extension publishers insight into usage of their apps/extensions and also allows them to find errors and performance issues before partners and customers report them.
Both for environment-level and app-level telemetry, it's possible to craft custom telemetry messages directly from AL using the LogMessage Method.
Enable telemetry on environments
Once you have the resource and its connection string or instrumentation key, you can enable your tenants to send telemetry to your Azure Application Insights resource.
The way you enable Azure Application Insights depends on whether you want to connect to a Business Central online or Business Central on-premises environment. For on-premises, if also depends on whether the Business Central Server instance is configured as a single-tenant or multitenant instance.
For Business Central online, you can enable telemetry on environments either from the admin center or by using the admin center API. To use the admin center, complete the following steps.
For a single-tenant server instance of Business Central on-premises, set the Application Insights Connection String or Application Insights Instrumentation Key setting of the server instance.
For a multitenant server instance of Business Central on-premises, enable telemetry on a per-tenant basis when you mount tenants on the Business Central Server instance.
If you're using the BcContainerHelper module, specify the Azure Application Insights instrumentation key when you create the container. The key is used on the server instance for a single-tenant container. For a multitenant container, it's used on the default tenant
Assign a telemetry ID to users
To help troubleshooting problems experienced by a given Business Central user, you can assign the user a random ID that will be included in traces logged in Application Insights. This ID is a special GUID that's only used for telemetry. It will appear in the user_Id column in certain events, but not all. Specifically, it's used only in telemetry that the Business Central service/server emits in the context of a user session. So, for example, telemetry that the Business Central Web server emits won't include this ID.
The telemetry ID for a user is initially set by the Business Central server when the user is created. To change, or clear the telemetry ID on a user, set the Telemetry ID field on the User Card for the user in Business Central:
Sign in to Business Central using an administrator account.
Choose the icon, enter Users, and then choose the related link.
Choose the user name to open the User Card page.
Select the Telemetry ID field.
Analyze and Monitoring telemetry with Power BI
To make it simple to analyze Business Central telemetry, we've developed two Power BI apps available from Microsoft AppSource. One app is for telemetry on environments. The other one is for telemetry on apps/extensions (the telemetry defined in app.json). Both apps are free and open source but requires Power BI pro licenses to use.
About the reports in the app
The app consists of four reports:
Usage
Errors
Performance
Administration
Understand usage report
The usage report provides a multi-perspective view into how Business central is being used. The report can have data from in one or more environments or apps (depending on how you fill in the parameters and how you've partitioned the Azure Application Insights resource).
What do the pages in the report show?
Sessions: See how sessions are distributed over a timeline, weekday, and time of day
Clients: See which types of clients and browsers that users use
Locations: See where users sign in from and which languages they use in the client
Page views: See which pages users use and when
Reports: See which reports users use and when
Feature usage: See which features users use and when
Integrations and Connectors: See the activity on system integrations (web service calls)
Deprecated features: check if online environments are using deprecated features such as basic authentication and need to migrate to better solutions
Analyze Error report
The error report provides a multi-perspective view into errors occurring in one or more environments or apps (depending on how you fill in the parameters and how you've partitioned the Azure Application Insights resource). The report is a supplement to the Jupyter notebook trouble shooting guides (TSGs). Use the report to investigate and drill into the data and the notebook to follow a prescribed path.
Pages in the report show the following items:
User errors: When users get error dialogs, it can be a symptom of missing knowledge about the system, or that some features aren't set up the way they're supposed to.
Integrations errors: External systems communicate with Business Central using web services. Failures in this area means that some of the integrations are probably not working correctly.
System errors: Some Business Central modules or code might be misconfigured. Failures here indicate the system isn't set up correctly.
Performance report
The performance report provides a multi-perspective view into the performance of one or more environments or apps (depending on how you fill in the parameters and how you've partitioned the Azure Application Insights resource). The report is a supplement to the Jupyter notebook trouble shooting guides (TSGs). Use the report to investigate and drill into the data and the notebook to follow a prescribed path.
Pages in the report show the following items:
Sessions: Statistics on sessions that were started, client types (UI clients, background, or web service), and user types (normal, admin, or guest)
OnCompanyOpen: Timings of the OnCompanyOpen trigger (is run every time a session is created). Can show if expensive code was added here
Page views: Timings of pages visited by users, client type that ran them (modern client or desktop), and browsers used
Reports: Timings of reports, client type that ran them (UI clients or background), and reporting engine used (Word, RDLC, or processing only)
Long Running SQL Queries: Insights into SQL queries that ran longer than 750 milliseconds, the extensions and codeunits that called the database, and corresponding AL call stacks
Database lock timeouts: Insights into SQL queries that waited for a lock longer than 15 seconds, the extensions and codeunits that called the database, and corresponding AL call stacks
Long Running AL methods: Insights into AL methods that ran longer than 10,000 milliseconds, the extensions and codeunits they belong to, and corresponding AL call stacks
Incoming webservice calls/Outgoing webservice calls: Timings of incoming/outgoing web service calls and their type (SOAP, OData, or API), http status codes, and the codeunit they expose
Job Queue/Task scheduler: Timings of background jobs/tasks
Configuration packages: Timings of configuration package operations
App Updates: Timings of how long time updates of installed apps take
Administration report
The Administration report provides a multi-perspective view into the current state of Business central environments and any change done to them.
Pages in the report show the following items:
Inventory: See an inventory of environments and their current version
Update Planning: See an overview of environment versions and their update schedules
All changes: See changes to environments, companies, extensions, and indexes
Environment Changes: See changes to environments (for example, stop/start, rename, copy, delete, update)
Company Changes: See changes to companies (for example, create, rename, and delete)
Extension Changes: See changes to extensions (for example, install, update, and uninstall)
Index Changes: See changes to indexes (keys) (added, removed)
Field Changes: See changes to fields that are tracked in the field monitoring feature. Consider monitoring Business Central configuration tables to have that data show up here
Retention Policy: See date deleted due to retention policies set up in Business Central
App on environment/app telemetry
To install or update the app for environment telemetry, go to https://aka.ms/bctelemetryreport and select Get it now.
You'll first have to sign in to Microsoft AppSource using your Power BI account name and password, if you aren't already signed in. Follow the online instructions to get the app installed in Power BI.
Once installed, the Dynamics 365 Business Central Usage app appears under Apps in Power BI. A workspace with the same name is also installed for configuring the app.
To open the app, from the navigation pane, select Apps > Dynamics 365 Business Central Usage.
By default, the app shows sample data in the reports. This sample data enables you to demo the app to prospective customers without having to show data from existing customers.
App on app telemetry
To install or update the app for app telemetry, go to https://aka.ms/bctelemetry-isv-app and select Get it now.
You'll first have to sign in to Microsoft AppSource using your Power BI account name and password, if you aren't already signed in. Follow the online instructions to get the app installed in Power BI.
Once installed, the Dynamics 365 Business Central App Usage app appears under Apps in Power BI. A workspace with the same name is also installed for configuring the app.
To open the app, from the navigation pane, select Apps > Dynamics 365 Business Central App Usage.
By default, the app shows sample data in the reports. This sample data enables you to demo the app to prospective customers without having to show data from existing customers.