Мониторинг Azure Digital Twins с помощью журналов диагностики

В этой статье показано, как настроить параметры диагностики на портале Azure, включая типы журналов для сбора и хранения (например, Log Analytics или учетную запись хранения по своему усмотрению). Затем можно запросить журналы, чтобы быстро собрать пользовательские аналитические сведения.

Azure Digital Twins может собирать журналы для экземпляра службы, чтобы отслеживать производительность, доступ и другие данные. Информацию из этих журналов можно использовать для понимания, что происходит в вашем экземпляре Azure Digital Twins, а также для анализа основных причин возникающих проблем без обращения в службу поддержки Azure.

В этой статье также содержатся сведения обо всех категориях журналов, которые azure Digital Twins может собирать, и их схемы.

Включение параметров диагностики

Чтобы начать сбор журналов в своем экземпляре Azure Digital Twins, включите параметры диагностики. Также можно выбрать место, где должны храниться экспортированные журналы. Далее представлено, как можно включить параметры диагностики для своего экземпляра Azure Digital Twins.

  1. Войдите на портал Azure и перейдите к своему экземпляру Azure Digital Twins. Его можно найти, введя его имя на панели поиска портала.

  2. Выберите Параметры диагностики в меню, затем Добавить параметр диагностики.

    Screenshot showing the diagnostic settings page in the Azure portal and button to add.

  3. На следующей странице введите значения, перечисленные ниже.

    • Имя параметра диагностики: задайте общее название для параметров диагностики.

    • Сведения о категории: выберите операции, которые требуется отслеживать, и установите флажки, чтобы включить диагностику для этих операций. Ниже перечислены операции, для которых доступны параметры диагностики:

      • DigitalTwinsOperation
      • EventRoutesOperation
      • ModelsOperation
      • QueryOperation
      • AllMetrics

      Дополнительные сведения об этих категориях и содержащихся в них сведениях см. в разделе Категории журнала ниже.

    • Сведения о месте назначения: выберите, куда вы хотите отправлять журналы. Можно выбрать любое сочетание трех параметров:

      • Отправка в Log Analytics
      • "Архивировать в учетной записи хранения";
      • "Передать в концентратор событий";

      Возможно, вам будет предложено ввести дополнительные сведения, если они необходимы для выбора места назначения.

  4. Сохраните новые настройки.

    Screenshot showing the diagnostic setting page in the Azure portal where the user has filled in a diagnostic setting information.

Новые параметры вступят в силу в течение 10 минут. После этого журналы отобразятся в настроенном вами устройстве на странице Параметры диагностики для вашего экземпляра.

Для получения более подробных сведений о параметрах диагностики и опциях их настройки можно посетить страницу Создание параметров диагностики для отправки журналов и метрик платформы в разные места назначения.

Просмотр и запрос журналов

После настройки сведений о хранилище журналов Azure Digital Twins можно написать пользовательские запросы для них для создания аналитических сведений и устранения неполадок. Служба также предоставляет несколько примеров запросов, которые помогут вам приступить к работе, обращаясь к общим вопросам, которые клиенты могут иметь о своих экземплярах.

Далее представлена процедура запроса журналов для своего экземпляра.

  1. Войдите на портал Azure и перейдите к своему экземпляру Azure Digital Twins. Его можно найти, введя его имя на панели поиска портала.

  2. Выберите в меню Журналы, чтобы открыть страницу запроса журнала. Эта страница открывает окно под названием Запросы.

    Screenshot showing the Logs page for an Azure Digital Twins instance in the Azure portal with the Queries window overlaid, showing prebuilt queries.

    Эти запросы представляют собой предварительно созданные примеры, которые написаны для различных типов журналов. Можно выбрать один из запросов и загрузить его в редактор запросов, затем запустить, чтобы просмотреть эти журналы с целью применения в своем экземпляре.

    Можно также закрыть окно Запросы без выполнения каких-либо действий, чтобы перейти непосредственно на страницу редактора запросов, где можно написать или изменить код пользовательского запроса.

  3. После выхода из окна Запросы вы увидите главную страницу редактора запросов. Здесь можно просматривать и редактировать текст примеров запросов, а также создавать собственные запросы с нуля. Screenshot showing the Logs page for an Azure Digital Twins instance in the Azure portal. It includes a list of logs, query code, and Queries History.

    В левой области:

    • На вкладке Таблицы отображаются различные категории журналов Azure Digital Twins, которые можно использовать в запросах.
    • На вкладке Запросы содержатся примеры запросов, которые можно загрузить в редактор.
    • Вкладка Фильтр позволяет настроить отфильтрованное представление данных, возвращаемых запросом.

Дополнительные сведения о запросах на журналы и том, как написать эти запросы, см. в разделе Обзор запросов на журналы в Azure Monitor.

Категории журналов

Ниже приведены подробные сведения о категориях журналов, собираемых Azure Digital Twins.

