Analyzing client control add-in exception telemetry

APPLIES TO: Business Central 2025 release wave 1 (v26) and later.

Client control add-in exception telemetry gathers data about exceptions thrown in control add-ins. Each event tells you the type of exception, in which add-in it was triggered, information about the user's environment, and more.

Use the data to gather statistics about exceptions in control add-ins for troubleshooting and error mitigation.

Note

In Azure Application Insights, telemetry about client add-in exceptions is logged to the exceptions table and not the traces table like other Business Central traces. This also means that you can use the built-in pages in the Failures page of the Azure Application Insights for troubleshooting. Learn more in Failures and Performance views.

Exception raised inside a control add-in

Occurs when an exception was raised inside a control add-in.

General dimensions

The exceptions table is a built-in table in Azure Application Insights. Here are some of the fields most used in analysis of the signal:

FieldDescription or value
user_IdThe user telemetry ID for the user. From the user card, you can use user_Id to identify the user who triggered this telemetry event. Learn more in Assign a telemetry ID to users.

Custom dimensions

DimensionDescription or value
aadTenantIdSpecifies the Microsoft Entra tenant ID used for Microsoft Entra authentication. For on-premises, if you aren't using Microsoft Entra authentication, this value is common.
alObjectIdSpecifies the ID of the page object that was opened.
alObjectNameSpecifies the name of the page object that was opened.
alObjectTypeControlAddIn
appIdSpecifies the Id of the app/extension that was opened.
appNameSpecifies the name of the app/extension that the page belongs to.
appPublisherSpecifies the publisher of the app/extension that the page belongs to.
appVersionSpecifies the version of the app/extension that the page belongs to.
clientTypeSpecifies the type of client that opened the session, such as Background or Web. For a list of the client types, see ClientType Option Type.
companyNameThe current company name.
controlAddInNameThe name of the page control that hosts the control add-in from which the exception was thrown.
deviceScreenResolutionSpecifies the display resolution of the device that opened the page. The value is given as {width}×{height}, with the units in pixels. For example, 1024×768 means the width is 1024 pixels and the height is 768 pixels.
environmentNameSpecifies the name of the tenant environment. Learn more in Managing Environments.
environmentTypeSpecifies the environment type for the tenant, such as Production or Sandbox. Learn more in Environment Types.
eventIdCL0005
hostTypeSpecifies the host that loads the page. <ul><li>Device App
The page was loaded by a Business Central mobile app, from a desktop, tablet, or phone. </li><li>Office add-in
The page was loaded by Office application, like Excel or Outlook.</li><li>Designer
The page was loaded by the in-client designer, used for changing page layout. The designer has different modes. Each mode provides a different level of page customization, as specified in the designerLevel dimension.</li><li>Shim Browser
The page was loaded by the UWP (Universal Windows Platform) application.</li><li>Browser
The page was loaded by web browser, like Microsoft Edge or Google Chrome. </li></ul>

All error information is stored in the following properties:

PropertyDescription or value
problemIdThe problem ID identifies where the exception was thrown in code. It's used for exceptions grouping. Typically, it's a combination of an exception type and a function from the call stack.
typeThe type of the error that occurred.
assemblyThe web assembly where the error occurred.
methodThe JavaScript method where the error occurred.
outerTypeThe top level error type on the stack trace.
outerMessageThe top level error message on the stack trace.
outerAssemblyThe top level assembly on the stack trace.
outerMethodThe top level method on the stack trace.
innermostTypeThe inner most error type on the stack trace.
innermostMessageThe inner most error message on the stack trace.
innermostAssemblyThe inner most assembly on the stack trace.
innermostMethodThe inner most method on the stack trace.
detailsJSON structure with more information, such as stack traces.

Sample KQL code (control add-in exceptions)

This KQL code can help you get started analyzing client add-in exceptions:

exceptions
| where timestamp > ago(60d) // adjust as needed
| where customDimensions.eventId == 'CL0005'
| order by timestamp desc
| take 5
| project timestamp
// in which environment/company did it happen
, aadTenantId = customDimensions.aadTenantId
, environmentName = customDimensions.environmentName
, environmentType = customDimensions.environmentType
, companyName = customDimensions.companyName
// in which extension/app
, appId = customDimensions.appId
, appName = customDimensions.appName
, appPublisher = customDimensions.appPublisher
, appVersion = customDimensions.appVersion
// in which object
, alObjectId = customDimensions.alObjectId
, alObjectName = customDimensions.alObjectName
, alObjectType = customDimensions.alObjectType
// which add-in
, controlAddInName = customDimensions.controlAddInName
// which client (browser, tablet, phone, ...)
, clientType = customDimensions.clientType
, hostType = customDimensions.hostType
// device info
, deviceScreenResolution = customDimensions.deviceScreenResolution
// error information
, problemId
, type
, assembly
, method
, outerType
, outerMessage
, outerAssembly
, outerMethod
, innermostType
, innermostMessage
, innermostAssembly
, innermostMethod
, details // json structure with more information, such as stack traces
// which user got the error
, usertelemetryId = user_Id

Control add-in object
Monitoring and Analyzing Telemetry
Enable Sending Telemetry to Application Insights