Enable Environment Telemetry
APPLIES TO: Business Central 2019 release wave 2 and later
This article describes how to set up sending telemetry data to Azure Application Insights for Business Central online and on-premises environments.
For app/extension telemetry, see Sending Extension Telemetry to Azure Application Insights.
Get started (set up Azure Application Insights)
If you don't already have one, get a subscription to Microsoft Azure.
Sign in to the Azure portal.
Create an Azure Application Insights resource by following the guidelines at Workspace-based Application Insights resources.
In Business Central 2020 release wave 2 (v17) and earlier, don't use an Azure Application Insights resource in Germany regions, such as (Europe) Germany West Central or (Europe) Germany North. If you do, traces from Business Central might not be recorded in Application Insights. The mitigation is to create an Azure Application Insights resource in a region outside of Germany. Then, when the relevant time comes, move the resource to the preferred region.
The Azure Application Insights resource can be in any Azure tenant that is accessible to your organization. For example, a delegated administrator from the reselling partner is the person analyzing the telemetry. But this person might not have access rights the customer's Azure instance. This scenario enables the partner to send the telemetry to their own Azure Application Insights instance.
You can use the same Azure Application Insights resource for multiple tenants and their different environments.
For more information, see Create an Application Insights resource.
Depending on your Business Central version, get the Connection String or Instrumentation Key of the Azure Application Insights resource.
You can copy this information from the Overview page for resource in the Azure portal.
For Business Central 2020 release wave 2 (v17) or earlier, copy the Instrumentation Key.
For later versions, copy the Connection String. The maximum supported length for the connection string is 2,048 characters.
For these versions, you can use either the instrumentation key or the connection string. However, for reliability, we recommend that you use the connection string.
Transition to using connection strings for data ingestion in Application Insights by 31 March 2025. On 31 March 2025, technical support for instrumentation key–based global ingestion in the Application Insights feature of Azure Monitor will end. After that date, your Azure Application Insights resources will continue to receive data, but Microsoft no longer provide updates or customer support for instrumentation key–based global ingestion.
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 online environments
For Business Central online, you can enable telemetry on environments either from the admin center or by using the the admin center API. To use the admin center, complete the following steps. For information about using the admin center API, go to Put AppInsights key.
From the admin center
In the Business Central administration center, select Environments, and then select the environment that you want to change.
The next steps require a restart to the environment, which is triggered automatically at the end of this procedure. Plan to do this during non-working hours to avoid disruptions.
On the Environment page, the Application Insights Key field shows if the environment already uses application insights.
To enable telemetry, choose the Define caption, and then, in the Set Application Insights Key pane, choose the Enable application insights field and enter the instrumentation key in the Instrumentation Key field.
In version 15 and 16, to enable telemetry, choose the Application Insights Key action, and then specify the instrumentation key.
Choose the Save button.
For on-premises environments (single-tenant mode)
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.
Set-NAVServerConfiguration -ServerInstance BC200 -Keyname ApplicationInsightsConnectionString -Keyvalue 'InstrumentationKey=11111111-2222-3333-4444-555555555555;IngestionEndpoint=https://westeurope-1.in.applicationinsights.azure.com/'
For more information, see Configuring Business Central Server.
For on-premises environments (multi-tenant mode)
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.
The Mount-NAVTenant cmdlet includes the
-ApplicationInsightsKey parameters. For example:
Mount-NAVTenant -ServerInstance BC200 -Tenant tenant1 -DatabaseName "Demo Database BC (20-0)" -DatabaseServer localhost -DatabaseInstance BCDEMO -ApplicationInsightsConnectionString 'InstrumentationKey=11111111-2222-3333-4444-555555555555;IngestionEndpoint=https://westeurope-1.in.applicationinsights.azure.com/'
Mount-NAVTenant -ServerInstance BC200 -Tenant tenant1 -DatabaseName "Demo Database BC (20-0)" -DatabaseServer localhost -DatabaseInstance BCDEMO -ApplicationInsightsKey 11111111-2222-3333-4444-555555555555
If you use the same Azure Application Insights resource for multiple environments, consider also using the AadTenantId parameter to distinguish tenants in telemetry.
For on-premises Docker sandbox environments
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 multi-tenant container, it's used on the default tenant.
New-BcContainer ` -accept_eula ` -updateHosts ` -artifactUrl (Get-BCArtifactUrl -country us) ` -applicationInsightsKey "11111111-2222-3333-4444-555555555555"
You can specify the same or another key when creating more tenants:
New-BcContainerTenant -tenantId "additional" -applicationInsightsKey "11111111-2222-3333-4444-555555555555"
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.
To assign, 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 .
- To assign or change the telemetry ID, choose Set field to random GUID > OK.
- To clear the telemetry ID, choose Set field to null GUID > OK.
We recommend that a telemetry ID is assigned to all users to make it possible to troubleshoot situations that happened in the past using telemetry.
Cleaning up settings
If the Azure Application Insights resource is tied to your partner account, and you end the relationship with a customer where you have set up telemetry based on your account's instrumentation key, you must remove the instrumentation key while you still have access to that customer's Business Central administration center.
It is also considered good practice to change all user telemetry IDs at the end of the relationship with the customer. This will remove traceability to users for all data in the Azure Application Insights resource.