Edytuj

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

In application versions that include the SMTP telemetry events documented below, the following operations are also emitted to telemetry:

  • Authentication to an SMTP server succeeded or failed
  • Connection to an SMTP server succeeded or failed
  • Sending an email through SMTP succeeded or failed

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

These events use TelemetryScope::All. The failed-to-send event uses error verbosity (severityLevel 3). The other events use normal verbosity (severityLevel 1), including SMTP events whose result dimension is No.

Tip

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

Email sent successfully

Occurs when the email dispatcher successfully sends 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. Learn more in Assign a telemetry ID to users.

Custom dimensions

Dimension Description or value
aadTenantId 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. Learn more in Managing Environments.
environmentType Specifies the environment type for the tenant, such as Production or Sandbox. Learn more in Environment Types.
alFeatureName Emailing
alEventName Email sent
alObjectId 8713, which is the ID of the system application telemetry logger codeunit.
alObjectName System Telemetry Logger, which emits the event on behalf of the email dispatcher.
alObjectType CodeUnit
eventId AL0000CTV

Failed to send email

Occurs when the email dispatcher fails to send an email.

General dimensions

Dimension Description or value
message The error text returned by the failed send operation.
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. Learn more in Assign a telemetry ID to users.

Custom dimensions

Dimension Description or value
aadTenantId 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. Learn more in Managing Environments.
environmentType Specifies the environment type for the tenant, such as Production or Sandbox. Learn more in Environment Types.
alFeatureName Emailing
alEventName Failed to send email
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 8713, which is the ID of the system application telemetry logger codeunit.
alObjectName System Telemetry Logger, which emits the event on behalf of the email dispatcher.
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. Learn more in Assign a telemetry ID to users.

Custom dimensions

Dimension Description or value
aadTenantId 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. Learn more in Managing Environments.
environmentType Specifies the environment type for the tenant, such as Production or Sandbox. Learn more in 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
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 set up 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. Learn more in Assign a telemetry ID to users.

Custom dimensions

Dimension Description or value
aadTenantId 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. Learn more in Managing Environments.
environmentType Specifies the environment type for the tenant, such as Production or Sandbox. Learn more in 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
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 set up 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 Sent 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. Learn more in Assign a telemetry ID to users.

Custom dimensions

Dimension Description or value
aadTenantId 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. Learn more in Managing Environments.
environmentType Specifies the environment type for the tenant, such as Production or Sandbox. Learn more in 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:

// Sent email
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 set up 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 set up alerting on Business Central telemetry, see Alert on Telemetry.

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