Monitor Azure Digital Twins with metrics, alerts, and diagnostics
Azure Digital Twins integrates with Azure Monitor to provide metrics and diagnostic information that you can use to monitor your Azure Digital Twins resources. Metrics are enabled by default, and give you information about the state of Azure Digital Twins resources in your Azure subscription. Alerts can proactively notify you when certain conditions are found in your metrics data. You can also collect diagnostic logs for your service instance to monitor its performance, access, and other data.
These monitoring features can help you assess the overall health of the Azure Digital Twins service and the resources connected to it. You can use them to understand what is happening in your Azure Digital Twins instance, and analyze root causes on issues without needing to contact Azure support.
They can be accessed from the Azure portal, grouped under the Monitoring heading for the Azure Digital Twins resource.
Metrics and alerts
For general information about viewing Azure resource metrics, see Get started with metrics explorer in the Azure Monitor documentation. For general information about configuring alerts for Azure metrics, see Create a new alert rule.
The rest of this section describes the metrics tracked by each Azure Digital Twins instance, and how each metric relates to the overall status of your instance.
Metrics for tracking service limits
You can configure these metrics to track when you're approaching a published service limit for some aspect of your solution.
To set up tracking, use the alerts feature in Azure Monitor. You can define thresholds for these metrics so that you receive an alert when a metric reaches a certain percentage of its published limit.
| Metric | Metric display name | Unit | Aggregation type | Description | Dimensions |
|---|---|---|---|---|---|
| TwinCount | Twin Count (Preview) | Count | Total | Total number of twins in the Azure Digital Twins instance. Use this metric to determine if you're approaching the service limit for max number of twins allowed per instance. | None |
| ModelCount | Model Count (Preview) | Count | Total | Total number of models in the Azure Digital Twins instance. Use this metric to determine if you're approaching the service limit for max number of models allowed per instance. | None |
API request metrics
Metrics having to do with API requests:
| Metric | Metric display name | Unit | Aggregation type | Description | Dimensions |
|---|---|---|---|---|---|
| ApiRequests | API Requests | Count | Total | The number of API Requests made for Digital Twins read, write, delete, and query operations. | Authentication, Operation, Protocol, Status Code, Status Code Class, Status Text |
| ApiRequestsFailureRate | API Requests Failure Rate | Percent | Average | The percentage of API requests that the service receives for your instance that gives an internal error (500) response code for Digital Twins read, write, delete, and query operations. | Authentication, Operation, Protocol, Status Code, Status Code Class, Status Text |
| ApiRequestsLatency | API Requests Latency | Milliseconds | Average | The response time for API requests. This value refers to the time from when the request is received by Azure Digital Twins until the service sends a success/fail result for Digital Twins read, write, delete, and query operations. | Authentication, Operation, Protocol |
Billing metrics
Metrics having to do with billing:
| Metric | Metric display name | Unit | Aggregation type | Description | Dimensions |
|---|---|---|---|---|---|
| BillingApiOperations | Billing API Operations | Count | Total | Billing metric for the count of all API requests made against the Azure Digital Twins service. | Meter ID |
| BillingMessagesProcessed | Billing Messages Processed | Count | Total | Billing metric for the number of messages sent out from Azure Digital Twins to external endpoints. To be considered a single message for billing purposes, a payload must be no larger than 1 KB. Payloads larger than this limit will be counted as additional messages in 1 KB increments (so a message between 1 KB and 2 KB will be counted as 2 messages, between 2 KB and 3 KB will be 3 messages, and so on). This restriction also applies to responses—so a call that returns 1.5 KB in the response body, for example, will be billed as 2 operations. |
Meter ID |
| BillingQueryUnits | Billing Query Units | Count | Total | The number of Query Units, an internally computed measure of service resource usage, consumed to execute queries. There's also a helper API available for measuring Query Units: QueryChargeHelper Class | Meter ID |
For more information on the way Azure Digital Twins is billed, see Azure Digital Twins pricing.
Ingress metrics
Metrics having to do with data ingress:
| Metric | Metric display name | Unit | Aggregation type | Description | Dimensions |
|---|---|---|---|---|---|
| IngressEvents | Ingress Events | Count | Total | The number of incoming device telemetry events into Azure Digital Twins. | Result |
| IngressEventsFailureRate | Ingress Events Failure Rate | Percent | Average | The percentage of incoming device telemetry events for which the service returns an internal error (500) response code. | Result |
| IngressEventsLatency | Ingress Events Latency | Milliseconds | Average | The time from when an event arrives to when it's ready to be egressed by Azure Digital Twins, at which point the service sends a success/fail result. | Result |
Bulk operation metrics (from the Jobs APIs)
Metrics having to do with bulk operations from the Jobs APIs:
| Metric | Metric display name | Unit | Aggregation type | Description | Dimensions |
|---|---|---|---|---|---|
| ImportJobLatency | Import Job Latency | Milliseconds | Average | Total time taken for an import job to complete. | Operation, Authentication, Protocol |
| ImportJobEntityCount | Import Job Entity Count | Count | Total | The number of twins, models, or relationships processed by an import job. | Operation, Result |
| DeleteJobLatency | Delete Job Latency | Milliseconds | Average | Total time taken for a delete job to complete. | Operation, Authentication, Protocol |
| DeleteJobEntityCount | Delete Job Entity Count | Count | Total | The number of models, twins, and/or relationships deleted as part of a delete job. | Operation, Result |
Routing metrics
Metrics having to do with routing:
| Metric | Metric display name | Unit | Aggregation type | Description | Dimensions |
|---|---|---|---|---|---|
| MessagesRouted | Messages Routed | Count | Total | The number of messages routed to an endpoint Azure service such as Event Hubs, Service Bus, or Event Grid. | Endpoint Type, Result |
| RoutingFailureRate | Routing Failure Rate | Percent | Average | The percentage of events that result in an error as they're routed from Azure Digital Twins to an endpoint Azure service such as Event Hubs, Service Bus, or Event Grid. | Endpoint Type, Result |
| RoutingLatency | Routing Latency | Milliseconds | Average | Time elapsed between an event getting routed from Azure Digital Twins to when it's posted to the endpoint Azure service such as Event Hubs, Service Bus, or Event Grid. | Endpoint Type, Result |
Metric dimensions
Dimensions help identify more details about the metrics. Some of the routing metrics provide information per endpoint. The table below lists possible values for these dimensions.
| Dimension | Values |
|---|---|
| Authentication | OAuth |
| Operation (for API Requests) | Microsoft.DigitalTwins/digitaltwins/delete, Microsoft.DigitalTwins/digitaltwins/write, Microsoft.DigitalTwins/digitaltwins/read, Microsoft.DigitalTwins/eventroutes/read, Microsoft.DigitalTwins/eventroutes/write, Microsoft.DigitalTwins/eventroutes/delete, Microsoft.DigitalTwins/models/read, Microsoft.DigitalTwins/models/write, Microsoft.DigitalTwins/models/delete, Microsoft.DigitalTwins/query/action |
| Endpoint Type | Event Grid, Event Hubs, Service Bus |
| Protocol | HTTPS |
| Result | Success, Failure |
| Status Code | 200, 404, 500, and so on. |
| Status Code Class | 2xx, 4xx, 5xx, and so on. |
| Status Text | Internal Server Error, Not Found, and so on. |
Diagnostics logs
For general information about Azure diagnostics settings, including how to enable them, see Diagnostic settings in Azure Monitor. For information about querying diagnostic logs using Log Analytics, see Overview of Log Analytics in Azure Monitor.
The rest of this section describes the diagnostic log categories that Azure Digital Twins can collect, and their schemas.
Log categories
Here are more details about the categories of logs that Azure Digital Twins collects.
| Log category | Description |
|---|---|
| ADTModelsOperation | Log all API calls related to Models |
| ADTQueryOperation | Log all API calls related to Queries |
| ADTEventRoutesOperation | Log all API calls related to Event Routes and egress of events from Azure Digital Twins to an endpoint service like Event Grid, Event Hubs, and Service Bus |
| ADTDigitalTwinsOperation | Log all API calls related to individual twins |
Each log category consists of operations of write, read, delete, and action. These categories map to REST API calls as follows:
| Event type | REST API operations |
|---|---|
| Write | PUT and PATCH |
| Read | GET |
| Delete | DELETE |
| Action | POST |
Here's a comprehensive list of the operations and corresponding Azure Digital Twins REST API calls that are logged in each category.
Note
Each log category contains several operations/REST API calls. In the table below, each log category maps to all operations/REST API calls underneath it until the next log category is listed.
| Log category | Operation | REST API calls and other events |
|---|---|---|
| ADTModelsOperation | Microsoft.DigitalTwins/models/write | Digital Twin Models Update API |
| Microsoft.DigitalTwins/models/read | Digital Twin Models Get By ID and List APIs | |
| Microsoft.DigitalTwins/models/delete | Digital Twin Models Delete API | |
| Microsoft.DigitalTwins/models/action | Digital Twin Models Add API | |
| ADTQueryOperation | Microsoft.DigitalTwins/query/action | Query Twins API |
| ADTEventRoutesOperation | Microsoft.DigitalTwins/eventroutes/write | Event Routes Add API |
| Microsoft.DigitalTwins/eventroutes/read | Event Routes Get By ID and List APIs | |
| Microsoft.DigitalTwins/eventroutes/delete | Event Routes Delete API | |
| Microsoft.DigitalTwins/eventroutes/action | Failure while attempting to publish events to an endpoint service (not an API call) | |
| ADTDigitalTwinsOperation | Microsoft.DigitalTwins/digitaltwins/write | Digital Twins Add, Add Relationship, Update, Update Component |
| Microsoft.DigitalTwins/digitaltwins/read | Digital Twins Get By ID, Get Component, Get Relationship by ID, List Incoming Relationships, List Relationships | |
| Microsoft.DigitalTwins/digitaltwins/delete | Digital Twins Delete, Delete Relationship | |
| Microsoft.DigitalTwins/digitaltwins/action | Digital Twins Send Component Telemetry, Send Telemetry |
Log schemas
Each log category has a schema that defines how events in that category are reported. Each individual log entry is stored as text and formatted as a JSON blob. The fields in the log and example JSON bodies are provided for each log type below.
ADTDigitalTwinsOperation, ADTModelsOperation, and ADTQueryOperation use a consistent API log schema. ADTEventRoutesOperation extends the schema to contain an endpointName field in properties.
API log schemas
This log schema is consistent for ADTDigitalTwinsOperation, ADTModelsOperation, ADTQueryOperation. The same schema is also used for ADTEventRoutesOperation, except the Microsoft.DigitalTwins/eventroutes/action operation name (for more information about that schema, see the next section, Egress log schemas).
The schema contains information pertinent to API calls to an Azure Digital Twins instance.
Here are the field and property descriptions for API logs.
| Field name | Data type | Description |
|---|---|---|
Time |
DateTime | The date and time that this event occurred, in UTC |
ResourceId |
String | The Azure Resource Manager Resource ID for the resource where the event took place |
OperationName |
String | The type of action being performed during the event |
OperationVersion |
String | The API Version used during the event |
Category |
String | The type of resource being emitted |
ResultType |
String | Outcome of the event |
ResultSignature |
String | Http status code for the event |
ResultDescription |
String | Additional details about the event |
DurationMs |
String | How long it took to perform the event in milliseconds |
CallerIpAddress |
String | A masked source IP address for the event |
CorrelationId |
Guid | Unique identifier for the event |
ApplicationId |
Guid | Application ID used in bearer authorization |
Level |
Int | The logging severity of the event |
Location |
String | The region where the event took place |
RequestUri |
Uri | The endpoint used during the event |
TraceId |
String | TraceId, as part of W3C's Trace Context. The ID of the whole trace used to uniquely identify a distributed trace across systems. |
SpanId |
String | SpanId as part of W3C's Trace Context. The ID of this request in the trace. |
ParentId |
String | ParentId as part of W3C's Trace Context. A request without a parent ID is the root of the trace. |
TraceFlags |
String | TraceFlags as part of W3C's Trace Context. Controls tracing flags such as sampling, trace level, and so on. |
TraceState |
String | TraceState as part of W3C's Trace Context. Additional vendor-specific trace identification information to span across different distributed tracing systems. |
Below are example JSON bodies for these types of logs.
ADTDigitalTwinsOperation
{
"time": "2020-03-14T21:11:14.9918922Z",
"resourceId": "/SUBSCRIPTIONS/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/RESOURCEGROUPS/MYRESOURCEGROUP/PROVIDERS/MICROSOFT.DIGITALTWINS/DIGITALTWINSINSTANCES/MYINSTANCENAME",
"operationName": "Microsoft.DigitalTwins/digitaltwins/write",
"operationVersion": "2020-10-31",
"category": "DigitalTwinOperation",
"resultType": "Success",
"resultSignature": "200",
"resultDescription": "",
"durationMs": 8,
"callerIpAddress": "13.68.244.*",
"correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
"identity": {
"claims": {
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444"
}
},
"level": "4",
"location": "southcentralus",
"uri": "https://myinstancename.api.scus.digitaltwins.azure.net/digitaltwins/factory-58d81613-2e54-4faa-a930-d980e6e2a884?api-version=2020-10-31",
"properties": {},
"traceContext": {
"traceId": "95ff77cfb300b04f80d83e64d13831e7",
"spanId": "b630da57026dd046",
"parentId": "9f0de6dadae85945",
"traceFlags": "01",
"tracestate": "k1=v1,k2=v2"
}
}
ADTModelsOperation
{
"time": "2020-10-29T21:12:24.2337302Z",
"resourceId": "/SUBSCRIPTIONS/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/RESOURCEGROUPS/MYRESOURCEGROUP/PROVIDERS/MICROSOFT.DIGITALTWINS/DIGITALTWINSINSTANCES/MYINSTANCENAME",
"operationName": "Microsoft.DigitalTwins/models/write",
"operationVersion": "2020-10-31",
"category": "ModelsOperation",
"resultType": "Success",
"resultSignature": "201",
"resultDescription": "",
"durationMs": "80",
"callerIpAddress": "13.68.244.*",
"correlationId": "bbbb1111-cc22-3333-44dd-555555eeeeee",
"identity": {
"claims": {
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444"
}
},
"level": "4",
"location": "southcentralus",
"uri": "https://myinstancename.api.scus.digitaltwins.azure.net/Models?api-version=2020-10-31",
"properties": {},
"traceContext": {
"traceId": "95ff77cfb300b04f80d83e64d13831e7",
"spanId": "b630da57026dd046",
"parentId": "9f0de6dadae85945",
"traceFlags": "01",
"tracestate": "k1=v1,k2=v2"
}
}
ADTQueryOperation
{
"time": "2020-12-04T21:11:44.1690031Z",
"resourceId": "/SUBSCRIPTIONS/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/RESOURCEGROUPS/MYRESOURCEGROUP/PROVIDERS/MICROSOFT.DIGITALTWINS/DIGITALTWINSINSTANCES/MYINSTANCENAME",
"operationName": "Microsoft.DigitalTwins/query/action",
"operationVersion": "2020-10-31",
"category": "QueryOperation",
"resultType": "Success",
"resultSignature": "200",
"resultDescription": "",
"durationMs": "314",
"callerIpAddress": "13.68.244.*",
"correlationId": "cccc2222-dd33-4444-55ee-666666ffffff",
"identity": {
"claims": {
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444"
}
},
"level": "4",
"location": "southcentralus",
"uri": "https://myinstancename.api.scus.digitaltwins.azure.net/query?api-version=2020-10-31",
"properties": {},
"traceContext": {
"traceId": "95ff77cfb300b04f80d83e64d13831e7",
"spanId": "b630da57026dd046",
"parentId": "9f0de6dadae85945",
"traceFlags": "01",
"tracestate": "k1=v1,k2=v2"
}
}
ADTEventRoutesOperation
Here's an example JSON body for an ADTEventRoutesOperation that isn't of Microsoft.DigitalTwins/eventroutes/action type (for more information about that schema, see the next section, Egress log schemas).
{
"time": "2020-10-30T22:18:38.0708705Z",
"resourceId": "/SUBSCRIPTIONS/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/RESOURCEGROUPS/MYRESOURCEGROUP/PROVIDERS/MICROSOFT.DIGITALTWINS/DIGITALTWINSINSTANCES/MYINSTANCENAME",
"operationName": "Microsoft.DigitalTwins/eventroutes/write",
"operationVersion": "2020-10-31",
"category": "EventRoutesOperation",
"resultType": "Success",
"resultSignature": "204",
"resultDescription": "",
"durationMs": 42,
"callerIpAddress": "212.100.32.*",
"correlationId": "dddd3333-ee44-5555-66ff-777777aaaaaa",
"identity": {
"claims": {
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444"
}
},
"level": "4",
"location": "southcentralus",
"uri": "https://myinstancename.api.scus.digitaltwins.azure.net/EventRoutes/egressRouteForEventHub?api-version=2020-10-31",
"properties": {},
"traceContext": {
"traceId": "95ff77cfb300b04f80d83e64d13831e7",
"spanId": "b630da57026dd046",
"parentId": "9f0de6dadae85945",
"traceFlags": "01",
"tracestate": "k1=v1,k2=v2"
}
},
Egress log schemas
The following example is the schema for ADTEventRoutesOperation logs specific to the Microsoft.DigitalTwins/eventroutes/action operation name. These contain details related to exceptions and the API operations around egress endpoints connected to an Azure Digital Twins instance.
| Field name | Data type | Description |
|---|---|---|
Time |
DateTime | The date and time that this event occurred, in UTC |
ResourceId |
String | The Azure Resource Manager Resource ID for the resource where the event took place |
OperationName |
String | The type of action being performed during the event |
Category |
String | The type of resource being emitted |
ResultDescription |
String | Additional details about the event |
CorrelationId |
Guid | Customer provided unique identifier for the event |
ApplicationId |
Guid | Application ID used in bearer authorization |
Level |
Int | The logging severity of the event |
Location |
String | The region where the event took place |
TraceId |
String | TraceId, as part of W3C's Trace Context. The ID of the whole trace used to uniquely identify a distributed trace across systems. |
SpanId |
String | SpanId as part of W3C's Trace Context. The ID of this request in the trace. |
ParentId |
String | ParentId as part of W3C's Trace Context. A request without a parent ID is the root of the trace. |
TraceFlags |
String | TraceFlags as part of W3C's Trace Context. Controls tracing flags such as sampling, trace level, and so on. |
TraceState |
String | TraceState as part of W3C's Trace Context. Additional vendor-specific trace identification information to span across different distributed tracing systems. |
EndpointName |
String | The name of egress endpoint created in Azure Digital Twins |
Here's an example JSON body for an ADTEventRoutesOperation that of Microsoft.DigitalTwins/eventroutes/action type.
{
"time": "2020-11-05T22:18:38.0708705Z",
"resourceId": "/SUBSCRIPTIONS/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/RESOURCEGROUPS/MYRESOURCEGROUP/PROVIDERS/MICROSOFT.DIGITALTWINS/DIGITALTWINSINSTANCES/MYINSTANCENAME",
"operationName": "Microsoft.DigitalTwins/eventroutes/action",
"operationVersion": "",
"category": "EventRoutesOperation",
"resultType": "",
"resultSignature": "",
"resultDescription": "Unable to send EventHub message to [myPath] for event Id [f6f45831-55d0-408b-8366-058e81ca6089].",
"durationMs": -1,
"callerIpAddress": "",
"correlationId": "dddd3333-ee44-5555-66ff-777777aaaaaa",
"identity": {
"claims": {
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444"
}
},
"level": "4",
"location": "southcentralus",
"uri": "",
"properties": {
"endpointName": "myEventHub"
},
"traceContext": {
"traceId": "95ff77cfb300b04f80d83e64d13831e7",
"spanId": "b630da57026dd046",
"parentId": "9f0de6dadae85945",
"traceFlags": "01",
"tracestate": "k1=v1,k2=v2"
}
},
Next steps
Read more about Azure Monitor and its capabilities in the Azure Monitor documentation.