{"title":"Creating custom telemetry events for Application Insights","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-instrument-application-for-telemetry-app-insights/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-instrument-application-for-telemetry-app-insights, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-instrument-application-for-telemetry-app-insights","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Add custom telemetry events to Business Central extensions with Session.LogMessage, choose their scope, and define dimensions for Application Insights.","date":"2026-11-17","meta":{"topic":"concept-article"},"outline":[{"level":1,"title":"Creating custom telemetry events for Application Insights","slug":"creating-custom-telemetry-events-for-application-insights","at":0,"chars":13462},{"level":2,"title":"The scope for extension telemetry","slug":"the-scope-for-extension-telemetry","at":856,"chars":914},{"level":2,"title":"Create a custom telemetry event","slug":"create-a-custom-telemetry-event","at":1770,"chars":6459},{"level":3,"title":"Using a dictionary","slug":"using-a-dictionary","at":2392,"chars":311},{"level":3,"title":"Using dimension overloads","slug":"using-dimension-overloads","at":2703,"chars":334},{"level":3,"title":"Setting the parameters","slug":"setting-the-parameters","at":3037,"chars":2837},{"level":3,"title":"Default dimensions in CustomDimensions","slug":"default-dimensions-in-customdimensions","at":5874,"chars":2355},{"level":2,"title":"Best practices for designing telemetry for your app/extensions","slug":"best-practices-for-designing-telemetry-for-your-appextensions","at":8229,"chars":2778},{"level":3,"title":"Convention for Message column","slug":"convention-for-message-column","at":9145,"chars":605},{"level":3,"title":"Convention for eventId dimension","slug":"convention-for-eventid-dimension","at":9750,"chars":583},{"level":3,"title":"Conventions for dimension names","slug":"conventions-for-dimension-names","at":10333,"chars":674},{"level":2,"title":"Custom telemetry examples","slug":"custom-telemetry-examples","at":11007,"chars":1067},{"level":2,"title":"Conditions on when events are sent","slug":"conditions-on-when-events-are-sent","at":12074,"chars":918},{"level":3,"title":"Using DataClassification for privacy","slug":"using-dataclassification-for-privacy","at":12112,"chars":452},{"level":3,"title":"Diagnostic trace level (on-premises only)","slug":"diagnostic-trace-level-on-premises-only","at":12564,"chars":428},{"level":2,"title":"Related information","slug":"related-information","at":12992,"chars":470}],"text":"# Creating custom telemetry events for Application Insights\n> APPLIES TO: Business Central 2020 release wave 2 and later\nThis article explains how to develop extensions to send custom telemetry trace events to Azure Application Insights for viewing and analyzing.\nYou can add AL code in extensions to emit messages about activities or operations that users do within the application. At runtime, the messages can be picked up by an Azure Application Insights resource, which you set up beforehand. In Azure Application Insights, the custom telemetry events are stored in the traces table.\n> TIP\n> Consider using the Feature usage module from the System Application for logging events from your extension instead of using raw Session.LogMessage calls as described in this article. See Using Feature telemetry<../administration/telemetry-feature-telemetry>.\n## The scope for extension telemetry\nTelemetry for Business Central can be defined in two places.\n In the app.json file of the extension.\n  See Set up telemetry in an extension<devenv-application-insights-for-extensions>.\n In the Business Central environment.\n  See Enabling Telemetry on Environments<../administration/telemetry-overview#enable>.\nWhen you create a custom telemetry trace signal, you can specify the scope of the event. The telemetry scope determines if the event is only sent to the Azure Application Insights resource specified in the extension's app.json or if the event is also sent to the Azure Application Insights resource of the environment where the extension is installed.\n![Shows how the scope property works in Business Central app telemetry]\n> NOTE\n> Having Azure Application Insights resources configured in your app.json is not required to define custom telemetry events in AL code.\n## Create a custom telemetry event\nTo create a custom telemetry event, use the LogMessage method in AL code where you want to trigger the signal. The LogMessage method defines the information that is sent to Azure Application Insights for a specific operation or activity.\nThere are two variations of the LogMessage method. The difference is that one method uses a dictionary object to define custom dimensions for the trace signal. The other method includes two overloads so you don't have to construct a dictionary. You can use these methods in any object, trigger, or method.\nThe methods have the following signatures:\n### Using a dictionary\nThe LogMessage method for using a dictionary for dimensions has the following signature:\n```al\nSession.LogMessage(EventId: Text, Message: Text, Verbosity: Verbosity, DataClassification: DataClassification, TelemetryScope: TelemetryScope, CustomDimensions: Dictionary of [Text, Text])\n```\n### Using dimension overloads\nThe LogMessage method for using dimension overloads has the following signature:\n```al\nSession.LogMessage(EventId: Text, Message: Text, Verbosity: Verbosity, DataClassification: DataClassification, TelemetryScope: TelemetryScope, Dimension1: Text, Value1: Text [, Dimension2: Text] [, Value2: Text])\n```\n### Setting the parameters\nUse the parameters to build the dimensions, or columns, that show for the trace in Azure Application Insights. Message and Verbosity appear as general dimensions. TelemetryScope controls routing and isn't emitted as a dimension. The event ID, data classification, and custom dimensions appear in customDimensions.\nParameter|Description|Dimension\nEventID|A text string that assigns an identifier to the telemetry trace signal. The tag can consist of letters, numbers, and special characters. Try to make your tags unique. For example, use at least eight characters or a prefix, like Cronus-0001 and Cronus-0002. Business Central prefixes the emitted value with AL, so `Cronus-0001` appears as `ALCronus-0001`.|eventId\nMessage|A text string that specifies the descriptive message for the telemetry trace signal.|message\nVerbosity*<#*>|An enumeration that specifies the severity level of the telemetry trace signal. The value can be Critical, Error, Warning, Normal, or Verbose.|severityLevel<br /><br />`4`=Critical<br />`3`=Error<br />`2`=Warning<br />`1`=Normal <br />`0`=Verbose<br />\nDataClassification*<#*>|A DataClassification data type that assigns a classification to the telemetry trace signal. Learn more in the Business Central developer documentation<../developer>.|alDataClassification\nTelemetryScope|Scope of emitting the telemetry. <ul><li>ExtensionPublisher sends the custom signal only to the Azure Application Insights resource specified in the extension's app.json file</li><li>All sends the custom signal to the Azure Application Insights resource specified in the extension's app.json file and on the environment. </li></ul>|Not emitted\nCustomDimensions|A dictionary of text that defines the custom dimensions for the trace signal in Application Insights. Several custom dimensions are included in traces by default. See #default-dimensions-in-customdimensions.|customDimensions\nDimension1|A text string that specifies the name of the custom dimension.|Custom dimension key, prefixed with al\nValue1|A text string that specifies the value of Dimension1.|Value of the corresponding custom dimension\nDimension2|A text string that specifies the name of the custom dimension.|Custom dimension key, prefixed with al\nValue2|A text string that specifies the value of Dimension2.|Value of the corresponding custom dimension\n> TIP\n> In Azure Application Insights, the name of custom dimension will be prefixed with al. For example, if the dimension string you define in code is Result, then in the trace logged in Azure Application Insights, the name appears as alResult. It is therefore considered good practice to use PascalCasing for your dimension names. This way, your dimension names in Azure Application Insights will conform to the standard naming of dimensions in Business Central telemetry.\n### Default dimensions in CustomDimensions\nThe following table explains the default dimensions that are automatically included in CustomDimensions for telemetry events sent from AL code.\nDimension|Description or value\naadTenantId|Specifies the Microsoft Entra tenant ID, when configured.\nalCallerAppName|Specifies the name of the extension that emitted the telemetry signal to Application Insights.\nalCallerPublisher|Specifies the publisher of the extension that emitted the telemetry signal to Application Insights.\nalCallerAppVersion|Specifies the version number of the extension that emitted the telemetry signal to Application Insights.\nalObjectId|Specifies the ID of the object that called the LOGMESSAGE method.\nalObjectName|Specifies the name of the object that called the LOGMESSAGE method.\nalObjectType|Specifies the type of the object that called the LOGMESSAGE method, like PageExtension for a page extension object.\nclientType|Specifies the type of client connection that ran the LogMessage method, such as Background or WebClient. The value uses the server connection type name, which can differ from the AL ClientType value.\ncompanyName|Specifies the company in Business Central.\ncomponent|Dynamics 365 Business Central Server.\ncomponentVersion|Specifies the version number of the component that emits telemetry. See the component dimension.\nenvironmentName|Specifies the name of the tenant environment. See Managing Environments<../administration/tenant-admin-center-environments>.\nenvironmentType|Specifies the environment type for the tenant, such as Production, Sandbox, Trial. See ../administration/tenant-admin-center-environments#types-of-environments.\nextensionName|Specifies the name of the extension that called the LOGMESSAGE method.\nextensionId|Specifies the ID of the extension that called the LOGMESSAGE method.\nextensionPublisher|Specifies the publisher of the extension that called the LOGMESSAGE method.\nextensionVersion|Specifies the version of the compiled extension.\ndeprecatedKeys|A comma-separated list of all the keys that have been deprecated. The keys in this list are still supported but will eventually be removed in the next major release. We recommend that you update any queries that use these keys to use the new key name.\ntelemetrySchemaVersion|Specifies the version of the Business Central telemetry schema.\n## Best practices for designing telemetry for your app/extensions\nWhen the Business Central product team designed the partner telemetry feature, we built the following characteristics into it:\n Telemetry event definitions must be treated as an API. Changing custom dimensions is a breaking change (someone might have built reporting or alerting on top of it).\n Telemetry events must be discoverable in docs. If you see something in telemetry, it should be easy to learn more about it in documentation. We added the custom dimension eventId because of this. It's good practice to keep eventIds unique, also across apps/extensions.\n Documented: each telemetry event has good documentation, preferably with guidance on how to react on this event.\n Actionable (if possible): before we add a new telemetry event, we ask \"what can a customer/partner do with this?\" If no good answers come to mind, we don't add the event.\n### Convention for Message column\nTry to use the \"Object ActionInPastTense\" pattern for the Message part of a LogMessage call. This makes reading the output from a KQL query ordered by timestamp easier.\nHere are some examples from the built-in Business Central telemetry:\n Web Service Called\n Report canceled: {report name}\n Extension published: {Extension name}\nConsider also adding some of the dimension values into the message itself. This makes it easier to browse the events by message column alone (no need to open up custom dimensions for every single event to see, e.g., which page it was about).\n### Convention for eventId dimension\nIt's considered good practice to use unique eventID values for each LogMessage call in your code (also when you use the feature telemetry module from the System Application). When analyzing data from your telemetry, using unique eventIDs makes it easy for you to identify where in the code the telemetry was emitted from.\nAlso, consider using a prefix unique to your app/extension. This helps consumers when your events are emitted to per-environment telemetry, where the environment admin might get telemetry data from multiple apps/extensions.\n### Conventions for dimension names\nWhen logging events to Azure Application Insights, Business Central server prefixes the name of custom dimension keys from AL with the string al. For example, if the dimension key you define in code is Result, then in the event logged in Azure Application Insights, the key name appears as alResult.\nIt's therefore considered good practice to use PascalCasing for your dimension key names. This way, your dimension key names in Azure Application Insights conform to the standard naming of dimension keys in Business Central telemetry.\nAlso, don't use dimension key names with spaces in them. It makes KQL queries more difficult to write.\n## Custom telemetry examples\nThe following code snippets create simple telemetry events from AL. They create a critical-level telemetry signal that is scoped to the app/extension publisher. For a simple test of this code, add it to the OnRun trigger of a codeunit, and then run the codeunit.\nUsing a dictionary:\n```al\nvar\n  CustDimension: Dictionary of [Text, Text];\nbegin\n  CustDimension.Add('Result', 'failed');\n  CustDimension.Add('Reason', 'critical error in code');\n  LogMessage(\n    'MyExt-0001',\n    'Critical error happened: MyExt module 1',\n    Verbosity::Critical,\n    DataClassification::SystemMetadata,\n    TelemetryScope::ExtensionPublisher, // this event will only go to app telemetry\n    CustDimension\n  );\nend;\n```\nUsing an overload:\n```al\nbegin\n  LogMessage(\n    'MyExt-0002',\n    'Critical error happened: MyExt module 2',\n    Verbosity::Critical,\n    DataClassification::SystemMetadata,\n    TelemetryScope::ExtensionPublisher, // this event will only go to app telemetry\n    'Result', 'failed',\n    'Reason', 'critical error in code'\n  );\nend;\n```\n## Conditions on when events are sent\n### Using DataClassification for privacy\nIn version 29, events classified as SystemMetadata or OrganizationIdentifiableInformation can be sent to Azure Application Insights. Events with personal or restricted data classifications aren't sent. During development of your extension, it's good practice to have a privacy review of the use of LogMessage calls to ensure that customer data isn't mistakenly leaked into Azure Application Insights resources.\n### Diagnostic trace level (on-premises only)\nFor Business Central on-premises, the Diagnostic Trace Level setting on the Business Central Server instance controls which signals are sent, based on their severity level.\nIf you set the TraceLevel to Warning, the system doesn't send Normal and Verbose signals to Application Insights. See Configuring Business Central Server - General<../administration/server-instance-settings>.\n## Related information\nUsing feature telemetry<../administration/telemetry-feature-telemetry>\nmethods-auto/session/session-logmessage-string-string-verbosity-dataclassification-telemetryscope-dictionary[text,text]-method\nmethods-auto/session/session-logmessage-string-string-verbosity-dataclassification-telemetryscope-string-string-string-string-method\ndevenv-instrument-application-for-telemetry\nMonitoring and analyzing telemetry<../administration/telemetry-overview>"}