Категория журнала Описание
ADTModelsOperation Регистрируют все вызовы API, связанные с моделями
ADTQueryOperation Регистрируют все вызовы API, связанные с запросами
ADTEventRoutesOperation Регистрируют все вызовы API, связанные с маршрутами событий, а также с исходящим трафиком событий из Azure Digital Twins в службу конечной точки, например в "Сетку событий", "Концентраторы событий" и на "Служебную шину"
ADTDigitalTwinsOperation Регистрируют все вызовы API, связанные с отдельными цифровыми двойниками

Каждая категория журнала состоит из операций "write" (запись), "read" (чтение), "delete" (удаление) и "action" (действие). Эти категории сопоставляются с вызовами REST API следующим образом:

Тип события Операции REST API
запись PUT и PATCH
Чтение GET
DELETE DELETE
Действие POST

Ниже приведен полный список операций и соответствующих вызовов REST API Azure Digital Twins REST API calls, которые регистрируются в каждой категории.

Примечание

Каждая категория журнала содержит несколько операций или вызовов REST API. В приведенной ниже таблице каждая категория журналов сопоставляется со всеми операциями/вызовами REST API, находящимися под ней, только после этого приводится следующая категория журнала.

Категория журнала Операция Вызовы REST API и другие события
ADTModelsOperation Microsoft.DigitalTwins/models/write API обновления моделей цифровых двойников
Microsoft.DigitalTwins/models/read API получения моделей цифровых двойников по идентификаторам и спискам
Microsoft.DigitalTwins/models/delete API удаления моделей цифровых двойников
Microsoft.DigitalTwins/models/action API добавления моделей цифровых двойников
ADTQueryOperation Microsoft.DigitalTwins/query/action API запроса цифровых двойников
ADTEventRoutesOperation Microsoft.DigitalTwins/eventroutes/write API добавления маршрутов событий
Microsoft.DigitalTwins/eventroutes/read API получения маршрутов событий по идентификаторам и спискам
Microsoft.DigitalTwins/eventroutes/delete API удаления маршрутов событий
Microsoft.DigitalTwins/eventroutes/action Сбой при попытке публикации событий в службе конечной точки (не вызов API)
ADTDigitalTwinsOperation Microsoft.DigitalTwins/digitaltwins/write Добавление цифровых двойников, добавление связи, обновление, обновление компонента
Microsoft.DigitalTwins/digitaltwins/read Получение цифровых двойников по идентификатору, получение компонента, получение связи по идентификатору, списка входящих связей, списка связей
Microsoft.DigitalTwins/digitaltwins/delete Удаление цифровых двойников, удаление связи
Microsoft.DigitalTwins/digitaltwins/action Отправка данных телеметрии компонента цифровых двойников, отправка данных телеметрии

Схемы журналов

Каждая категория имеет схему, определяющую, как направляются отчеты о событиях в этой категории. Каждая отдельная запись журнала хранится как текст, а также в формате большого двоичного объекта JSON. Ниже для каждого типа журнала представлены поля в журнале и примеры тела JSON.

ADTDigitalTwinsOperation, ADTModelsOperation и ADTQueryOperation используют согласованную схему журналов API. В ADTEventRoutesOperation схема расширена, в своих свойствах она содержит поле endpointName.

Схемы журналов API

Эта схема журнала является согласованной для ADTDigitalTwinsOperation, ADTModelsOperation, ADTQueryOperation. Та же схема используется также и для ADTEventRoutesOperation, за исключением имени операции Microsoft.DigitalTwins/eventroutes/action (дополнительные сведения об этой схеме см. в следующем разделе Схемы журналов исходящего трафика).

Схема содержит сведения, относящиеся к вызовам API для экземпляра Azure Digital Twins.

Ниже приведены описания полей и свойств для журналов API.

Имя поля Тип данных Описание
Time Дата и время Дата и время, когда произошло событие, в формате UTC
ResourceId Строка Идентификатор ресурса Azure Resource Manager для ресурса, в котором произошло событие
OperationName Строка Тип действия, выполняемого во время события
OperationVersion Строка Версия API, используемая во время события
Category Строка Тип создаваемого ресурса
ResultType Строка Результат события
ResultSignature Строка Код состояния HTTP для события
ResultDescription Строка Дополнительные сведения о событии
DurationMs Строка Время, затраченное на выполнение события, в миллисекундах
CallerIpAddress Строка Маскированный исходный IP-адрес для события
CorrelationId Guid Уникальный идентификатор события
ApplicationId Guid Идентификатор обращения, используемый в носителе при авторизации
Level Int Степень серьезности события заносимого в журнал
Location Строка Регион, в котором произошло событие
RequestUri URI Версия конечной точки, используемая во время события
TraceId Строка TraceId как часть контекста трассировки W3C. Идентификатор всей трассировки, используемой для уникальной идентификации распределенной трассировки между системами.
SpanId Строка SpanId как часть контекста трассировки W3C. Идентификатор этого запроса в трассировке.
ParentId Строка ParentId как часть контекста трассировки W3C. Запрос без родительского идентификатора является корнем трассировки.
TraceFlags Строка TraceFlags как часть контекста трассировки W3C. управляет флагами трассировки, такими как выборка, уровень трассировки и т. д.
TraceState Строка TraceState как часть контекста трассировки W3C. Дополнительные сведения от поставщика об идентификации трассировки, для охвата различных распределенных систем трассировки.

