Turn environment telemetry on or off

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.

Note

For app/extension telemetry, see Sending Extension Telemetry to Azure Application Insights.

Get started (set up Azure Application Insights)

1. If you don't already have one, get a subscription to Microsoft Azure.

2. Sign in to the Azure portal.

3. Create an Azure Application Insights resource by following the guidelines at Workspace-based Application Insights resources.

   Important

   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.

   Tip

   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.

4. 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.

     Note

     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.

     Note

     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.

Video guidance

The following video summarizes how to store Business Central telemetry in Azure Application Insights.

Turn on 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 turn on 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 turn on 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 information about using the admin center API, go to Put AppInsights key.

Video guidance

The following video shows how to turn on telemetry for online environments.

From the admin center

1. In the Business Central administration center, select Environments, and then select the environment that you want to change.

   Important

   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.

2. On the Environment page, the Application Insights Key field shows if the environment already uses application insights.

   To turn on 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.

   Note

   In version 15 and 16, to turn on telemetry, choose the Application Insights Key action, and then specify the instrumentation key.

3. 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=aaaaaaaa-0b0b-1c1c-2d2d-333333333333;IngestionEndpoint=https://westeurope-1.in.applicationinsights.azure.com/'

For more information, see Configuring Business Central Server.

For on-premises environments (multitenant mode)

For a multitenant server instance of Business Central on-premises, turn on telemetry on a per-tenant basis when you mount tenants on the Business Central Server instance.

The Mount-NAVTenant cmdlet includes the -ApplicationInsightsConnectionString and -ApplicationInsightsKey parameters. For example:

Mount-NAVTenant -ServerInstance BC200 -Tenant tenant1 -DatabaseName "Demo Database BC (20-0)" -DatabaseServer localhost -DatabaseInstance BCDEMO -AadTenantId 'MyAadTenantId' -EnvironmentName 'MyEnvironmentName' -EnvironmentType Production -ApplicationInsightsConnectionString 'InstrumentationKey=aaaaaaaa-0b0b-1c1c-2d2d-333333333333;IngestionEndpoint=https://westeurope-1.in.applicationinsights.azure.com/'

Or

Mount-NAVTenant -ServerInstance BC200 -Tenant tenant1 -DatabaseName "Demo Database BC (20-0)" -DatabaseServer localhost -DatabaseInstance BCDEMO -EnvironmentName 'MyEnvironmentName' -EnvironmentType Sandbox -ApplicationInsightsKey aaaabbbb-0000-cccc-1111-dddd2222eeee

If you use the same Azure Application Insights resource for multiple environments, consider also using the parameters AadTenantId, EnvironmentName, and EnvironmentType 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 "aaaabbbb-0000-cccc-1111-dddd2222eeee" 

You can specify the same or another key when creating more tenants:

New-BcContainerTenant -tenantId "additional" -applicationInsightsKey "aaaabbbb-0000-cccc-1111-dddd2222eeee" 

Turn off telemetry on environments

To turn off having telemetry sent from environments, follow the instructions above for turning on telemetry, but set the Azure Application Insights connection string or instrumentation key to a blank value.

Troubleshooting telemetry setup

If you set up telemetry but don't get any data in Azure Application Insights, then take a look at these common mistakes that others made.

1. Check that you used the correct Azure Application Insights connection string.
2. Check that you enabled telemetry in the correct environment.
3. (Only for on-premises) Check that network traffic from Business Central to Azure Application Insights isn't blocked by a firewall or some software that is filtering outgoing calls to the ingestion endpoint.
4. (Only for on-premises) Similar to checking network traffic, check if you block domain name service (DNS) to lookup Azure resources.
5. (Only for on-premises) Did you restart Business Central Server unstances after enabling telemetry?

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 to be included in traces logged in Application Insights. This ID is a special globally unique identifier (GUID) that's only used for telemetry. It appears in the user_Id column in certain events, but not all.

In Business Central version 24 and later, the server and the browser components align on the GUIDs logged to the user_Id column in the traces and pageViews tables. For versions before version 24, only events logged by the Business Central server emit in the context of a user session.

The Business Central server initially sets the telemetry ID for a user 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:

1. Sign in to Business Central using an administrator account.

2. Choose the icon, enter Users, and then choose the related link.

3. Choose the user name to open the User Card page.

4. 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.

Note

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.

For more information on how to query the user_Id in telemetry, see KQL example - following telemetry events for a user.

Cleaning up settings

If the Azure Application Insights resource is tied to your partner account, and you end the relationship with a customer where telemetry is set up 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's good practice to change all user telemetry IDs at the end of the relationship with the customer. This practice removes traceability to users for all data in the Azure Application Insights resource.

See also

Sending Extension Telemetry to Azure Application Insights
Environment Telemetry
Analyze Telemetry with KQL
Telemetry FAQ
Telemetry overview