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.
Related information
App Key Vaults with Business Central Extensions
Monitoring and Analyzing Telemetry
Enable Sending Telemetry to Application Insights
Alert on Telemetry