Создание преобразования в Azure Monitor

Преобразования в Azure Monitor фильтруют или изменяют входящие данные перед сохранением в рабочей области Log Analytics. Реализуйте преобразования в виде инструкции языка запросов Kusto (KQL) в правиле сбора данных (DCR). В этой статье приведены рекомендации по созданию и тестированию запроса преобразования и его добавлению в DCR.

Базовая структура запросов

Все запросы преобразования начинаются с source. Это виртуальная таблица, представляющая входной поток. Затем можно использовать любые поддерживаемые операторы KQL для фильтрации, изменения или добавления столбцов в данные, как и в любой другой таблице. Запрос применяется отдельно к каждой записи, отправляемой источником данных.

Выходные данные запроса должны соответствовать схеме целевой таблицы со следующими рекомендациями:

• Исключите столбцы, которые не нужны, чтобы сократить затраты. При пропуске столбца этот столбец пуст для каждой записи в целевой таблице.
• Исключите столбцы, которые не входят в выходную таблицу. Дополнительные столбцы принимаются без ошибок, но вы платите за прием данных, которые не хранятся.
• Укажите допустимую метку времени в столбце с именем TimeGenerated и типом datetime. Если источник данных не включает это свойство, добавьте его с помощью extend или project.

Следующее преобразование — это пример, который выполняет три функции:

• Фильтрует входящие данные с помощью инструкции where .
• Добавляет новый столбец Properties с помощью extend оператора с parse_json функцией для анализа значений JSON из входящего properties столбца.
• Форматирует выходные данные преобразования, чтобы точно соответствовать столбцам целевой таблицы с помощью project оператора.

source
| where severity == "Critical" 
| extend Properties = parse_json(properties)
| project
    TimeGenerated = todatetime(["time"]),
    Category = category,
    StatusDescription = StatusDescription,
    EventName = name,
    EventId = tostring(Properties.EventId)

См. примеры и сценарии правил сбора данных (DCR) в Azure Monitor, чтобы ознакомиться с примерами для различных сценариев.

Создание запроса преобразования

Перед добавлением преобразования в DCR создайте и протестируйте запрос в Log Analytics. Когда запрос возвращает ожидаемые результаты, замените имя таблицы на source и добавьте его в DCR, как описано в разделе «Добавление преобразования в DCR».

Например, чтобы отфильтровать события системного журнала, начните с этого запроса в Log Analytics:

Syslog | where SeverityLevel != 'info'

Затем замените имя таблицы на source в DCR:

source | where SeverityLevel != 'info'

Добавление преобразования в DCR

После создания запроса преобразования добавьте его в DCR, выполнив следующие действия:

1. Получите текущее определение DCR. Откройте определение DCR в пользовательском интерфейсе и выберите представление JSON или экспортируйте JSON с помощью Azure CLI:

   az monitor data-collection rule show --name {dcrName} --resource-group {resourceGroupName} > dcr.json
   

   Дополнительные сведения см. в разделе Создание и изменение правил сбора данных (DCR) в Azure Monitor.

2. dataFlows Найдите раздел DCR. Этот раздел связывает источник данных с назначением.

3. Добавьте свойство transformKql JSON в поток данных, который нужно преобразовать. Задайте значение запроса преобразования в одной строке. Преобразование применяется к входящему потоку перед отправкой в место назначения. Он применяется только к тому потоку данных, даже если тот же поток или назначение используется в других потоках данных.

4. Сохраните и разверните обновленный DCR:

   az monitor data-collection rule update --name {dcrName} --resource-group {resourceGroupName} --body @dcr.json
   

   Другие методы см. в разделе Создание и изменение правил сбора данных (DCR) в Azure Monitor.

Если свойство не задано transformKql или если задано его значение source, преобразование не применяется. Входящие данные отправляются в место назначения без изменений.

В следующем примере нет transformKql свойства, поэтому входящие данные отправляются в место назначения без изменения.

"dataFlows": [ 
    { 
        "streams": [ 
        "Microsoft-Syslog" 
        ], 
        "destinations": [ 
        "centralWorkspace" 
        ] 
    } 
] 

В следующем примере, transformKql имеет простой запрос на source, поэтому данные, которые поступают, отправляются в место назначения без изменений. Его функциональные возможности идентичны предыдущему примеру.

"dataFlows": [ 
    { 
        "streams": [ 
        "Microsoft-Syslog" 
        ], 
        "transformKql": "source", 
        "destinations": [ 
        "centralWorkspace" 
        ] 
    } 
] 

В следующем примере имеется запрос, transformKql который фильтрует данные, поэтому только сообщения об ошибках отправляются в место назначения.

"dataFlows": [ 
    { 
        "streams": [ 
        "Microsoft-Syslog" 
        ], 
        "transformKql": "source | where message has 'error'", 
        "destinations": [ 
        "centralWorkspace" 
        ] 
    } 
] 

