Simple Log Service:Referência geral

* | where "A B" like '%error%'

Resolução de conflitos de nomes de campos

Durante o upload de logs ou a execução da SPL, o processamento sensível a maiúsculas e minúsculas pode causar conflitos de nomes de campos. Por exemplo, um log bruto pode conter tanto o campo Method quanto o campo method. A SPL resolve esses conflitos de maneiras diferentes, dependendo do cenário.

Para evitar essas situações, padronize os nomes dos campos em seus logs brutos.

Conflitos nos resultados de saída

Para obter a lista completa de campos reservados, consulte Campos reservados. A SPL lê dados da estrutura LogGroup como entrada. Para mais informações sobre a definição de LogGroup, consulte Codificação de dados. Se os dados brutos gravados no Simple Log Service não estiverem codificados no formato padrão LogGroup, alguns campos reservados poderão aparecer em LogContent em vez de sua localização padrão. A SPL trata esses campos reservados da seguinte forma:

• Para os campos __source__, __topic__, __time__ e __time_ns_part__, a SPL lê seus valores da estrutura padrão LogGroup e ignora quaisquer campos com os mesmos nomes em LogContent.

• Para campos de tag com o prefixo __tag__: , a SPL tenta primeiro ler seus valores da estrutura padrão LogGroup. Se nenhum valor for encontrado, a SPL o lê de LogContent. Por exemplo, para o campo __tag__:ip, a SPL tenta primeiro ler o campo com a chave ip da lista LogTag. Se o campo não existir, a SPL então lê o campo de log com a chave __tag__:ip dos campos de log personalizados em LogContent.

O campo __line__ para pesquisa de texto completo

Para filtrar logs brutos no console ou usando a operação de API GetLogstoreLogs, use o campo __line__.

Exemplo

• Pesquise a palavra-chave error nos logs.

  * | where __line__ like '%error%'

• Se um log contiver um campo chamado __line__, coloque o nome do campo entre crases para referenciá-lo.

  * | where `__line__` ='20'

Tipos de dados inconsistentes entre valores antigos e novos

O valor original do campo de entrada é mantido.

Exemplo

• Exemplo 1: Um campo renomeado por uma instrução project tem um nome conflitante.

  • Instrução SPL

    * 
    | extend status=cast(status as BIGINT) -- Convert the type of the status field to BIGINT.
    | project code=status -- The new value's type (BIGINT) differs from the old value's type (VARCHAR), so the old value is kept.

  • Dados de entrada

    status: '200'
    code: 'Success'

  • Resultado de saída

    code: 'Success'

• Exemplo 2: Um campo extraído por uma instrução parse-json tem um nome conflitante.

  • Instrução SPL

    * 
    | extend status=cast(status as BIGINT) -- Convert the type of the status field to BIGINT.
    | parse-json content -- The old type of status is BIGINT and the new type is VARCHAR. The old value is retained.

  • Dados de entrada

    status: '200'
    content: '{"status": "Success", "body": "this is test"}'

  • Resultado de saída

    content: '{"status": "Success", "body": "this is test"}'
    status: 200
    body: 'this is test'

Tipos de dados consistentes entre valores antigos e novos

Se o valor de entrada for nulo, o novo valor será usado. Caso contrário, o comportamento é determinado pelo parâmetro mode na instrução, conforme definido na tabela a seguir.

Exemplo

• Exemplo 1: Um campo renomeado por uma instrução project tem um nome conflitante e o mesmo tipo. O modo padrão é overwrite.

  • Instrução SPL

  * | project code=status -- The old and new types of code are both VARCHAR. The new value is used based on the overwrite mode.

  • Dados de entrada

    status: '200'
    code: 'Success'

  • Resultado de saída

    code: '200'

• Exemplo 2: Um campo extraído por uma instrução parse-json tem um nome conflitante e o mesmo tipo. O modo padrão é overwrite.

  • Instrução SPL

    * | parse-json content -- The old and new types of status are both VARCHAR. The new value is used based on the overwrite mode.

  • Dados de entrada

    status: '200'
    content: '{"status": "Success", "body": "this is test"}'

  • Resultado de saída

    content: '{"status": "Success", "body": "this is test"}'
    status: 'Success'
    body: 'this is test'

