Estrutura de transformação no Azure Monitor

Artigo
10/30/2024

As Transformações no Azure Monitor permitem filtrar ou modificar dados de entrada antes de serem armazenados em um espaço de trabalho do Log Analytics. Eles são implementados como uma instrução Linguagem de Consulta Kusto (KQL) 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. Ela deve entender o formato dos dados de entrada e criar a saída na estrutura da tabela de destino. Uma tabela virtual nomeada source representa o fluxo de entrada. source colunas de tabela correspondem à definição de fluxo de dados de entrada. Segue 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 operadorextend.
Formata a saída para corresponder às colunas da tabela de destino usando o operador project.

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 da KQL

Como a transformação é aplicada a cada registro individualmente, ela não pode usar nenhum operador de KQL que atue em vários registros. Há suporte apenas para operadores que levam uma única linha como entrada e não retornam mais de uma linha. Por exemplo, não há suporte para summarize, pois resume vários registros. Confira Recursos de KQL com suporte para ver uma lista completa dos recursos com suporte.

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 uma DCR, incluindo detalhes e limitações da KQL (Linguagem de Consulta Kusto) usada para a instrução da transformação.

Comando Analisar

O comando analisar em uma transformação é limitado a 10 colunas por instrução por motivos de desempenho. Se sua transformação exigir a análise de mais de 10 colunas, divida-a em várias instruções, conforme descrito em Interromper comandos de análise grandes.

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 na final extend ou project no bloco! Criar ou atualizar um DCR sem TimeGenerated na saída de uma transformação levará a um erro.

Manipular 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-o como uma 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 utilizado na transformação do KQL:

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

Literais dinâmicos

Use a funçãoparse_json para lidar com literais dinâmicos.

Por exemplo, as consultas a seguir oferecem as mesmas funcionalidades:

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 de KQL com suporte

Instruções com suporte

Instrução LET

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

Instrução TABULAR EXPRESSION

As únicas fontes de dados com suporte para a instrução KQL são as seguinte:

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

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

Operador print, que sempre produz uma única linha. Por exemplo:
```
print x = 2 + 2, y = 5 | extend z = exp2(x) + exp2(y)
```

Operadores de tabela

extend
project
print
where
parse
project-away
project-rename
datatable
columnifexists (use columnifexists em vez de column_ifexists)

Operadores escalares

Operadores numéricos

Todos os operadores numéricos têm suporte.

Operadores aritméticos Datetime e Timespan

Todos os operadores aritméticos Datetime e Timespan têm suporte.

Operações de cadeia de caracteres

Há suporte para os seguintes Operadores de cadeia de caracteres.

==
!=
=~
!~
contains
!contains
contains_cs
!contains_cs
has
!has
has_cs
!has_cs
startswith
!startswith
startswith_cs
!startswith_cs
endswith
!endswith
endswith_cs
!endswith_cs
matches regex
in
!in

Operadores bit a bit

Há suporte para os seguintes Operadores Bitwise.

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 Dynamic e array

Funções matemáticas

Funções condicionais

Funções de cadeia de caracteres

base64_encodestring (use base64_encodestring em vez de base64_encode_tostring)
base64_decodestring (use base64_decodestring em vez de base64_decode_tostring)
countof
extract
extract_all
indexof
isempty
isnotempty
parse_json
replace
split
strcat
strcat_delim
strlen
substring
tolower
toupper
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 de Extensão 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, conforme mostrado no exemplo abaixo.

| 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

Considerando uma cadeia de caracteres que contém endereço IP (há suporte para IPv4 e IPv6), a função geo_location retorna uma localização geográfica aproximada, incluindo os seguintes atributos:

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

| extend GeoLocation = geo_location("1.0.0.5")

Importante

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

Citações do identificador

Use as citações do identificador conforme necessário.

Próximas etapas

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.

Compartilhar via

Estrutura de transformação no Azure Monitor