Skip to content

Commit 9cca5ee

Browse files
author
Jill Grant
authored
Merge pull request #244539 from matthohn-msft/patch-2
Updating ACS Email azure monitor documentation
2 parents a478936 + 3aa31f9 commit 9cca5ee

10 files changed

+166
-131
lines changed

‎articles/communication-services/concepts/analytics/logs/email-diagnostic-log.png

118 KB
Loading

‎articles/communication-services/concepts/analytics/logs/email-logs.md

Lines changed: 85 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,11 @@
22
title: Azure Communication Services email logs
33
titleSuffix: An Azure Communication Services concept document
44
description: Learn about logging for Azure Communication Services email.
5-
author: ddematheu2
5+
author: mkhribech
66
services: azure-communication-services
77

8-
ms.author: dademath
9-
ms.date: 03/21/2023
8+
ms.author: mkhribech
9+
ms.date: 06/01/2023
1010
ms.topic: conceptual
1111
ms.service: azure-communication-services
1212
ms.subservice: data
@@ -16,8 +16,21 @@ ms.subservice: data
1616

1717
Azure Communication Services offers logging capabilities that you can use to monitor and debug your Communication Services solution. These capabilities can be configured through the Azure portal.
1818

19+
## Prerequisites
20+
21+
Azure Communications Services provides monitoring and analytics features via [Azure Monitor Logs overview](../../../../azure-monitor/logs/data-platform-logs.md) and [Azure Monitor Metrics](../../../../azure-monitor/essentials/data-platform-metrics.md). Each Azure resource requires its own diagnostic setting, which defines the following criteria:
22+
* Categories of logs and metric data sent to the destinations defined in the setting. The available categories will vary for different resource types.
23+
* One or more destinations to send the logs. Current destinations include Log Analytics workspace, Event Hubs, and Azure Storage.
24+
* A single diagnostic setting can define no more than one of each of the destinations. If you want to send data to more than one of a particular destination type (for example, two different Log Analytics workspaces), then create multiple settings. Each resource can have up to five diagnostic settings.
25+
1926
> [!IMPORTANT]
20-
> The following refers to logs enabled through [Azure Monitor](../../../../azure-monitor/overview.md) (see also [FAQ](../../../../azure-monitor/faq.yml)). To enable these logs for your Communications Services, see: [Enable logging in Diagnostic Settings](../enable-logging.md)
27+
> You must enable a Diagnostic Setting in Azure Monitor to send the log data of your surveys to a Log Analytics workspace, Event Hubs, or an Azure storage account to receive and analyze your survey data. If you do not send call automation data to one of these options your survey data will not be stored and will be lost
28+
The following are instructions for configuring your Azure Monitor resource to start creating logs and metrics for your Communications Services. For detailed documentation about using Diagnostic Settings across all Azure resources, see: [Enable logging in Diagnostic Settings](../enable-logging.md)
29+
30+
> [!NOTE]
31+
> Under diagnostic setting name please select select “Email Service Delivery Status Update Logs”, "Email Service Send Mail logs", "Email Service User Engagement Logs" to enable the logs for emails
32+
>
33+
> :::image type="content" source="..\logs\email-diagnostic-log.png" alt-text="Screenshot of diagnostic settings for Email.":::
2134
2235
## Resource log categories
2336

@@ -35,7 +48,7 @@ Communication Services offers the following types of logs that you can enable:
3548
| `Timestamp` | The timestamp (UTC) of when the log was generated. |
3649
| `Operation Name` | The operation associated with log record. |
3750
| `Operation Version` | The `api-version` associated with the operation, if the operationName was performed using an API. If there's no API that corresponds to this operation, the version represents the version of that operation in case the properties associated with the operation change in the future. |
38-
| `Category` | The log category of the event. Category is the granularity at which you can enable or disable logs on a particular resource. The properties that appear within the properties blob of an event are the same within a particular log category and resource type. |
51+
| `Category` | The log category of the event. The category is the granularity at which you can enable or disable logs on a particular resource. The properties that appear within the properties blob of an event are the same within a particular log category and resource type. |
3952
| `Correlation ID` | The ID for correlated events. Can be used to identify correlated events between multiple tables. |
4053
| `Properties` | Other data applicable to various modes of Communication Services. |
4154
| `Record ID` | The unique ID for a given usage record. |
@@ -45,45 +58,104 @@ Communication Services offers the following types of logs that you can enable:
4558

4659
## Email Send Mail operational logs
4760