• Exemplo 3: Um campo extraído por uma instrução parse-json tem um nome conflitante e o mesmo tipo. O modo está definido como preserve.

  • Instrução SPL

    * | parse-json -mode='preserve' content -- The old and new types of status are both VARCHAR. The old value is retained based on the preserve mode.

  • Dados de entrada

    status: '200'
    content: '{"status": "Success", "body": "this is test"}'

  • Resultado de saída

    content: '{"status": "Success", "body": "this is test"}'
    status: '200'
    body: 'this is test'

Conversão de tipos de dados

Tipo inicial

Quando a SPL processa dados, todos os campos de entrada são inicialmente do tipo VARCHAR, exceto os campos de tempo de log. Se o processamento subsequente exigir um tipo de dados diferente, converta o tipo explicitamente.

Exemplo

Para filtrar logs de acesso com código de status 5xx, converta o campo status para o tipo BIGINT antes da comparação.

* -- The initial type of the status field is VARCHAR.
| where cast(status as BIGINT) >= 500 -- Convert the type of the status field to BIGINT, and then perform the comparison.

Retenção de tipo

Após usar a instrução extend para converter o tipo de dados de um campo, o processamento subsequente mantém o tipo convertido.

Exemplo

* -- A Logstore is used as input data. Except for time fields, all fields are initially of the VARCHAR type.
| where __source__='127.0.0.1' -- Filter on the __source__ field.
| extend status=cast(status as BIGINT) -- Convert the type of the status field to BIGINT.
| project status, content
| where status>=500 -- The type of the status field remains BIGINT, so it can be directly compared with the number 500.

Geração de valores nulos

Durante o processamento de dados da SPL, valores nulos são gerados nos seguintes cenários:

1. Se um campo usado em uma expressão SPL não existir nos dados de entrada, seu valor será tratado como nulo durante os cálculos.

2. Se ocorrer uma exceção durante o cálculo de uma expressão SPL, o resultado será nulo. Por exemplo, quando uma conversão de tipo cast falha ou um índice de array está fora dos limites.

Exemplo

1. Se um campo não existir, seu valor será tratado como nulo nos cálculos.

   • Instrução SPL

     * | extend withoutStatus=(status is null)

   • Dados de entrada

     # Entry 1
     status: '200'
     code: 'Success'
     
     # Entry 2
     code: 'Success'

   • Resultado de saída

     # Entry 1
     status: '200'
     code: 'Success'
     withoutStatus: false
     
     # Entry 2
     code: 'Success'
     withoutStatus: true

2. Se ocorrer uma exceção durante o cálculo, o resultado será nulo.

   • Instrução SPL

     *
     | extend code=cast(code as BIGINT) -- Failed to convert the code field to BIGINT.
     | extend values=json_parse(values)
     | extend values=cast(values as ARRAY(BIGINT))
     | extend last=arr[10] -- Array index out of bounds.

   • Dados de entrada

     status: '200'
     code: 'Success'
     values: '[1,2,3]'

   • Resultado de saída

     status: '200'
     code: null
     values: [1, 2, 3]
     last: null

Eliminação de valores nulos

Para eliminar valores nulos durante os cálculos, use a expressão COALESCE. Ela retorna o primeiro valor não nulo de uma lista de expressões. Também é possível especificar um valor padrão para uso caso todas as expressões resultem em nulo.

Exemplo

Leia o último elemento de um array. Se o array estiver vazio, o valor padrão será 0.

• Instrução SPL

  *
  | extend values=json_parse(values)
  | extend values=cast(values as ARRAY(BIGINT))
  | extend last=COALESCE(values[3], values[2], values[1], 0)

• Dados de entrada

  # Entry 1
  values: '[1, 2, 3]'
  
  # Entry 2
  values: '[]'

• Resultado de saída

  # Entry 1
  values: [1, 2, 3]
  last: 3
  
  # Entry 2
  values: []
  last: 0

Aspas simples

Aspas simples delimitam literais de string. Se o literal de string contiver uma aspa simples, use uma aspa simples adicional para escapá-la.

Aspas duplas

Aspas duplas delimitam nomes de campos. Se o nome do campo contiver uma aspa dupla, use uma aspa dupla adicional para escapá-la.