Modifier

Partager via


Analyze email telemetry

APPLIES TO: Business Central 2020 release wave 2, update 17.2, and later

Email telemetry gathers data about the following operations:

  • An email was sent successfully
  • An attempt to send an email failed

From Business Central 2023 release wave 1, update 23.2, and later, the following operations are also emitted to telemetry:

  • Authentication to an SMTP server succeded/failed
  • Connection to an SMTP server succeded/failed

Before you can collect this data, you'll have to set up email. For more information, see Set Up Email in the Business Central application help.

Tip

You can also view failed emails in the Email Outbox page in the Business Central client.

Email sent successfully

Occurs when an email was successfully sent from the client.

General dimensions

Dimension Description or value
message Email sent successfully
user_Id The user telemetry ID for the user. From the user card, you can use user_Id to identify the user who triggered this telemetry event. For more information, see Assign a telemetry ID to users.

Custom dimensions

Dimension Description or value
aadTenantId

Note

Azure Active Directory is now Microsoft Entra ID. Learn more

Specifies 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.
clientType Specifies the type of client that opened the session, such as Background or Web. For a list of the client types, see ClientType Option Type.
companyName The current company name.
environmentName Specifies the name of the tenant environment. See Managing Environments.
environmentType Specifies the environment type for the tenant, such as Production or Sandbox. See Environment Types.
alConnector Specifies the email-provider connector used to send the email. Possible values include:
  • Current User
  • Microsoft 365
  • SMTP
  • Other custom connectors installed by extensions.
The connector is specified on the email accounts that are set up in Business Central. For more information, see Adding Email Accounts.
alEmailMessageID Specifies the GUID assigned to email, like C7A56676-9F3F-4044-90F0-D7F3196AC366.
alObjectId 8888, which is the ID of the system application codeunit that sends emails.
alObjectName Email Dispatcher, which is the name of the system application codeunit that sends the emails.
alObjectType CodeUnit
eventId AL0000CTV

Failed to send email

Occurs when an email failed to be sent from the client.

General dimensions

Dimension Description or value
message Failed to send email.
user_Id The user telemetry ID for the user. From the user card, you can use user_Id to identify the user who triggered this telemetry event. For more information, see Assign a telemetry ID to users.

Custom dimensions

Dimension Description or value
aadTenantId

Note

Azure Active Directory is now Microsoft Entra ID. Learn more

Specifies 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.
clientType Specifies the type of client that opened the session, such as Background or Web. For a list of the client types, see ClientType Option Type.
companyName The current company name.
environmentName Specifies the name of the tenant environment. See Managing Environments.
environmentType Specifies the environment type for the tenant, such as Production or Sandbox. See Environment Types.
alConnector Specifies the email-provider connector used to send the email. Possible values include:
  • Current User
  • Microsoft 365
  • SMTP
  • Other custom connectors installed by extensions.
The connector is specified on the email accounts that are set up in Business Central. For more information, see Adding Email Accounts.
alEmailMessageID Specifies the GUID assigned to email, like C7A56676-9F3F-4044-90F0-D7F3196AC366.
alErrorCallStack Specifies the AL callstack when the error occurred. This dimension was added in version 19.0.
alErrorText Specifies the AL error message. This dimension was added in version 19.0.
alObjectId 8888, which is the ID of the system application codeunit that sends emails.
alObjectName Email Dispatcher, which is the name of the system application codeunit that sends the emails.
alObjectType CodeUnit
eventId AL0000CTP

SMTP server authentication

Occurs when the SMTP module is authenticating to an SMTP server.

General dimensions

Dimension Description or value
message Authenticated to SMTP server
user_Id The user telemetry ID for the user. From the user card, you can use user_Id to identify the user who triggered this telemetry event. For more information, see Assign a telemetry ID to users.

Custom dimensions

Dimension Description or value
aadTenantId

Note

Azure Active Directory is now Microsoft Entra ID. Learn more

Specifies 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.
clientType Specifies the type of client that opened the session, such as Background or Web. For a list of the client types, see ClientType Option Type.
companyName The current company name.
environmentName Specifies the name of the tenant environment. See Managing Environments.
environmentType Specifies the environment type for the tenant, such as Production or Sandbox. See Environment Types.
eventId AL0000GKK
alAuthenticated Specifies whether authentication succeeded. Possible values are Yes or No.

Sample KQL code

This KQL code can help you get started analyzing SMTP authentication failures:

