{"title":"Analyzing extension update telemetry","url":"https://jonas-paprotka.de/docs/dev-itpro/administration/telemetry-extension-update-trace/","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/administration/telemetry-extension-update-trace, 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/administration/telemetry-extension-update-trace","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":"Analyze Business Central extension update telemetry to investigate upgrade code failures and track upgrade tags used during extension upgrades.","date":"2026-11-17","meta":{"topic":"concept-article"},"outline":[{"level":1,"title":"Analyzing extension update telemetry","slug":"analyzing-extension-update-telemetry","at":0,"chars":6737},{"level":2,"title":"Extension update failed: exception raised in extension","slug":"extension-update-failed-exception-raised-in-extension","at":1179,"chars":2518},{"level":3,"title":"General dimensions","slug":"general-dimensions","at":1324,"chars":215},{"level":3,"title":"Custom dimensions","slug":"custom-dimensions","at":1539,"chars":2158},{"level":2,"title":"Upgrade tag searched for","slug":"upgrade-tag-searched-for","at":3697,"chars":1462},{"level":3,"title":"General dimensions","slug":"general-dimensions-1","at":3861,"chars":119},{"level":3,"title":"Custom dimensions","slug":"custom-dimensions-1","at":3980,"chars":1179},{"level":2,"title":"Upgrade tag set","slug":"upgrade-tag-set","at":5159,"chars":1372},{"level":3,"title":"General dimensions","slug":"general-dimensions-2","at":5328,"chars":110},{"level":3,"title":"Custom dimensions","slug":"custom-dimensions-2","at":5438,"chars":1093},{"level":2,"title":"Related information","slug":"related-information","at":6531,"chars":206}],"text":"# Analyzing extension update telemetry\nINTRODUCED IN: Exception telemetry was introduced in Business Central 2020 release wave 1, version 16.2. Upgrade tag telemetry was introduced in Business Central 2021 release wave 1, version 18.1.\nExtension upgrade telemetry gathers information about operations that can occur during extension upgrades:\n Upgrade code failures\n  The telemetry provides information about exceptions that are thrown by code run by upgrade codeunits. The trace events include the following information:\n   The codeunit that threw the exception.\n   AL stack trace.\n   Exception message.\n Upgrade tag usage\n  The telemetry provides information about calls to the AL methods HasUpgradeTag and SetUpgradeTag. These methods are provided by codeunit 9999 Upgrade Tag in the System Application extension. Upgrade tags are used to control when upgrade code is run. See ../developer/devenv-upgrading-extensions#using-upgrade-tags-to-control-upgrade-code. This data can help you identify, troubleshoot, and resolve issues in upgrade code.\nThe telemetry helps you troubleshoot and resolve code issues that block the data upgrade of per-tenant and Marketplace extensions.\n## Extension update failed: exception raised in extension\nOccurs when an extension upgrade fails because of an exception in an upgrade codeunit.\n### General dimensions\nDimension|Description or value\nmessage|Extension Update Failed: exception raised in extension {extensionName} by {companyName} (updating to version {extensionTargetedVersion})\nseverityLevel|3\n### Custom dimensions\nDimension|Description or value\neventId|RT0010\nalObjectId|The ID of the AL object that was run by request\nalStackTrace|The stack trace in AL\ncompanyName|The display name of the Business Central company that was used at time of execution\nextensionName|The name of the extension that was being upgraded\nextensionId|The AppID of the extension that was being upgraded\nextensionTargetedVersion|The new version of the extension being upgraded\nextensionVersion|The version of the extension being upgraded to\nfailureReason|The exception that was thrown by the upgrade code. Some exception messages can contain customer data. As a precaution, Business Central only emits information that's classified as SystemMetadata<../developer/devenv-instrument-application-for-telemetry-app-insights#using-dataclassification-for-privacy>. Exception messages that contain other data classifications, like customer data, aren't shown. Instead, the following message is shown: \"Message not shown because the NavBaseException(string, Exception, bool) constructor was used.\"\nfailureType|DataUpdate\nCommon custom dimensions\nThe following table explains other custom dimensions that are common to all extension update traces.\nDimension|Description or value\naadTenantId|The Microsoft Entra tenant ID that's used for Microsoft Entra authentication. For on-premises, if you aren't using Microsoft Entra authentication, this value is common.\ncomponent|Dynamics 365 Business Central Server\ncomponentVersion|The version number of the component that emits telemetry (see the component dimension)\nenvironmentName|The name of the tenant environment. See Managing environments<tenant-admin-center-environments>. This dimension isn't included for Business Central on-premises environments.\ndeprecatedKeys|A comma-separated list of keys that have been deprecated. We recommend that you update any queries that use these keys to use the new key names.\nenvironmentType|The environment type for the tenant, such as Production, Sandbox, Trial. See tenant-admin-center-environments#types-of-environments.\ntelemetrySchemaVersion|The version of the Business Central telemetry schema\n## Upgrade tag searched for\nOccurs when the HasUpgradeTag method in codeunit 9999 Upgrade Tag checks for a tag during an extension upgrade and the tag isn't found.\n### General dimensions\nDimension|Description or value\nmessage|Upgrade tag searched for: {alUpgradeTag}\nseverityLevel|1\n### Custom dimensions\n|Dimension|Description or value|\n|eventId|AL0000EJ9|\n|alCategory|ALUpgrade|\n|alCompanyName|The company for which the upgrade tag was checked. An empty value indicates a database-wide tag.|\n|alDataClassification|OrganizationIdentifiableInformation|\n|alObjectId|9996|\n|alObjectName|Upgrade Tag Impl.|\n|alUpgradeTag|The upgrade tag that was input to the HasUpgradeTag method|\n|alExecutionContext|The context that the upgrade code was running in. The dimension has the following values:<ul><li> Install indicates the code was run during the installation of the extension.</li><li>Upgrade indicates the code was run during the upgrade of the extension.</li><li>Normal indicates the code was run by an operation other than extension installation or upgrade. For example, when a new company was added.</li></ul>|\n|alValue|false, because this event is emitted when the upgrade tag isn't found.|\n|extensionName|System Application|\n|extensionId|The ID of the System Application extension|\n|extensionPublisher|The publisher of the System Application extension|\n|extensionVersion|The version of the System Application extension|\n|See common custom dimensions<#other>||\n## Upgrade tag set\nOccurs when codeunit 9999 Upgrade Tag sets an upgrade tag. This event can also occur outside an extension upgrade, such as when a company is created.\n### General dimensions\nDimension|Description or value\nmessage|Upgrade tag set: {alUpgradeTag}\nseverityLevel|1\n### Custom dimensions\n|Dimension|Description or value|\n|eventId|AL0000EJA|\n|alCategory|ALUpgrade|\n|alCompanyName|The company for which the upgrade tag was set. An empty value indicates a database-wide tag.|\n|alDataClassification|OrganizationIdentifiableInformation|\n|alObjectId|9996|\n|alObjectName|Upgrade Tag Impl.|\n|alUpgradeTag|The upgrade tag that was set by the SetUpgradeTag method.|\n|alExecutionContext|The context that the upgrade code was running in. The dimension has the following values:<ul><li> Install indicates the code was run during the installation of the extension.</li><li>Upgrade indicates the code was run during the upgrade of the extension.</li><li>Normal indicates the code was run by an operation other than extension installation or upgrade. For example, when a new company was added.</li></ul>|\n|extensionName|System Application|\n|extensionId|The ID of the System Application extension|\n|extensionPublisher|The publisher of the System Application extension|\n|extensionVersion|The version of the System Application extension|\n|See common custom dimensions<#other>||\n## Related information\n../developer/devenv-upgrading-extensions\nMonitoring and Analyzing Telemetry<telemetry-overview>\nEnable Sending Telemetry to Application Insights<telemetry-enable-application-insights>"}