61+
*Email Send Mail Operational logs* provide valuable insights into API request trends over time. This data helps you discover key email analytics, such as the total number of emails sent, email size, and number of emails with attachments. This information can be quickly analyzed in near-real-time and visualized in a user-friendly way to help drive better decision-making.
62+
4863
| Property | Description |
4964
| -------- | ---------------|
5065
| `TimeGenerated` | The timestamp (UTC) of when the log was generated. |
5166
| `Location` | The region where the operation was processed. |
52-
| `OperationName` | The operation associated with log record. |
67+
| `OperationName` | The operation associated with the log record. |
5368
| `OperationVersion` | The `api-version` associated with the operation, if the `operationName` was performed using an API. If there's no API that corresponds to this operation, the version represents the version of that operation in case the properties associated with the operation change in the future. |
54-
| `Category` | The log category of the event. Category is the granularity at which you can enable or disable logs on a particular resource. The properties that appear within the properties blob of an event are the same within a particular log category and resource type. |
69+
| `Category` | The log category of the event. The category is the granularity at which you can enable or disable logs on a particular resource. The properties that appear within the properties blob of an event are the same within a particular log category and resource type. |
5570
| `CorrelationID` | The ID for correlated events. Can be used to identify correlated events between multiple tables. For all Email operational logs, the CorrelationId is mapped to the MessageId, which is returned from a successful SendMail request. |
56-
| `Size` | Represents the total size in megabytes of the email body, subject, headers and attachments. |
71+
| `Size` | Represents the total size of the email body, subject, headers and attachments in megabytes. |
5772
| `ToRecipientsCount` | The total # of unique email addresses on the To line. |
5873
| `CcRecipientsCount` | The total # of unique email addresses on the Cc line. |
5974
| `BccRecipientsCount` | The total # of unique email addresses on the Bcc line. |
60-
| `UniqueRecipientsCount` | This is the deduplicated total recipient count for the To, Cc and Bcc address fields. |
75+
| `UniqueRecipientsCount` | This is the deduplicated total recipient count for the To, Cc, and Bcc address fields. |
6176
| `AttachmentsCount` | The total # of attachments. |
6277

78+
**Samples**
79+
80+
``` json
81+
{
82+
"OperationType":"SendMail",
83+
"OperationCategory":"EmailSendMailOperational",
84+
"Size":0.026019,
85+
"ToRecipientsCount":2,
86+
"CcRecipientsCount":3,
87+
"BccRecipientsCount":1,
88+
"UniqueRecipientsCount":6,
89+
"AttachmentsCount":0
90+
}
91+
```
92+
6393
## Email Status Update operational logs
6494

95+
*Email status update operational logs* provide in-depth insights into message and recipient level delivery status updates on your sendmail API requests. These logs offer message-specific details, such as the time of delivery, as well as recipient-level details, such as email addresses and delivery status updates. By tracking these logs, you can ensure full visibility into your email delivery process, quickly identifying any issues that may arise and taking corrective action as necessary.
96+
6597
| Property | Description |
6698
| -------- | ---------------|
6799
| `TimeGenerated` | The timestamp (UTC) of when the log was generated. |
68100
| `Location` | The region where the operation was processed. |
69-
| `OperationName` | The operation associated with log record. |
101+
| `OperationName` | The operation associated with the log record. |
70102
| `OperationVersion` | The `api-version` associated with the operation, if the `operationName` was performed using an API. If there's no API that corresponds to this operation, the version represents the version of that operation in case the properties associated with the operation change in the future. |
71-
| `Category` | The log category of the event. Category is the granularity at which you can enable or disable logs on a particular resource. The properties that appear within the properties blob of an event are the same within a particular log category and resource type. |
103+
| `Category` | The log category of the event. The category is the granularity at which you can enable or disable logs on a particular resource. The properties that appear within the properties blob of an event are the same within a particular log category and resource type. |
72104
| `CorrelationID` | The ID for correlated events. Can be used to identify correlated events between multiple tables. For all Email operational logs, the CorrelationId is mapped to the MessageId, which is returned from a successful SendMail request. |
73105
| `RecipientId` | The email address for the targeted recipient. If this is a message-level event, the property will be empty. |
74106
| `DeliveryStatus` | The terminal status of the message. |
107+
| `SmtpStatusCode` | SMTP status code returned from the recipient email server in response to a send mail request.
108+
| `EnhancedSmtpStatusCode` | Enhanced SMTP status code returned from the recipient email server.
109+
| `SenderDomain` | The domain portion of the SenderAddress used in sending emails.
110+
| `SenderUsername` | The username portion of the SenderAddress used in sending emails.
111+
| `IsHardBounce` | Signifies whether a delivery failure was due to a permanent or temporary issue. IsHardBounce == true means a permanent mailbox issue preventing emails from being delivered.
112+
113+
**Samples**
114+
115+
``` json
116+
{
117+
"OperationType":"DeliveryStatusUpdate",
118+
"OperationCategory":"EmailStatusUpdateOperational",
119+
"RecipientId":"[email protected]",
120+
"DeliveryStatus":"Delivered",
121+
"SenderDomain":"contoso.com",
122+
"SenderUsername":"donotreply",
123+
"IsHardBounce":false
124+
}
125+
```
75126

