Compartilhar via

Recursos de KQL com suporte nas transformações do Azure Monitor

  • Artigo

As transformações no Azure Monitor permitem executar uma consulta KQL em relação aos dados do Azure Monitor recebidos para filtrá-los ou modificá-los antes que eles sejam armazenados em um workspace do Log Analytics. Este artigo detalha considerações e recursos com suporte de KQL em consultas de transformação, além de operadores especiais que só estão disponíveis em transformações.

Como as transformações são aplicadas a cada registro individualmente, elas não podem 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.

Somente os operadores listados neste artigo têm suporte em transformações. Não há suporte para outros operadores que possam ser usados em outras consultas de log em transformações.

Considerações especiais

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.

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":{}}')

Funções especiais

As funções a seguir só estão disponíveis em transformações. Elas não podem ser usadas em outras consultas de log.

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

Saída de exemplo da função parse_cef_dictionary.

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

Captura de tela da saída de exemplo da função geo_location.

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.

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 em uma transformação 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 print, que sempre produz uma única linha. Por exemplo:

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

Operadores de tabela compatíveis

Operadores escalares com suporte

Funções escalares

Citações do identificador

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

Próximas etapas