Modifier

Partager via


Analyze an 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. For an overview of app key vaults and secrets, see Using 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.

Initialization

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 it's 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.

Retrieval

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 is 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.

For more information about using key vault secrets with extensions, see App Key Vaults with Business Central Extensions.

App Key Vault secret initialization succeeded

Occurs when an extension secret was successfully initialized.

General dimensions

Dimension Description or value
message App Key Vault initialization succeeded: '{keyVaultUri}'.
severityLevel 1

Custom dimensions

Dimension Description or value
alObjectId Specifies the ID of the AL object that was run by request.
alObjectName Specifies the name of the AL object that was run by request.
alObjectType Specifies the type of AL object that was run by request.
alStackTrace The stack trace in AL.
clientType Specifies the type of client that executed the request, such as Background or Web. For a list of the client types, see ClientType Option Type.
component Dynamics 365 Business Central Server.
componentVersion Specifies the version number of the component that emits telemetry (see the component dimension.)
deprecatedKeys 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 update any queries that use these keys to use the new key name.
eventId RT0014
extensionId Specifies the AppID of the extension that requested the secret.
extensionName Specifies the name of the extension that requested the secret.
extensionPublisher Specifies the publisher of the extension that requested the secret.
extensionVersion Specifies the version of the extension that requested the secret.
keyVaultUrls Specifies 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.
telemetrySchemaVersion Specifies the version of the Business Central telemetry schema.

Sample KQL code (successful Azure Keyvault initializations)

This KQL code can help you get started analyzing Azure Keyvault 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

Dimension Description or value
message App Key Vault initialization failed.
severityLevel 3

Custom dimensions

Dimension Description or value
alObjectId Specifies the ID of the AL object that was run by request.
alObjectName Specifies the name of the AL object that was run by request.
alObjectType Specifies the type of AL object that was run by request.
alStackTrace The stack trace in AL.
clientType Specifies the type of client that executed request, such as Background or Web. For a list of the client types, see ClientType Option Type.
component Dynamics 365 Business Central Server.
componentVersion Specifies the version number of the component that emits telemetry (see the component dimension.)
deprecatedKeys 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 update any queries that use these keys to use the new key name.
eventId RT0015
extensionId Specifies the AppID of the extension that requested the secret.
extensionName Specifies the name of the extension that requested the secret.
extensionPublisher Specifies the publisher of the extension that requested the secret.
extensionVersion Specifies the version of the extension that requested the secret.
failureReason Specifies the error that occurred.
telemetrySchemaVersion Specifies the version of the Business Central telemetry schema.

Sample KQL code (Azure Keyvault initialization errors)

This KQL code can help you get started troubleshooting and alerting on Azure Keyvault retrieval 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 setup 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

Dimension Description or value
message App Key Vault secret retrieval succeeded from key vault '{keyVaultUri}'.
severityLevel 1

Custom dimensions

Dimension Description or value
alObjectId Specifies the ID of the AL object that was run by request.
alObjectName Specifies the name of the AL object that was run by request.
alObjectType Specifies the type of AL object that was run by request.
alStackTrace The stack trace in AL.
clientType Specifies the type of client that executed the SQL Statement, such as Background or Web. For a list of the client types, see ClientType Option Type.
component Dynamics 365 Business Central Server.
componentVersion Specifies the version number of the component that emits telemetry (see the component dimension.)
deprecatedKeys 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 update any queries that use these keys to use the new key name.
eventId RT0016
extensionId Specifies the AppID of the extension that requested the secret.
extensionName Specifies the name of the extension that requested the secret.
extensionPublisher Specifies the publisher of the extension that requested the secret.
extensionVersion Specifies the version of the extension that requested the secret.
keyVaultUrl Specifies 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.
telemetrySchemaVersion Specifies the version of the Business Central telemetry schema.

Sample KQL code (successful Azure Keyvault retrievals)

This KQL code can help you get started analyzing Azure Keyvault 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

App Key Vault secret retrieval failed

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

General dimensions

Dimension Description or value
message App Key Vault secret retrieval failed from key vault '{keyVaultUri}'.
severityLevel 3

Custom dimensions

Dimension Description or value
alObjectId Specifies the ID of the AL object that was run by request.
alObjectName Specifies the name of the AL object that was run by request.
alObjectType Specifies the type of AL object that was run by request.
alStackTrace The stack trace in AL.
clientType Specifies the type of client that executed the SQL Statement, such as Background or Web. For a list of the client types, see ClientType Option Type.
component Dynamics 365 Business Central Server.
componentVersion Specifies the version number of the component that emits telemetry (see the component dimension.)
deprecatedKeys 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 update any queries that use these keys to use the new key name.
eventId RT0017
extensionId Specifies the AppID of the extension that requested the secret.
extensionName Specifies the name of the extension that requested the secret.
extensionPublisher Specifies the publisher of the extension that requested the secret.
extensionVersion Specifies the version of the extension that requested the secret.
keyVaultUrl Specifies 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.
telemetrySchemaVersion Specifies the version of the Business Central telemetry schema.

Sample KQL code (Azure Keyvault retrieval errors)

This KQL code can help you get started troubleshooting and alerting on Azure Keyvault 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

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

See also

App Key Vaults with Business Central Extensions
Monitoring and Analyzing Telemetry
Enable Sending Telemetry to Application Insights
Alert on Telemetry