Compartilhar via

Estrutura de transformação no Azure Monitor

  • Artigo

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 operador extend
  • 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 DCR (regra de coleta de dados) 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.

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ção parse_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ções de expressão tabular

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
  • print, um operador que sempre produz uma única linha. Por exemplo:
print x = 2 + 2, y = 5 | extend z = exp2(x) + exp2(y)

Operadores de tabela

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.

  • ==
  • !=
  • =~
  • !~
  • contém
  • !contains
  • contains_cs
  • !contains_cs
  • tem
  • !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

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

Sample output of parse_cef_dictionary function.

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")

Screenshot of sample output of geo_location function.

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