Analyzing environment validation telemetry

APPLIES TO: Business Central online

Incompatible partner apps (per-tenant extensions) can block upgrades to the next major version of Business Central if they can't compile on that version. The Business Central service proactively validates all environments regularly against the next release. If an environment isn't ready to be updated, then the Business Central service sends an email to the administrator and, starting from September 2023, emits telemetry on these validations.

With this telemetry, partners can monitor environments for the customers and set up alerts so that they know up front which customers need help prior to updating to the next major version of Business Central.

Failed operations result in a trace log entry that includes a reason for the failure.

The validation flow is as follows:

First, environment validation started (LC0220).
For each extension (main + dependent extensions)
        Extension validation started (LC0224)
        Either
                Extension validation completed successfully (LC0225)
        or
                Extension Validation diagnostic reported (LC0210)
                Extension validation completed with failures (LC0226)
Finally,
either
        Environment validation completed successfully (LC0222)
or
        Environment validation completed with failures (LC0223)
        Environment diagnostic reported (LC0221 and/or LC0227)

Environment validation started (LC0220)

Occurs when a new validation attempt is started for the environment.

General dimensions

DimensionDescription or value
messageEnvironment validation started: environment {environmentName} target build version {targetVersion}

{environmentName} indicates the name of the environment.

{targetVersion} indicates the new version that the environment is validated against.

Custom dimensions

DimensionDescription or value
eventIdLC0220
environmentTenantAADSpecifies 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.
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.
targetVersionSpecifies the version of Business Central that we are validating against. Typically the next major version.

Environment validation diagnostic reported (LC0221)

Occurs during the environment validation to report diagnostics related to the validation itself. For example, it could be that there are duplicate object IDs across extensions in the environment. This signal isn't necessarily an error, but can also be a warning or information.

General dimensions

DimensionDescription or value
messageDiagnostic reported on validation of environment {environmentId} for target build version {targetVersion}
severityLevel1 for information, 2 for warning, 3 for error

Custom dimensions

DimensionDescription or value
eventIdLC0221
environmentTenantAADSpecifies 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.
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.
targetVersionSpecifies the version of Business Central that we are validating against. Typically the next major version.
diagnosticCodeSpecifies a diagnostics code emitted by the AL compiler. For more information, see AL compiler diagnostics
diagnosticMessageSpecifies a diagnostics message emitted by the AL compiler.
diagnosticSeveritySpecifies the severity of diagnostics message emitted by the AL compiler, such as Error or Warning.

Extension validation started (LC0224)

Occurs for each extension in the environment.

General dimensions

DimensionDescription or value
messageExtension validation started: extension {extensionName} version {extensionVersion} by {extensionPublisher} ({extensionId})

{extensionName} indicates the name of the extension.

{extensionVersion} indicates the version of the extension.

{extensionPublisher} indicates the publisher of the extension.

{extensionId} indicates the ID of the extension.

Custom dimensions

DimensionDescription or value
eventIdLC0224
environmentTenantAADSpecifies 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.
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.
extensionNameSpecifies the name of the extension that was to be validated.
extensionIdSpecifies the ID of the extension/app.
extensionPublisherSpecifies the publisher of the extension/app.
extensionVersionSpecifies the version of the extension.

Extension validation completed successfully (LC0225)

Occurs if the extension validated successfully on the next major of Business Central.

General dimensions

DimensionDescription or value
messageExtension validation completed successfully: extension {extensionName} version {extensionVersion} by {extensionPublisher} ({extensionId})

{extensionName} indicates the name of the extension.

{extensionVersion} indicates the version of the extension.

{extensionPublisher} indicates the publisher of the extension.

{extensionId} indicates the id of the extension.

Custom dimensions

DimensionDescription or value
eventIdLC0225
environmentTenantAADSpecifies 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.
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.
extensionNameSpecifies the name of the extension that was to be validated.
extensionIdSpecifies the ID of the extension/app.
extensionPublisherSpecifies the publisher of the extension/app.
extensionVersionSpecifies the version of the extension.
targetVersionSpecifies the version of Business Central that we are validating against. Typically the next major version.

Extension validation diagnostic reported (LC0210)

