Analyze app key vault secret trace telemetry

APPLIES TO: Business Central 2020 release wave 2 and later

App key vault telemetry gathers information about the acquisition of secrets in Azure Key Vaults by extensions at runtime. These events are sent to the extension's Application Insights resource, not the environment's resource. Learn more in Use app key vaults with Business Central extensions.

The app key vault secret process has two operations: initialization and retrieval. The telemetry data provides information about the success or failure for each of these operations. There are various conditions that cause a failure. The failure messages provide insight into the cause of the failure, helping you identify, troubleshoot, and resolve issues.

Initialize the app key vault provider

Initialization is the first stage. It verifies the configuration of the app key vault provider in the extension and on the service. This stage is initiated by the TryInitializeFromCurrentApp method call in the extension code. Some conditions that cause failures in this stage include:

  • The extension doesn't specify a key vault in its app.json file.
  • The Azure Key Vault Client Identity settings are incorrect. For example, it could be that the application (client) ID that you specified for the key vault reader application in Azure is wrong.
  • The Business Central Server lacks permission to the private key of the Azure Key Vault client certificate.

Retrieve an app key vault secret

Retrieval is the second stage, and occurs after a successful initialization. In this stage, the service tries to get a secret from a specified key vault. This stage is initiated by the GetSecret method call in the extension code. Some conditions that cause failures include:

  • The secret name requested by the extension doesn't exist or isn't valid.
  • The key vault doesn't exist.
  • The application ID doesn't have permission to read from the key vault.

Learn more in Use app key vaults with Business Central extensions.

App key vault secret initialization succeeded

Occurs when an extension secret was successfully initialized.

General dimensions

DimensionDescription or value
messageApp Key Vault initialization succeeded: '{keyVaultUri}'.
severityLevel1

Custom dimensions

DimensionDescription or value
alObjectIdSpecifies the ID of the AL object that was run by request.
alObjectNameSpecifies the name of the AL object that was run by request.
alObjectTypeSpecifies the type of AL object that was run by request.
alStackTraceThe stack trace in AL.
clientTypeSpecifies the type of client that executed the request, such as Background or WebClient. Learn more in ClientType option type.
componentDynamics 365 Business Central Server.
componentVersionSpecifies the version number of the component that emits telemetry (see the component dimension.)
deprecatedKeysA 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.
eventIdRT0014
extensionIdSpecifies the AppID of the extension that requested the secret.
extensionNameSpecifies the name of the extension that requested the secret.
extensionPublisherSpecifies the publisher of the extension that requested the secret.
extensionVersionSpecifies the version of the extension that requested the secret.
keyVaultUrlsSpecifies the DNS name of the Azure key vault that was used in the request. The keyVaultUris are specified in the app.json file of the extension.
telemetrySchemaVersionSpecifies the version of the Business Central telemetry schema.

Sample KQL code (successful Azure Key Vault initializations)

This KQL code can help you get started analyzing Azure Key Vault initializations.

traces
| where timestamp > ago(60d) // adjust as needed
| where customDimensions.eventId == 'RT0014'
| project timestamp
, alObjectId = customDimensions.alObjectId
, alObjectName = customDimensions.alObjectName
, alObjectType = customDimensions.alObjectType
, alStackTrace = customDimensions.alStackTrace
, clientType = customDimensions.clientType
, extensionName = customDimensions.extensionName
, extensionId = customDimensions.extensionId
, extensionPublisher = customDimensions.extensionPublisher
, extensionVersion = customDimensions.extensionVersion
, keyVaultUrls = customDimensions.keyVaultUrls

App key vault initialization failed

Occurs when a key vault failed to be initialized.

General dimensions

DimensionDescription or value
messageApp Key Vault initialization failed.
severityLevel3

Custom dimensions

DimensionDescription or value
alObjectIdSpecifies the ID of the AL object that was run by request.
alObjectNameSpecifies the name of the AL object that was run by request.
alObjectTypeSpecifies the type of AL object that was run by request.
alStackTraceThe stack trace in AL.
clientTypeSpecifies the type of client that executed the request, such as Background or WebClient. Learn more in ClientType option type.
componentDynamics 365 Business Central Server.
componentVersionSpecifies the version number of the component that emits telemetry (see the component dimension.)
deprecatedKeysA 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.
eventIdRT0015
extensionIdSpecifies the AppID of the extension that requested the secret.
extensionNameSpecifies the name of the extension that requested the secret.
extensionPublisherSpecifies the publisher of the extension that requested the secret.
extensionVersionSpecifies the version of the extension that requested the secret.
failureReasonSpecifies the error that occurred.
telemetrySchemaVersionSpecifies the version of the Business Central telemetry schema.

Sample KQL code (Azure Key Vault initialization errors)

This KQL code can help you get started troubleshooting and alerting on Azure Key Vault initialization errors.