Ниже приведены примеры с телом JSON для таких типов журналов.

ADTDigitalTwinsOperation

{
  "time": "2020-03-14T21:11:14.9918922Z",
  "resourceId": "/SUBSCRIPTIONS/BBED119E-28B8-454D-B25E-C990C9430C8F/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": "2f6a8e64-94aa-492a-bc31-16b9f0b16ab3",
  "identity": {
    "claims": {
      "appId": "872cd9fa-d31f-45e0-9eab-6e460a02d1f1"
    }
  },
  "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/BBED119E-28B8-454D-B25E-C990C9430C8F/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": "9dcb71ea-bb6f-46f2-ab70-78b80db76882",
  "identity": {
    "claims": {
      "appId": "872cd9fa-d31f-45e0-9eab-6e460a02d1f1"
    }
  },
  "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/BBED119E-28B8-454D-B25E-C990C9430C8F/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": "1ee2b6e9-3af4-4873-8c7c-1a698b9ac334",
  "identity": {
    "claims": {
      "appId": "872cd9fa-d31f-45e0-9eab-6e460a02d1f1"
    }
  },
  "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

Ниже приведен пример текста JSON для ADTEventRoutesOperation типа, который не Microsoft.DigitalTwins/eventroutes/action относится к типу (дополнительные сведения об этой схеме см. в следующем разделе: схемы журналов исходящего трафика).

  {
    "time": "2020-10-30T22:18:38.0708705Z",
    "resourceId": "/SUBSCRIPTIONS/BBED119E-28B8-454D-B25E-C990C9430C8F/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": "7f73ab45-14c0-491f-a834-0827dbbf7f8e",
    "identity": {
      "claims": {
        "appId": "872cd9fa-d31f-45e0-9eab-6e460a02d1f1"
      }
    },
    "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"
    }
  },

Схемы журналов исходящего трафика

В следующем примере представлена схема для журналов ADTEventRoutesOperation, характерных для имени операции Microsoft.DigitalTwins/eventroutes/action. Такие журналы содержат подробные сведения об исключениях и операциях API, связанных с конечными точками исходящего трафика, которые подключены к экземпляру Azure Digital Twins.

Имя поля Тип данных Описание
Time Дата и время Дата и время, когда произошло событие, в формате UTC
ResourceId Строка Идентификатор ресурса Azure Resource Manager для ресурса, в котором произошло событие
OperationName Строка Тип действия, выполняемого во время события
Category Строка Тип создаваемого ресурса
ResultDescription Строка Дополнительные сведения о событии
CorrelationId Guid Уникальный идентификатор для события, предоставленный пользователем
ApplicationId Guid Идентификатор обращения, используемый в носителе при авторизации
Level Int Степень серьезности события заносимого в журнал
Location Строка Регион, в котором произошло событие
TraceId Строка TraceId как часть контекста трассировки W3C. Идентификатор всей трассировки, используемой для уникальной идентификации распределенной трассировки между системами.
SpanId Строка SpanId как часть контекста трассировки W3C. Идентификатор этого запроса в трассировке.
ParentId Строка ParentId как часть контекста трассировки W3C. Запрос без родительского идентификатора является корнем трассировки.
TraceFlags Строка TraceFlags как часть контекста трассировки W3C. управляет флагами трассировки, такими как выборка, уровень трассировки и т. д.
TraceState Строка TraceState как часть контекста трассировки W3C. Дополнительные сведения от поставщика об идентификации трассировки, для охвата различных распределенных систем трассировки.
EndpointName Строка Имя конечной точки исходящего трафика, созданной в Azure Digital Twins

Ниже приведены примеры с телом JSON для таких типов журналов.

ADTEventRoutesOperation для Microsoft.DigitalTwins/eventroutes/action

Ниже приведен пример тела JSON для ADTEventRoutesOperation, принадлежащего к типу Microsoft.DigitalTwins/eventroutes/action.

{
  "time": "2020-11-05T22:18:38.0708705Z",
  "resourceId": "/SUBSCRIPTIONS/BBED119E-28B8-454D-B25E-C990C9430C8F/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": "7f73ab45-14c0-491f-a834-0827dbbf7f8e",
  "identity": {
    "claims": {
      "appId": "872cd9fa-d31f-45e0-9eab-6e460a02d1f1"
    }
  },
  "level": "4",
  "location": "southcentralus",
  "uri": "",
  "properties": {
    "endpointName": "myEventHub"
  },
  "traceContext": {
    "traceId": "95ff77cfb300b04f80d83e64d13831e7",
    "spanId": "b630da57026dd046",
    "parentId": "9f0de6dadae85945",
    "traceFlags": "01",
    "tracestate": "k1=v1,k2=v2"
  }
},

Дальнейшие действия