// Authenticated to SMTP server
// Introduced in version 22.3
traces
| where timestamp > ago(60d) // adjust as needed
| where customDimensions.eventId == 'AL0000GKK'
| where customDimensions.alAuthenticated == 'No'
| project timestamp
, aadTenantId = customDimensions.aadTenantId
, environmentName = customDimensions.environmentName
, environmentType = customDimensions.environmentType
, companyName = customDimensions.companyName
, clientType = customDimensions.clientType

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

SMTP server connections

Occurs when the SMTP module is connecting to an SMTP server.

General dimensions

Dimension Description or value
message Connected to SMTP server
user_Id The user telemetry ID for the user. From the user card, you can use user_Id to identify the user who triggered this telemetry event. For more information, see Assign a telemetry ID to users.

Custom dimensions

Dimension Description or value
aadTenantId

Note

Azure Active Directory is now Microsoft Entra ID. Learn more

Specifies 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.
clientType Specifies the type of client that opened the session, such as Background or Web. For a list of the client types, see ClientType Option Type.
companyName The current company name.
environmentName Specifies the name of the tenant environment. See Managing Environments.
environmentType Specifies the environment type for the tenant, such as Production or Sandbox. See Environment Types.
eventId AL0000GKJ
alConnected Specifies whether connection succeeded. Possible values are Yes or No.

Sample KQL code

This KQL code can help you get started analyzing SMTP connection failures:

// Connected to SMTP server
// Introduced in version 22.3
traces
| where timestamp > ago(60d) // adjust as needed
| where customDimensions.eventId == 'AL0000GKJ'
| where customDimensions.alConnected == 'No'
| project timestamp
, aadTenantId = customDimensions.aadTenantId
, environmentName = customDimensions.environmentName
, environmentType = customDimensions.environmentType
, companyName = customDimensions.companyName
, clientType = customDimensions.clientType

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

Email sent (using SMTP)

Occurs when the SMTP module is sending an email.

General dimensions

Dimension Description or value
message Email sent
user_Id The user telemetry ID for the user. From the user card, you can use user_Id to identify the user who triggered this telemetry event. For more information, see Assign a telemetry ID to users.

Custom dimensions

Dimension Description or value
aadTenantId

Note

Azure Active Directory is now Microsoft Entra ID. Learn more

Specifies 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.
clientType Specifies the type of client that opened the session, such as Background or Web. For a list of the client types, see ClientType Option Type.
companyName The current company name.
environmentName Specifies the name of the tenant environment. See Managing Environments.
environmentType Specifies the environment type for the tenant, such as Production or Sandbox. See Environment Types.
eventId AL0000GKL
alSent Specifies whether sending the email succeeded. Possible values are Yes or No.

Sample KQL code

This KQL code can help you get started analyzing failures in sending emails:

// Connected to SMTP server
// Introduced in version 22.3
traces
| where timestamp > ago(60d) // adjust as needed
| where customDimensions.eventId == 'AL0000GKL'
| where customDimensions.alSent == 'No'
| project timestamp
, aadTenantId = customDimensions.aadTenantId
, environmentName = customDimensions.environmentName
, environmentType = customDimensions.environmentType
, companyName = customDimensions.companyName
, clientType = customDimensions.clientType

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

Sample KQL code for alerting on SMTP failures

Use this KQL code if you want to set up alerts on SMTP failures, either failures authenticating/connecting to SMTP servers or failures on sending emails.

traces
| where timestamp > ago(1d) // adjust as needed
| where  customDimensions.eventId == 'AL0000CTP'
     or (customDimensions.eventId == 'AL0000GKK' and customDimensions.alAuthenticated == 'No')
     or (customDimensions.eventId == 'AL0000GKJ' and customDimensions.alConnected == 'No')
     or (customDimensions.eventId == 'AL0000GKL' and customDimensions.alSent == 'No')
| extend EventId = customDimensions.eventId     
| summarize count() by
  aadTenantId = tostring( customDimensions.aadTenantId )
, environmentName = tostring( customDimensions.environmentName )
, environmentType = tostring( customDimensions.environmentType )
, companyName = tostring( customDimensions.companyName )
, clientType = tostring( customDimensions.clientType )
, ErrorType = case (
  EventId == 'AL0000CTP', 'Other'
, EventId == 'AL0000GKK', 'SMTP authentication'
, EventId == 'AL0000GKJ', 'SMTP connection'
, EventId == 'AL0000GKL', 'SMTP email'
, 'Unknown'
)

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

See also

Monitoring and Analyzing Telemetry
Enable Sending Telemetry to Application Insights
Alert on Telemetry