Edit

Share via

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. For more information, see 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:

Field Description or value
user_Id The 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

Dimension Description or value
aadTenantId Specifies 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.
alObjectId Specifies the ID of the page object that was opened.
alObjectName Specifies the name of the page object that was opened.
appId Specifies the Id of the app/extension that was opened.
appName Specifies the name of the app/extension that the page belongs to.
appPublisher Specifies the publisher of the app/extension that the page belongs to.
appVersion Specifies the version of the app/extension that the page belongs to.
clientType Specifies the type of client that opened the session, such as Background or Web. For a list of the client types, see ClientType Option Type.
companyName The current company name.
controlAddInName The name of the control add-in from which the exception was thrown.
deviceScreenResolution Specifies 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.
environmentName Specifies the name of the tenant environment. Learn more in Managing Environments.
environmentType Specifies the environment type for the tenant, such as Production or Sandbox. Learn more in Environment Types.
eventId CL0005
hostType Specifies the host that loads the page.
  • Device App
    The page was loaded by a Business Central mobile app, from a desktop, tablet, or phone.
  • Office add-in
    The page was loaded by Office application, like Excel or Outlook.
  • 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.
  • Shim Browser
    The page was loaded by the UWP (Universal Windows Platform) application.
  • Browser
    The page was loaded by web browser, like Microsoft Edge or Google Chrome.

All error information is stored in the following properties:

Property Description or value
problemId The 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.
type The type of the error that occurred.
assembly The web assembly where the error occurred.
method The JavaScript method where error occurred.
outerType The top level error type on the stack trace.
outerMessage The top level error message on the stack trace.
outerAssembly The top level assembly on the stack trace.
outerMethod The top level method on the stack trace.
innermostType The inner most error type on the stack trace.
innermostMessage The inner most error message on the stack trace.
innermostAssembly The inner most assembly on the stack trace.
innermostMethod The inner most method on the stack trace.
details JSON 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.screenRes
, hostType = customDimensions.hostType
// 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