traces
| where timestamp > ago(60d) // adjust as needed
| where customDimensions.eventId == 'RT0015'
| project timestamp
, alObjectId = customDimensions.alObjectId
, alObjectName = customDimensions.alObjectName
, alObjectType = customDimensions.alObjectType
, alStackTrace = customDimensions.alStackTrace
, clientType = customDimensions.clientType
, extensionName = customDimensions.extensionName
, extensionId = customDimensions.extensionId
, extensionPublisher = customDimensions.extensionPublisher
, extensionVersion = customDimensions.extensionVersion
, failureReason = customDimensions.failureReason

To learn more about how to set up alerting on Business Central telemetry, see Alert on Telemetry.

App key vault secret retrieval succeeded

Occurs when a secret used by an extension is successfully retrieved from an Azure Key Vault.

General dimensions

DimensionDescription or value
messageApp Key Vault secret retrieval succeeded from key vault '{keyVaultUri}'.
severityLevel1

Custom dimensions

DimensionDescription or value
alObjectIdSpecifies the ID of the AL object that was run by request.
alObjectNameSpecifies the name of the AL object that was run by request.
alObjectTypeSpecifies the type of AL object that was run by request.
alStackTraceThe stack trace in AL.
clientTypeSpecifies the type of client that requested the secret, such as Background or WebClient. Learn more in ClientType option type.
componentDynamics 365 Business Central Server.
componentVersionSpecifies the version number of the component that emits telemetry (see the component dimension.)
deprecatedKeysA 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.
eventIdRT0016
extensionIdSpecifies the AppID of the extension that requested the secret.
extensionNameSpecifies the name of the extension that requested the secret.
extensionPublisherSpecifies the publisher of the extension that requested the secret.
extensionVersionSpecifies the version of the extension that requested the secret.
keyVaultUrlSpecifies the DNS name of the Azure key vault that was used in the request. The keyVaultUris are specified in the app.json file of the extension.
secretNameSpecifies the secret name.
telemetrySchemaVersionSpecifies the version of the Business Central telemetry schema.

Sample KQL code (successful Azure Key Vault retrievals)

This KQL code can help you get started analyzing Azure Key Vault retrievals.

traces
| where timestamp > ago(60d) // adjust as needed
| where customDimensions.eventId == 'RT0016'
| project timestamp
, alObjectId = customDimensions.alObjectId
, alObjectName = customDimensions.alObjectName
, alObjectType = customDimensions.alObjectType
, alStackTrace = customDimensions.alStackTrace
, clientType = customDimensions.clientType
, extensionName = customDimensions.extensionName
, extensionId = customDimensions.extensionId
, extensionPublisher = customDimensions.extensionPublisher
, extensionVersion = customDimensions.extensionVersion
, keyVaultUrl = customDimensions.keyVaultUrl
, secretName = customDimensions.secretName

App key vault secret retrieval failed

Occurs when an extension failed to retrieve a secret from a specified Azure key vault.

General dimensions

DimensionDescription or value
messageApp Key Vault secret retrieval failed from key vault '{keyVaultUri}'.
severityLevel3

Custom dimensions

DimensionDescription or value
alObjectIdSpecifies the ID of the AL object that was run by request.
alObjectNameSpecifies the name of the AL object that was run by request.
alObjectTypeSpecifies the type of AL object that was run by request.
alStackTraceThe stack trace in AL.
clientTypeSpecifies the type of client that requested the secret, such as Background or WebClient. Learn more in ClientType option type.
componentDynamics 365 Business Central Server.
componentVersionSpecifies the version number of the component that emits telemetry (see the component dimension.)
deprecatedKeysA 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.
eventIdRT0017
extensionIdSpecifies the AppID of the extension that requested the secret.
extensionNameSpecifies the name of the extension that requested the secret.
extensionPublisherSpecifies the publisher of the extension that requested the secret.
extensionVersionSpecifies the version of the extension that requested the secret.
failureReasonSpecifies the error that occurred while retrieving the secret.
keyVaultUrlSpecifies the DNS name of the Azure key vault that was used in the request. The keyVaultUris are specified in the app.json file of the extension.
secretNameSpecifies the secret name.
telemetrySchemaVersionSpecifies the version of the Business Central telemetry schema.

Sample KQL code (Azure Key Vault retrieval errors)

This KQL code can help you get started troubleshooting and alerting on Azure Key Vault retrieval errors.

traces
| where timestamp > ago(60d) // adjust as needed
| where customDimensions.eventId == 'RT0017'
| project timestamp
, alObjectId = customDimensions.alObjectId
, alObjectName = customDimensions.alObjectName
, alObjectType = customDimensions.alObjectType
, alStackTrace = customDimensions.alStackTrace
, clientType = customDimensions.clientType
, extensionName = customDimensions.extensionName
, extensionId = customDimensions.extensionId
, extensionPublisher = customDimensions.extensionPublisher
, extensionVersion = customDimensions.extensionVersion
, failureReason = customDimensions.failureReason
, keyVaultUrl = customDimensions.keyVaultUrl
, secretName = customDimensions.secretName

To learn more about how to set up alerting on Business Central telemetry, see Alert on Telemetry.

Use key vault secrets in Business Central extensions
Monitoring and Analyzing Telemetry
Enable Sending Telemetry to Application Insights
Alert on Telemetry