Estrutura da transformação no Azure Monitor

Artigo
03/05/2024

As transformações no Azure Monitor permitem filtrar ou modificar dados de entrada antes que eles sejam armazenados em um espaço de trabalho do Log Analytics. Eles são implementados como uma instrução KQL (Kusto Query Language) em uma regra de coleta de dados (DCR). Este artigo fornece detalhes sobre como essa consulta é estruturada e as limitações permitidas na linguagem KQL.

Estrutura de transformação

A instrução KQL é aplicada individualmente a cada entrada na fonte de dados. Ele deve entender o formato dos dados de entrada e criar saída na estrutura da tabela de destino. Uma tabela virtual chamada source representa o fluxo de entrada. source As colunas da tabela correspondem à definição do fluxo de dados de entrada. Segue-se um exemplo típico de uma transformação. Este exemplo inclui a seguinte funcionalidade:

Filtra os dados de entrada com uma instrução where
Adiciona uma nova coluna usando o operador extend
Formata a saída para corresponder às colunas da tabela de destino usando o operador do projeto

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

Limitações do KQL

Como a transformação é aplicada a cada registro individualmente, ela não pode usar nenhum operador KQL que atue em vários registros. Somente operadores que usam uma única linha como entrada e não retornam mais de uma linha são suportados. Por exemplo, resumir não é suportado, pois resume vários registros. Consulte Recursos KQL suportados para obter uma lista completa dos recursos suportados.

As transformações em uma regra de coleta de dados (DCR) permitem filtrar ou modificar dados de entrada antes que eles sejam armazenados em um espaço de trabalho do Log Analytics. Este artigo descreve como criar transformações em um DCR, incluindo detalhes e limitações da KQL (Kusto Query Language) usada para a instrução transform.

Colunas necessárias

A saída de cada transformação deve conter um carimbo de data/hora válido em uma coluna chamada TimeGenerated do tipo datetime. Certifique-se de incluí-lo no final extend ou project bloco! Criar ou atualizar um DCR sem TimeGenerated na saída de uma transformação levará a um erro.

Tratamento de dados dinâmicos

Considere a seguinte entrada com dados dinâmicos:

{
    "TimeGenerated" : "2021-11-07T09:13:06.570354Z",
    "Message": "Houston, we have a problem",
    "AdditionalContext": {
        "Level": 2,
        "DeviceID": "apollo13"
    }
}

Para acessar as propriedades em AdditionalContext, defina-a como coluna de tipo dinâmico no fluxo de entrada:

"columns": [
    {
        "name": "TimeGenerated",
        "type": "datetime"
    },
    {
        "name": "Message",
        "type": "string"
    }, 
    {
        "name": "AdditionalContext",
        "type": "dynamic"
    }
]

O conteúdo da coluna AdditionalContext agora pode ser analisado e usado na transformação KQL:

source
| extend parsedAdditionalContext = parse_json(AdditionalContext)
| extend Level = toint (parsedAdditionalContext.Level)
| extend DeviceId = tostring(parsedAdditionalContext.DeviceID)

Literais dinâmicos

Use a função parse_json para manipular literais dinâmicos.

Por exemplo, as seguintes consultas fornecem a mesma funcionalidade:

print d=dynamic({"a":123, "b":"hello", "c":[1,2,3], "d":{}})

print d=parse_json('{"a":123, "b":"hello", "c":[1,2,3], "d":{}}')

Recursos KQL suportados

Declarações apoiadas

deixar declaração

O lado direito de let pode ser uma expressão escalar, uma expressão tabular ou uma função definida pelo usuário. Somente funções definidas pelo usuário com argumentos escalares são suportadas.

Instruções de expressão tabular

As únicas fontes de dados suportadas para a instrução KQL são as seguintes:

source, que representa os dados de origem. Por exemplo:

source
| where ActivityId == "383112e4-a7a8-4b94-a701-4266dfc18e41"
| project PreciseTimeStamp, Message

operador de impressão , que sempre produz uma única linha. Por exemplo:

print x = 2 + 2, y = 5 | extend z = exp2(x) + exp2(y)

Operadores tabulares

estender
projeto
impressão
em que
analisar
projeto-fora
projeto-renomear
Tabela de dados
columnifexists (use columnifexists em vez de column_ifexists)

Operadores escalares

Operadores numéricos

Todos os operadores numéricos são suportados.

Operadores aritméticos Datetime e Timespan

Todos os operadores aritméticos Datetime e Timespan são suportados.

Operadores de cadeias

Os seguintes operadores String são suportados.

==
!=
=~
!~
contém
!contém
contains_cs
!contains_cs
tem
!tem
has_cs
!has_cs
startswith
!começa com
startswith_cs
!startswith_cs
endswith
!termina com
endswith_cs
!endswith_cs
corresponde regex
presente em
!in

Operadores bit-a-bit

Os seguintes operadores Bitwise são suportados.

binary_and()
binary_or()
binary_xor()
binary_not()
binary_shift_left()
binary_shift_right()

Funções escalares

Funções Bitwise

Funções de conversão

Funções DateTime e TimeSpan

Funções dinâmicas e de matriz

Funções matemáticas

Funções condicionais

Funções de cadeia

base64_encodestring (use base64_encodestring em vez de base64_encode_tostring)
base64_decodestring (use base64_decodestring em vez de base64_decode_tostring)
Conde
extrato
extract_all
índice de
isempty
não está vazio
parse_json
replace
split
STRCAT
strcat_delim
strlen
substring
abaixar
Tosuperior
hash_sha256

Funções de tipo

Funções especiais

parse_cef_dictionary

Dada uma cadeia de caracteres que contém uma mensagem CEF, parse_cef_dictionary analisa a propriedade Extension da mensagem em um objeto de chave/valor dinâmico. Ponto e vírgula é um caractere reservado que deve ser substituído antes de passar a mensagem bruta para o método, como mostrado no exemplo.

| extend cefMessage=iff(cefMessage contains_cs ";", replace(";", " ", cefMessage), cefMessage) 
| extend parsedCefDictionaryMessage =parse_cef_dictionary(cefMessage) 
| extend parsecefDictionaryExtension = parsedCefDictionaryMessage["Extension"]
| project TimeGenerated, cefMessage, parsecefDictionaryExtension

geo_location

Dada uma cadeia de caracteres contendo endereço IP (IPv4 e IPv6 são suportados), geo_location a função retorna a localização geográfica aproximada, incluindo os seguintes atributos:

País
País/Região
Estado
City
Latitude
Longitude

| extend GeoLocation = geo_location("1.0.0.5")

Importante

Devido à natureza do serviço de geolocalização IP utilizado por esta função, ele pode introduzir latência de ingestão de dados se usado excessivamente. Tenha cuidado ao usar esta função mais de várias vezes por transformação.

Citação do identificador

Use a cotação do identificador conforme necessário.

Próximos passos

Crie uma regra de coleta de dados e uma associação a ela a partir de uma máquina virtual usando o agente do Azure Monitor.