Occurs if something wasn't right when validating the extension on the next major of Business Central.

General dimensions

DimensionDescription or value
messageValidation diagnostic reported: extension {extensionName} version {extensionVersion} by {extensionPublisher} ({extensionId})

{extensionName} indicates the name of the extension.

{extensionVersion} indicates the version of the extension.

{extensionPublisher} indicates the publisher of the extension.

{extensionId} indicates the id of the extension.

Custom dimensions

DimensionDescription or value
eventIdLC0210
environmentIdSpecifies 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.
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.
extensionNameSpecifies the name of the extension that was to be validated.
extensionIdSpecifies the ID of the extension/app.
extensionPublisherSpecifies the publisher of the extension/app.
extensionVersionSpecifies the version of the extension.
diagnosticCodeSpecifies a diagnostics code emitted by the AL compiler. For more information, see AL compiler diagnostics
diagnosticMessageSpecifies a diagnostics message emitted by the AL compiler.
diagnosticSeveritySpecifies the severity of diagnostics message emitted by the AL compiler, such as Error or Warning.
diagnosticSourceLocationSpecifies where in the app code the AL compiler emitted the diagnostics.
diagnosticSourcePathSpecifies where in a file in the app the AL compiler emitted the diagnostics.
submissionOperationIdThe operation ID for the validation submission of the app.

Sample KQL code (extension validation diagnostic reported)

This KQL code can help you get started analyzing validation failures for an app on the next major of Business Central:

// Extension Validation diagnostic reported (LC0210)
traces
| where customDimensions has "LC0210"
| where customDimensions.eventId == "LC0210"
| where timestamp > ago(30d) // adjust as needed
| project timestamp
// which environment is being validated
, aadTenantId = customDimensions.environmentId
, environmentName = customDimensions.environmentName
, environmentType = customDimensions.environmentType
// which extension/app is being validated
, extensionId = customDimensions.extensionId
, extensionPublisher = customDimensions.extensionPublisher
, extensionVersion = customDimensions.extensionVersion
, extensionName = customDimensions.extensionName
, mainExtension = customDimensions.mainExtension
// validation info
, diagnosticSourceLocation = customDimensions.diagnosticSourceLocation
, diagnosticMessage = customDimensions.diagnosticMessage
, diagnosticSourcePath = customDimensions.diagnosticSourcePath
, diagnosticCode = customDimensions.diagnosticCode
, diagnosticSeverity = customDimensions.diagnosticSeverity
, submissionOperationId = customDimensions.submissionOperationId

Extension validation completed with failures (LC0226)

Occurs if the extension validated with one or more failures on the next major of Business Central.

General dimensions

DimensionDescription or value
messageExtension validation completed with failures: extension {extensionName} version {extensionVersion} by {extensionPublisher} ({extensionId})

{extensionName} indicates the name of the extension.

{extensionVersion} indicates the version of the extension.

{extensionPublisher} indicates the publisher of the extension.

{extensionId} indicates the id of the extension.

Custom dimensions

DimensionDescription or value
eventIdLC0226
environmentTenantAADSpecifies 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.
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.
extensionNameSpecifies the name of the extension that was to be validated.
extensionIdSpecifies the ID of the extension/app.
extensionPublisherSpecifies the publisher of the extension/app.
extensionVersionSpecifies the version of the extension.
targetVersionSpecifies the version of Business Central that we are validating against. Typically the next major version.
failureReasonThe overall reason that the extension failed to validate on the new major of Business Central.

Sample KQL code (extension validation completed with failures)

This KQL code can help you get started analyzing validation failures for an app on the next major of Business Central:

// Extension validation completed with failures (LC0226)
traces
| where customDimensions has "LC0226"
| where customDimensions.eventId == "LC0226"
| where timestamp > ago(30d) // adjust as needed
| project timestamp
// which environment is being validated
, aadTenantId = customDimensions.environmentTenantAAD
, environmentName = customDimensions.environmentName
, environmentType = customDimensions.environmentType
// which extension/app is being validated
, extensionId = customDimensions.extensionId
, extensionName = customDimensions.extensionName
, extensionPublisher = customDimensions.extensionPublisher
, extensionVersion = customDimensions.extensionVersion
// validation info
, targetVersion = customDimensions.targetVersion
, failureReason = customDimensions.failureReason