76127
## Email User Engagement operational logs
77128

129+
*Email user engagement operational logs* provide insights into email engagement trends for your email system. This data helps you track and analyze key email metrics such as open rates, click-through rates, and unsubscribe rates. These logs can be stored and analyzed, allowing you to gain deeper insights into your email system's performance, and adapt your strategy accordingly. Overall, Email User Engagement operational logs provide a powerful tool for improving your email system's performance, proactively measuring, and optimizing your email campaigns, and improving user engagement over time.
130+
78131
| Property | Description |
79132
| -------- | ---------------|
80133
| `TimeGenerated` | The timestamp (UTC) of when the log was generated. |
81134
| `Location` | The region where the operation was processed. |
82-
| `OperationName` | The operation associated with log record. |
135+
| `OperationName` | The operation associated with the log record. |
83136
| `OperationVersion` | The `api-version` associated with the operation, if the `operationName` was performed using an API. If there's no API that corresponds to this operation, the version represents the version of that operation in case the properties associated with the operation change in the future. |
84-
| `Category` | The log category of the event. Category is the granularity at which you can enable or disable logs on a particular resource. The properties that appear within the properties blob of an event are the same within a particular log category and resource type. |
137+
| `Category` | The log category of the event. The category is the granularity at which you can enable or disable logs on a particular resource. The properties that appear within the properties blob of an event are the same within a particular log category and resource type. |
85138
| `CorrelationID` | The ID for correlated events. Can be used to identify correlated events between multiple tables. For all Email operational logs, the CorrelationId is mapped to the MessageId, which is returned from a successful SendMail request. |
86139
| `RecipientId` | The email address for the targeted recipient. If this is a message-level event, the property will be empty. |
87140
| `EngagementType` | The type of user engagement being tracked. |
88141
| `EngagementContext` | The context represents what the user interacted with. |
89142
| `UserAgent` | The user agent string from the client. |
143+
144+
**Samples**
145+
146+
``` json
147+
{
148+
"OperationType": "UserEngagementUpdate",
149+
"OperationCategory": "EmailUserEngagementOperational",
150+
"EngagementType": "View",
151+
"UserAgent": "Mozilla/5.0"
152+
}
153+
154+
{
155+
"OperationType":"UserEngagementUpdate",
156+
"OperationCategory":"EmailUserEngagementOperational",
157+
"EngagementType":"Click",
158+
"EngagementContext":"https://www.contoso.com/support?id=12345",
159+
"UserAgent":"Mozilla/5.0"
160+
}
161+
```

‎articles/communication-services/concepts/authentication.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ User access tokens are generated using the Identity SDK and are associated with
5959

6060
## Using identity for monitoring and metrics
6161

62-
The user identity is intended to act as a primary key for logs and metrics collected through Azure Monitor. If you'd like to get a view of all of a specific user's calls, for example, you should set up your authentication in a way that maps a specific Azure Communication Services identity (or identities) to a singular user. Learn more about [log analytics](../concepts/analytics/query-call-logs.md), and [metrics](../concepts/metrics.md) available to you.
62+
The user identity is intended to act as a primary key for logs and metrics collected through Azure Monitor. If you'd like to get a view of all of a specific user's calls, for example, you should set up your authentication in a way that maps a specific Azure Communication Services identity (or identities) to a singular user. Learn more about [log analytics](../concepts/analytics/query-call-logs.md), and [metrics](../concepts/authentication.md) available to you.
6363

6464
## Next steps
6565