Создание многоэтапного преобразования (предварительная версия)

Многоэтапные преобразования используют раздел transformations в DCR для определения конвейеров на основе обработчиков, на которые источники данных и потоки данных ссылаются с помощью свойства transform. В отличие от одноэтапных преобразований, использующих transformKqlмногоэтапные преобразования, выполняются на стороне клиента (до выхода данных из агента) или на стороне приема (до достижения рабочей области) или обоих.

• Преобразования на стороне клиента — выполнение на агенте до отправки данных. Эти преобразования сокращают объем данных в источнике и могут фильтровать, анализировать или дополнять данные перед передачей.
• Преобразования на стороне приема — выполняются в службе после поступления данных, но до хранения. Эти преобразования могут применять выражения KQL и дополнительно дополнять данные.

В многоэтапном конвейере процессор — это именованный шаг обработки, который выполняется в последовательности, например фильтрация, анализ, обогащение или применение KQL. Обработчик заголовков объявляет входной формат конвейера (например, header.Syslog для данных системного журнала).

Общие сведения см. в разделе " Многоэтапные преобразования". Полный справочник по схеме см. в разделе "Структура DCR — преобразования".

Создание многоэтапного преобразования

Создайте многоэтапное преобразование с помощью портала Azure или программно.

В следующем примере создается DCR с преобразованием на стороне клиента, которое фильтрует данные системного журнала, чтобы сохранить только события проверки подлинности, и преобразование на стороне приема, которое применяет KQL к потоку перед его сохранением.

Определение DCR включает следующие ключевые разделы:

• streamDeclarations — определяет схему пользовательских потоков, используемых между этапами обработки
• dataSources — настраивает источник данных с помощью свойства transform, которое ссылается по имени на преобразование на стороне клиента
• destinations — место отправки данных
• dataFlows — сопоставляет потоки с целевыми объектами с необязательным свойством transform для обработки на стороне приема данных
• transformations — определяет именованные конвейеры обработчика, на которые ссылаются источники данных и потоки данных.

Проверьте DCR, проверив их на портале Azure в разделе Monitor>Правила сбора данных.

{
    "location": "eastus",
    "properties": {
        "streamDeclarations": {
            "Custom-FilteredSyslog": {
                "columns": [
                    { "name": "TimeGenerated", "type": "datetime" },
                    { "name": "Facility", "type": "string" },
                    { "name": "Message", "type": "string" },
                    { "name": "Host", "type": "string" },
                    { "name": "SeverityNumber", "type": "int" }
                ]
            }
        },
        "dataSources": {
            "syslog": [
                {
                    "name": "syslogAuth",
                    "facilityNames": ["auth", "authpriv"],
                    "logLevels": ["*"],
                    "transform": "client_filter_auth",
                    "streams": ["Custom-FilteredSyslog"]
                }
            ]
        },
        "destinations": {
            "logAnalytics": [
                {
                    "name": "myWorkspace",
                    "workspaceResourceId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}",
                    "workspaceId": "{workspaceId}"
                }
            ]
        },
        "dataFlows": [
            {
                "streams": ["Custom-FilteredSyslog"],
                "transform": "ingestion_enrich_syslog",
                "destinations": ["myWorkspace"],
                "outputStream": "Microsoft-Syslog"
            }
        ],
        "transformations": [
            {
                "name": "client_filter_auth",
                "headerProcessor": {
                    "processor": "header.Syslog",
                    "configuration": {}
                },
                "processors": [
                    {
                        "processor": "filter.Basic",
                        "configuration": {
                            "any": [
                                {
                                    "all": [
                                        {
                                            "columnName": "Facility",
                                            "operator": "==",
                                            "value": "auth"
                                        }
                                    ]
                                }
                            ]
                        }
                    }
                ]
            },
            {
                "name": "ingestion_enrich_syslog",
                "headerProcessor": {
                    "processor": "header.CustomStream",
                    "configuration": {
                        "streamId": "Custom-FilteredSyslog"
                    }
                },
                "processors": [
                    {
                        "processor": "transform.KQL",
                        "configuration": {
                            "expression": "source | extend EnrichedMsg = strcat(Host, ': ', Message)"
                        }
                    }
                ]
            }
        ]
    }
}