Environment validation request completed successfully (LC0222)

Occurs if all extensions in the environment validated successfully on the next major of Business Central.

General dimensions

DimensionDescription or value
messageEnvironment validation request completed successfully for {environmentName} target build version {targetVersion}

{environmentName} indicates the name of the environment.

{targetVersion} indicates the new version that the environment is validated against.

Custom dimensions

DimensionDescription or value
eventIdLC0222
environmentTenantAADSpecifies 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.
environmentNameSpecifies the name of the tenant environment. Learn more in Managing Environments.
targetVersionSpecifies the version of Business Central that we are validating against. Typically the next major version.

Environment validation completed with failures (LC0223)

Occurs if one or more extensions in the environment failed to validate on the next major of Business Central.

General dimensions

DimensionDescription or value
messageEnvironment validation request completed with failures for environment {environmentName} target build version {targetVersion}

{environmentName} indicates the name of the environment.

{targetVersion} indicates the new version that the environment is validated against.

Custom dimensions

DimensionDescription or value
eventIdLC0223
environmentTenantAADSpecifies 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.
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.
failureReasonThe overall reason that the environment failed to validate on the new major of Business Central.
targetVersionSpecifies the version of Business Central that we are validating against. Typically the next major version.

Environment diagnostic reported (LC0227)

Occurs if an extension validated with a diagnostic on the next major of Business Central.

General dimensions

DimensionDescription or value
messageValidation diagnostic reported: extension {extensionName} version {extensionVersion} by {extensionPublisher} ({extensionId})

{extensionName} indicates the name of the extension.

{extensionVersion} indicates the version of the extension.

{extensionPublisher} indicates the publisher of the extension.

{extensionId} indicates the id of the extension.

Custom dimensions

DimensionDescription or value
eventIdLC0227
environmentTenantAADSpecifies 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.
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.
extensionNameSpecifies the name of the extension that was to be validated.
extensionIdSpecifies the ID of the extension/app.
extensionPublisherSpecifies the publisher of the extension/app.
extensionVersionSpecifies the version of the extension.
mainExtensionSpecifies the name of an extension that the validated extension has taken a dependency on.
diagnosticCodeSpecifies a diagnostics code emitted by the AL compiler. For more information, see AL compiler diagnostics
diagnosticMessageSpecifies a diagnostics message emitted by the AL compiler.
diagnosticSeveritySpecifies the severity of diagnostics message emitted by the AL compiler, such as Error or Warning.
diagnosticSourceLocationSpecifies where in the app code the AL compiler emitted the diagnostics.
diagnosticSourcePathSpecifies where in a file in the app the AL compiler emitted the diagnostics.
targetVersionSpecifies the version of Business Central that we are validating against. Typically the next major version.

Sample KQL code (environment diagnostic reported)

This KQL code can help you get started analyzing validation failures for an app on the next major of Business Central:

traces
| where customDimensions has "LC0227"
| where customDimensions.eventId == "LC0227"
| where timestamp > ago(30d) // adjust as needed
| project timestamp
// which environment is being validated
, aadTenantId = customDimensions.environmentTenantAAD
, environmentName = customDimensions.environmentName
, environmentType = customDimensions.environmentType // need this dimension
// which extension/app is being validated
, extensionId = customDimensions.extensionId
, extensionPublisher = customDimensions.extensionPublisher
, extensionVersion = customDimensions.extensionVersion
, extensionName = customDimensions.extensionName
, mainExtension = customDimensions.mainExtension
// validation info
, targetVersion = customDimensions.targetVersion
, diagnosticSeverity = customDimensions.diagnosticSeverity
, diagnosticMessage = customDimensions.diagnosticMessage
, diagnosticSourcePath = customDimensions.diagnosticSourcePath
, diagnosticSourceLocation = customDimensions.diagnosticSourceLocation
, diagnosticCode = customDimensions.diagnosticCode

Monitoring and Analyzing Telemetry
Enable Sending Telemetry to Application Insights