‎articles/communication-services/concepts/email-metrics.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
title: Email metric definitions for Azure Communication Services
3+
titleSuffix: An Azure Communication Services concept document
4+
description: This document covers definitions of acs email metrics available in the Azure portal.
5+
author: mkhribech
6+
manager: timmitchell
7+
services: azure-communication-services
8+
9+
ms.author: mkhribech
10+
ms.date: 06/30/2023
11+
ms.topic: conceptual
12+
ms.service: azure-communication-services
13+
ms.subservice: data
14+
---
15+
# Email metrics overview
16+
17+
Azure Communication Services currently provides metrics for all Azure communication services' primitives. [Azure Metrics Explorer](../../azure-monitor/essentials/metrics-getting-started.md) can be used to plot your own charts, investigate abnormalities in your metric values, and understand your API traffic by using the metrics data that email requests emit.
18+
19+
## Where to find metrics
20+
21+
Primitives in Azure Communication Services emit metrics for API requests. These metrics can be found in the Metrics tab under your Communication Services resource. You can also create permanent dashboards using the workbooks tab under your Communication Services resource.
22+
23+
## Metric definitions
24+
25+
All API request metrics contain three dimensions that you can use to filter your metrics data. These dimensions can be aggregated together using the `Count` aggregation type and support all standard Azure Aggregation time series including `Sum`, `Average`, `Min`, and `Max`.
26+
27+
More information on supported aggregation types and time series aggregations can be found [Advanced features of Azure Metrics Explorer](../../azure-monitor/essentials/metrics-charts.md#aggregation)
28+
29+
- **Operation** - All operations or routes that can be called on the Azure Communication Services Chat gateway.
30+
- **Status Code** - The status code response sent after the request.
31+
- **StatusSubClass** - The status code series sent after the response.
32+
33+
### Email Service Delivery Status Updates
34+
The `Email Service Delivery Status Updates` metric lets the email sender track SMTP and Enhanced SMTP status codes and get an idea of how many hard bounces they are encountering.
35+
36+
The following dimensions are available on the `Email Service Delivery Status Updates` metric:
37+
38+
| Dimension | Description |
39+
| -------------------- | ---------------------------------------------------------------------------------------------- |
40+
| Result | High level status of the message delivery: Success, Failure. |
41+
| MessageStatus | Terminal state of the Delivered, Failed, Suppressed. Emails are suppressed when a user sends an email to an email address that is known not to exist. Sending emails to addresses that do not exist trigger a hard bounce. |
42+
| IsHardBounce | True when a message delivery failed due to a hard bounce or if an item was suppressed due to a previous hard bounce. |
43+
| SenderDomain | The domain portion of the senders email address. |
44+
| SmtpStatusCode | Smpt error code from for failed deliveries. |
45+
| EnhancedSmtpStatusCode | The EnhancedSmtpStatusCode status code will be emitted if it is available. This status code provides additional details not available with the SmtpStatusCode. |
46+
47+
:::image type="content" source="./media/acs-email-delivery-status-hardbounce-metrics.png" alt-text="Screenshot showing the Email delivery status update metric - IsHardBounce.":::
48+
:::image type="content" source="./media/acs-email-delivery-status-smtp-metrics.png" alt-text="Screenshot showing the Email delivery status update metric - SmptStatusCode.":::
49+
50+
### Email Service API requests
51+
52+
The following operations are available for the `Email Service API Requests` metric. These standard dimensions are supported: StatusCode, StatusCodeClass, StatusCodeReason and Operation.
53+
54+
| Operation | Description |
55+
| -------------------- | ---------------------------------------------------------------------------------------------- |
56+
| SendMail | Email Send API. |
57+
| GetMessageStatus | Get the delivery status of a messageId. |
58+
59+
:::image type="content" source="./media/acs-email-api-request-metrics.png" alt-text="Screenshot showing the Email API Request Metrics.":::
60+
61+
### Email User Engagement
62+
63+
The `Email Service User Engagement` metric is supported with HTML type emails and must be opted into on your Domains resource. These dimensions are available for `Email Service User Engagement` metrics:
64+
65+
| Dimension | Description |
66+
| -------------------- | ---------------------------------------------------------------------------------------------- |
67+
| EngagementType | Type of interaction performed by the receiver of the email. |
68+
69+
:::image type="content" source="./media/acs-email-user-engagement-metrics.png" alt-text="Screenshot showing the Email user engagement metric.":::
70+
71+
## Next steps
72+
73+
- Learn more about [Data Platform Metrics](../../azure-monitor/essentials/data-platform-metrics.md)

‎articles/communication-services/concepts/media/acs-email-api-request-metrics.png

28.1 KB
Loading

‎articles/communication-services/concepts/media/acs-email-delivery-status-hardbounce-metrics.png

44.7 KB
Loading

‎articles/communication-services/concepts/media/acs-email-delivery-status-smtp-metrics.png

41.1 KB
Loading

‎articles/communication-services/concepts/media/acs-email-user-engagement-metrics.png

38.5 KB
Loading

0 commit comments

Comments
 (0)