$dcr = Get-Content -Path "dcr.json" -Raw
Invoke-AzRestMethod `
    -Path "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Insights/dataCollectionRules/{dcrName}?api-version=2025-05-11" `
    -Method PUT `
    -Payload $dcr

Создайте преобразование рабочей области DCR

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

Используйте один из следующих методов, чтобы создать преобразование DCR для вашей рабочей области и добавить в него одно или несколько преобразований.

{
    "kind": "WorkspaceTransforms",
    "location": "eastus",
    "properties": {
        "dataSources": {},
        "destinations": {
            "logAnalytics": [
                {
                    "workspaceResourceId": "/subscriptions/71b36fb6-4fe4-4664-9a7b-245dc62f2930/resourcegroups/my-resource-group/providers/microsoft.operationalinsights/workspaces/my-workspace",
                    "name": "MyWorkspace"
                }
            ]
        },
        "dataFlows": [
            {
                "streams": [
                    "Microsoft-Table-LAQueryLogs"
                ],
                "destinations": [
                    "MyWorkspace"
                ],
                "transformKql": "source | where QueryText !contains 'LAQueryLogs'"
            },
            {
                "streams": [
                    "Microsoft-Table-Event"
                ],
                "destinations": [
                    "MyWorkspace"
                ],
                "transformKql": "source | project-away ParameterXml"
            }
        ]
    }
}

az monitor data-collection rule create \
    --name {dcrName} \
    --resource-group {resourceGroupName} \
    --body @dcr.json

Оптимизация и мониторинг преобразований

Механизмы преобразования выполняют запрос KQL для каждой записи, собранной с помощью DCR, поэтому важно, чтобы они выполнялись эффективно. Время выполнения преобразования способствует общей задержке приема данных, а преобразования, которые занимают слишком много времени для выполнения, могут повлиять на производительность сбора данных и привести к потере данных. Для выполнения оптимальных преобразований должно потребоваться не более 1 секунды. Ознакомьтесь с рекомендациями по оптимизации запросов журналов в Azure Monitor для тестирования запроса перед его реализацией в качестве преобразования и рекомендаций по оптимизации запросов, которые не выполняются эффективно.

Так как преобразования не выполняются в интерактивном режиме, важно постоянно отслеживать их, чтобы убедиться, что они выполняются правильно и не занимают слишком много времени для обработки данных. Сведения о журналах и метрик, отслеживающих работоспособность и производительность преобразований, см. в статье "Мониторинг и устранение неполадок сбора данных DCR в Azure Monitor ". Это включает выявление любых ошибок, возникающих в KQL и в метриках, для отслеживания продолжительности их выполнения.

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

• Длительность трансформации логов за минуту
• Ошибки преобразования логов в минуту

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

Устранение неполадок с преобразованиями

В следующих таблицах перечислены распространенные ошибки преобразования и их разрешения.

Руководства по преобразованию по источнику данных

Способы создания преобразований зависят от метода сбора данных. В следующей таблице приводятся рекомендации по различным способам создания преобразований.

Ограничения и рекомендации

• Преобразования выполняются при приёме данных и увеличивают затраты на обработку данных. Однако фильтрация данных с помощью преобразований может снизить затраты на прием и хранение. Дополнительные сведения см. в разделе Оптимизация затрат и Azure Monitor.
• Не все таблицы в рабочей области Log Analytics поддерживают преобразования. Список поддерживаемых таблиц см. в разделе Tables, которые поддерживают преобразования в журналах Azure Monitor.
• Не все операторы KQL поддерживаются в запросах преобразования. Дополнительные сведения см. в разделе Поддерживаемые возможности KQL в преобразованиях Azure Monitor.
• Хотя преобразование может отправлять один источник данных в несколько таблиц, он не может отправлять данные в несколько рабочих областей. Чтобы отправить данные из одного источника данных в несколько рабочих областей, создайте несколько правил сбора данных (DCRs).
• Преобразование рабочей области DCR не может отправлять один источник данных нескольким таблицам, так как преобразование применяется к самой таблице.
• Преобразования в DCR рабочей области применяются ко всем данным, отправленным в таблицу, независимо от источника данных. Если необходимо применить различные преобразования к разным источникам данных, используйте where инструкцию в запросе преобразования, чтобы применить другую логику к данным из разных источников.
• Для многоэтапных преобразований transform и transformKql взаимоисключают друг друга в каждом потоке данных. DCR может смешивать потоки данных старого типа (transformKql) и нового типа (transform) в разных потоках.
• Для многоэтапных преобразований требуется версия 2025-05-11 API или более поздняя.
• Для данных счётчиков производительности требуются отдельные правила сбора данных (DCR) для компьютеров с Windows и Linux при использовании многоэтапных преобразований. DCR типа All не может использовать одновременно header.WindowsPerformanceCounters и header.LinuxPerformanceCounters в одном преобразовании на стороне клиента.

Связанный контент

• Мониторинг и устранение неполадок при сборе данных DCR в Azure Monitor — отслеживание производительности преобразований и диагностика ошибок.
• Поддерживаемые возможности KQL в преобразованиях Azure Monitor — проверьте, какие операторы KQL поддерживаются в преобразованиях.
• Структура правила сбора данных (DCR) в Azure Monitor — полный справочник по схеме JSON для определений DCR.
• Примеры преобразований для Azure Monitor — примеры запросов преобразования для распространённых сценариев.
• Создайте правило сбора данных и связь с ним с виртуальной машиной с помощью агента Azure Monitor.
• Оптимизация затрат и Azure Monitor — узнайте, как преобразования влияют на затраты на прием данных.