Todos os produtos
Search

Este produto

    Simple Log Service:Use Logtail SPL to parse logs

    Central de documentação

    Simple Log Service:Use Logtail SPL to parse logs

    Última atualização: Jul 03, 2026

    O Logtail 2.0 introduz o modo SPL, que combina o desempenho de plugins nativos (C++) com a flexibilidade de plugins de extensão (Go). Use instruções SPL para replicar as funcionalidades dos plugins nativos e de extensão na análise e no processamento de dados de log.

    Pré-requisitos

    Limitações

    • A coleta de logs via SPL exige o Logtail 2.0 ou versão posterior.

    • A configuração pelo console suporta apenas logs de texto. Para outros tipos de dados, use uma API ou CRDs.

    Exemplos de uso

    O tópico Usar SPL para coletar logs de texto oferece um guia completo passo a passo.

    Já o documento Melhores práticas para processamento de dados com SPL aborda os casos de uso mais comuns.

    Procedimento

    Modifique uma configuração

    1. Faça login no console do Simple Log Service.

    2. Na seção Projects, clique em no projeto desejado.

      image

    3. Na aba Log Storage > Logstores, clique em > ao lado do Logstore alvo e escolha Data Collection > Logtail Configuration.

    4. Na lista Logtail Configuration, localize a configuração desejada e clique em Manage Logtail Configuration na coluna Actions.

    5. Clique em Edit. Em Processor Configurations, dentro de Processor Configurations, selecione SPL para Processing Method e clique em Save.

      Global Configurations

      Parâmetro

      Descrição

      Configuration Name

      Insira um nome para a configuração do Logtail. O nome deve ser único no projeto e não pode ser alterado posteriormente.

      Log Topic Type

      Selecione um método para gerar tópicos de log. Para mais informações, consulte Tópicos de log.

      • Machine Group Topic: Os tópicos dos grupos de máquinas são usados como tópicos de log. Escolha esta opção para diferenciar logs de diferentes grupos de máquinas.

      • File Path Extraction: Especifique uma expressão regular personalizada. A parte do caminho do arquivo correspondente à expressão regular será usada como tópico do log. Esta opção é útil para distinguir logs de diferentes origens.

      • Custom: Defina um tópico de log personalizado.

      Advanced Parameters

      Opcional. Configure os parâmetros avançados relacionados às configurações globais. Para mais detalhes, consulte CreateLogtailPipelineConfig.

      Input Configurations

      Parâmetro

      Descrição

      File Path

      Especifique o diretório e o nome dos arquivos de log com base na localização dos logs no servidor, como em uma instância do Elastic Compute Service (ECS).

      • Caminhos de arquivo no Linux devem começar com uma barra (/). Exemplo: /apsara/nuwa/**/app.Log.

      • Caminhos de arquivo no Windows devem começar com a letra da unidade. Exemplo: C:\Program Files\Intel\**\*.Log.

      É possível especificar um diretório e um nome exatos ou usar caracteres curinga para definir o diretório e o nome. Ao configurar este parâmetro, use apenas o asterisco (*) ou o ponto de interrogação (?) como caracteres curinga.

      O Simple Log Service varre todos os níveis do diretório especificado para encontrar os arquivos de log correspondentes às condições definidas. Exemplos:

      • Ao especificar /apsara/nuwa/**/*.log, o Simple Log Service coleta logs dos arquivos com sufixo .log no diretório /apsara/nuwa e em seus subdiretórios recursivos.

      • Se você definir /var/logs/app_*/**/*.log, o Simple Log Service coletará logs dos arquivos que atendem às seguintes condições:

        • O nome do arquivo tem o sufixo .log.

        • O arquivo está armazenado em um subdiretório de /var/logs ou em um de seus subdiretórios recursivos.

        • O nome do subdiretório corresponde ao padrão app_*.

      • Caso especifique /var/log/nginx/**/access*, o Simple Log Service coleta logs dos arquivos cujos nomes começam com access no diretório /var/log/nginx e em seus subdiretórios recursivos.

      Maximum Directory Monitoring Depth

      Defina o número máximo de níveis de subdiretórios a serem monitorados dentro do diretório de arquivos de log especificado. Este parâmetro determina a profundidade de subdiretórios que os caracteres curinga ** no valor de File Path podem abranger. O valor 0 indica que apenas o diretório raiz especificado será monitorado.

      File Encoding

      Selecione o formato de codificação dos arquivos de log.

      First Collection Size

      Informe o tamanho dos dados que o Logtail pode coletar de um arquivo de log na primeira coleta. Valor padrão: 1024. Unidade: KB.

      • Se for menor que 1.024 KB, o Logtail coleta os dados desde o início do arquivo.

      • Se for igual ou superior a 1.024 KB, o Logtail coleta os últimos 1.024 KB de dados do arquivo.

      Configure o First Collection Size conforme as necessidades do seu negócio. Valores válidos: 0 a 10485760. Unidade: KB.

      Collection Blacklist

      Ao ativar esta opção, configure uma lista de bloqueios para indicar quais diretórios ou arquivos o Simple Log Service deve ignorar durante a coleta. É possível especificar nomes exatos de diretórios e arquivos ou usar caracteres curinga. Neste parâmetro, utilize apenas o asterisco (*) ou o ponto de interrogação (?) como curingas.

      Importante

      • Se utilizar caracteres curinga no File Path e precisar ignorar certos subdiretórios, configure a Collection Blacklist especificando os caminhos completos desses subdiretórios.

        Por exemplo, se o File Path for /home/admin/app/log/.log e você quiser ignorar todos os subdiretórios dentro de /home/admin/app1, selecione Directory Blacklist e insira /home/admin/app1/** no campo Directory Name. Inserir apenas /home/admin/app1* fará com que a lista de bloqueios não funcione.

      • O uso de listas de bloqueios gera sobrecarga computacional. Recomendamos limitar a lista a, no máximo, 10 entradas.

      • Não é permitido especificar um diretório terminado com barra (/). Por exemplo, ao definir o diretório /home/admin/dir1/, a lista de bloqueios de diretórios não terá efeito.

      Os seguintes tipos de listas de bloqueio têm suporte:

      File Path Blacklist

      • Se você selecionar File Path Blacklist e inserir /home/admin/private*.log no campo File Path Name, todos os arquivos no diretório /home/admin/ com prefixo private e sufixo .log serão ignorados.

      • Se você selecionar File Path Blacklist e digitar /home/admin/private/_inner.log no campo File Path Name, o sistema ignora todos os arquivos com sufixo _inner.log localizados em subdiretórios com prefixo private dentro de /home/admin/. Nesse caso, o arquivo /home/admin/private/app_inner.log é ignorado, mas /home/admin/private/app.log continua sendo coletado.

      File Blacklist

      Se você selecionar File Blacklist e preencher app_inner.log no campo File Name, qualquer arquivo chamado app_inner.log será excluído da coleta.

      Directory Blacklist

      • Se você selecionar Directory Blacklist e informar /home/admin/dir1 no campo Directory Name, todos os arquivos contidos em /home/admin/dir1 serão ignorados.

      • Se você usar Directory Blacklist com o valor /home/admin/dir* no campo Directory Name, o sistema pula todos os arquivos em subdiretórios com prefixo dir dentro de /home/admin/.

      • Se você definir Directory Blacklist como /home/admin/*/dir no campo Directory Name, os arquivos no subdiretório dir de cada subdiretório de segundo nível dentro de /home/admin/ serão ignorados. Assim, os arquivos em /home/admin/a/dir são pulados, enquanto os em /home/admin/a/b/dir permanecem na coleta.

      Allow File to Be Collected Multiple Times

      Por padrão, apenas uma configuração do Logtail pode coletar logs de um mesmo arquivo. Caso precise coletar múltiplas cópias dos logs desse arquivo, ative a opção Allow File to Be Collected Multiple Times.

      Advanced Parameters

      Opcional. Ajuste os parâmetros avançados referentes aos processadores de entrada. Consulte CreateLogtailPipelineConfig para mais informações.

      Processor Configurations

      Parâmetro

      Descrição

      Log sample

      Uma entrada de log de exemplo para configurar os parâmetros de processamento.

      [2023-10-01T10:30:01,000] [INFO] java.lang.Exception: exception happened
    at TestPrintStackTrace.f(TestPrintStackTrace.java:3)
    at TestPrintStackTrace.g(TestPrintStackTrace.java:7)
    at TestPrintStackTrace.main(TestPrintStackTrace.java:16)

      Multi-line mode

      • Um log multilinha abrange várias linhas consecutivas. Defina um padrão para identificar cada entrada de log individualmente.

        • Custom: Usa uma Regex to Match First Line para reconhecer o início de cada entrada de log.

        • Multi-line JSON: Cada objeto JSON é formatado em múltiplas linhas. Exemplo:

          {
  "name": "John Doe",
  "age": 30,
  "address": {
    "city": "New York",
    "country": "USA"
  }
}

      • Ação em caso de falha na análise:

        Exception in thread "main" java.lang.NullPointerException
    at com.example.MyClass.methodA(MyClass.java:12)
    at com.example.MyClass.methodB(MyClass.java:34)
    at com.example.MyClass.main(MyClass.java:½0)

        Se a divisão do log falhar:

        • Discard: Descarta a entrada de log.

        • Retain Single Line: Mantém cada linha como uma entrada de log separada. Neste exemplo, quatro entradas seriam retidas.

      Processing mode

      Defina o Processing Method como SPL.

      SPL statement

      A documentação de Sintaxe SPL lista todas as instruções disponíveis. Antes da análise, o conteúdo do log é armazenado por padrão no campo content.

      Timeout

      Tempo máximo permitido para a execução de uma única instrução SPL.

    Crie uma configuração

    1. Faça login no console do Simple Log Service.

    2. Na área Data Import, clique em Import Data. Na caixa de diálogo Quick Data Import, vá até a aba Self-managed Open Source/Commercial Software e selecione uma fonte de dados que contenha Text Logs em seu nome.

      Nota

      Atualmente, a configuração via console suporta apenas logs de texto. Para outras fontes de dados (como Kubernetes ou stdout do Docker), use uma API ou CRDs.

      Em Quick Data Collection, clique em Collect Data.

    3. Na etapa Select Logstore, selecione um projeto e um Logstore, depois clique em Next.

      image

    4. Na etapa Machine Group Configurations, configure um grupo de máquinas.

      1. Defina os parâmetros Scenario e Installation Environment conforme necessário.

        Importante

        É obrigatório configurar os parâmetros Scenario e Installation Environment, independentemente da existência prévia de um grupo de máquinas. Essas definições impactam as configurações subsequentes.

      2. Verifique se há um grupo de máquinas listado na seção Applied Server Groups e clique em Next.

        Grupo de máquinas disponível

        Selecione um grupo de máquinas na seção Source Machine Group.

        image

        Nenhum grupo de máquinas disponível

        Clique em Create Machine Group. No painel Create Machine Group, preencha os parâmetros necessários. O parâmetro Machine Group Identifier pode ser definido como IP Address ou Custom Identifier. Para mais detalhes, consulte Criar um grupo de máquinas baseado em identificador personalizado ou Criar um grupo de máquinas baseado em endereço IP.

        Importante

        Se aplicar um grupo de máquinas logo após sua criação, o status de heartbeat poderá aparecer como FAIL. Isso ocorre porque o grupo ainda não estabeleceu conexão com o Simple Log Service. Para resolver, clique em Automatic Retry. Caso o problema persista, veja O que fazer se nenhuma conexão de heartbeat for detectada no Logtail?

    5. Crie uma configuração do Logtail e clique em Next. As seções Global Configurations e Input Configurations seguem o mesmo padrão descrito anteriormente. Na seção Processor Configurations, defina o Processing Method como SPL.

      • Global Configurations

        Parâmetro

        Descrição

        Configuration Name

        Insira um nome para a configuração do Logtail. O nome deve ser único no projeto e não pode ser alterado posteriormente.

        Log Topic Type

        Selecione um método para gerar tópicos de log. Para mais informações, consulte Tópicos de log.

        • Machine Group Topic: Os tópicos dos grupos de máquinas são usados como tópicos de log. Escolha esta opção para diferenciar logs de diferentes grupos de máquinas.

        • File Path Extraction: Especifique uma expressão regular personalizada. A parte do caminho do arquivo correspondente à expressão regular será usada como tópico do log. Esta opção é útil para distinguir logs de diferentes origens.

        • Custom: Defina um tópico de log personalizado.

        Advanced Parameters

        Opcional. Configure os parâmetros avançados relacionados às configurações globais. Para mais detalhes, consulte CreateLogtailPipelineConfig.

      • Input Configurations

        Parâmetro

        Descrição

        File Path

        Especifique o diretório e o nome dos arquivos de log com base na localização dos logs no servidor, como em uma instância do Elastic Compute Service (ECS).

        • Caminhos de arquivo no Linux devem começar com uma barra (/). Exemplo: /apsara/nuwa/**/app.Log.

        • Caminhos de arquivo no Windows devem começar com a letra da unidade. Exemplo: C:\Program Files\Intel\**\*.Log.

        É possível especificar um diretório e um nome exatos ou usar caracteres curinga para definir o diretório e o nome. Ao configurar este parâmetro, use apenas o asterisco (*) ou o ponto de interrogação (?) como caracteres curinga.

        O Simple Log Service varre todos os níveis do diretório especificado para encontrar os arquivos de log correspondentes às condições definidas. Exemplos:

        • Ao especificar /apsara/nuwa/**/*.log, o Simple Log Service coleta logs dos arquivos com sufixo .log no diretório /apsara/nuwa e em seus subdiretórios recursivos.

        • Se você definir /var/logs/app_*/**/*.log, o Simple Log Service coletará logs dos arquivos que atendem às seguintes condições:

          • O nome do arquivo tem o sufixo .log.

          • O arquivo está armazenado em um subdiretório de /var/logs ou em um de seus subdiretórios recursivos.

          • O nome do subdiretório corresponde ao padrão app_*.

        • Caso especifique /var/log/nginx/**/access*, o Simple Log Service coleta logs dos arquivos cujos nomes começam com access no diretório /var/log/nginx e em seus subdiretórios recursivos.

        Maximum Directory Monitoring Depth

        Defina o número máximo de níveis de subdiretórios a serem monitorados dentro do diretório de arquivos de log especificado. Este parâmetro determina a profundidade de subdiretórios que os caracteres curinga ** no valor de File Path podem abranger. O valor 0 indica que apenas o diretório raiz especificado será monitorado.

        File Encoding

        Selecione o formato de codificação dos arquivos de log.

        First Collection Size

        Informe o tamanho dos dados que o Logtail pode coletar de um arquivo de log na primeira coleta. Valor padrão: 1024. Unidade: KB.

        • Se for menor que 1.024 KB, o Logtail coleta os dados desde o início do arquivo.

        • Se for igual ou superior a 1.024 KB, o Logtail coleta os últimos 1.024 KB de dados do arquivo.

        Configure o First Collection Size conforme as necessidades do seu negócio. Valores válidos: 0 a 10485760. Unidade: KB.

        Collection Blacklist

        Ao ativar esta opção, configure uma lista de bloqueios para indicar quais diretórios ou arquivos o Simple Log Service deve ignorar durante a coleta. É possível especificar nomes exatos de diretórios e arquivos ou usar caracteres curinga. Neste parâmetro, utilize apenas o asterisco (*) ou o ponto de interrogação (?) como curingas.

        Importante

        • Se utilizar caracteres curinga no File Path e precisar ignorar certos subdiretórios, configure a Collection Blacklist especificando os caminhos completos desses subdiretórios.

          Por exemplo, se o File Path for /home/admin/app/log/.log e você quiser ignorar todos os subdiretórios dentro de /home/admin/app1, selecione Directory Blacklist e insira /home/admin/app1/** no campo Directory Name. Inserir apenas /home/admin/app1* fará com que a lista de bloqueios não funcione.

        • O uso de listas de bloqueios gera sobrecarga computacional. Recomendamos limitar a lista a, no máximo, 10 entradas.

        • Não é permitido especificar um diretório terminado com barra (/). Por exemplo, ao definir o diretório /home/admin/dir1/, a lista de bloqueios de diretórios não terá efeito.

        Os seguintes tipos de listas de bloqueio têm suporte:

        File Path Blacklist

        • Se você selecionar File Path Blacklist e inserir /home/admin/private*.log no campo File Path Name, todos os arquivos no diretório /home/admin/ com prefixo private e sufixo .log serão ignorados.

        • Se você selecionar File Path Blacklist e digitar /home/admin/private/_inner.log no campo File Path Name, o sistema ignora todos os arquivos com sufixo _inner.log localizados em subdiretórios com prefixo private dentro de /home/admin/. Nesse caso, o arquivo /home/admin/private/app_inner.log é ignorado, mas /home/admin/private/app.log continua sendo coletado.

        File Blacklist

        Se você selecionar File Blacklist e preencher app_inner.log no campo File Name, qualquer arquivo chamado app_inner.log será excluído da coleta.

        Directory Blacklist

        • Se você selecionar Directory Blacklist e informar /home/admin/dir1 no campo Directory Name, todos os arquivos contidos em /home/admin/dir1 serão ignorados.

        • Se você usar Directory Blacklist com o valor /home/admin/dir* no campo Directory Name, o sistema pula todos os arquivos em subdiretórios com prefixo dir dentro de /home/admin/.

        • Se você definir Directory Blacklist como /home/admin/*/dir no campo Directory Name, os arquivos no subdiretório dir de cada subdiretório de segundo nível dentro de /home/admin/ serão ignorados. Assim, os arquivos em /home/admin/a/dir são pulados, enquanto os em /home/admin/a/b/dir permanecem na coleta.

        Allow File to Be Collected Multiple Times

        Por padrão, apenas uma configuração do Logtail pode coletar logs de um mesmo arquivo. Caso precise coletar múltiplas cópias dos logs desse arquivo, ative a opção Allow File to Be Collected Multiple Times.

        Advanced Parameters

        Opcional. Ajuste os parâmetros avançados referentes aos processadores de entrada. Consulte CreateLogtailPipelineConfig para mais informações.

      • Processor Configurations

        Parâmetro

        Descrição

        Log sample

        Uma entrada de log de exemplo para configurar os parâmetros de processamento.

        [2023-10-01T10:30:01,000] [INFO] java.lang.Exception: exception happened
    at TestPrintStackTrace.f(TestPrintStackTrace.java:3)
    at TestPrintStackTrace.g(TestPrintStackTrace.java:7)
    at TestPrintStackTrace.main(TestPrintStackTrace.java:16)

        Multi-line mode

        • Um log multilinha abrange várias linhas consecutivas. Defina um padrão para identificar cada entrada de log individualmente.

          • Custom: Usa uma Regex to Match First Line para reconhecer o início de cada entrada de log.

          • Multi-line JSON: Cada objeto JSON é formatado em múltiplas linhas. Exemplo:

            {
  "name": "John Doe",
  "age": 30,
  "address": {
    "city": "New York",
    "country": "USA"
  }
}

        • Ação em caso de falha na análise:

          Exception in thread "main" java.lang.NullPointerException
    at com.example.MyClass.methodA(MyClass.java:12)
    at com.example.MyClass.methodB(MyClass.java:34)
    at com.example.MyClass.main(MyClass.java:½0)

          Se a divisão do log falhar:

          • Discard: Descarta a entrada de log.

          • Retain Single Line: Mantém cada linha como uma entrada de log separada. Neste exemplo, quatro entradas seriam retidas.

        Processing mode

        Defina o Processing Method como SPL.

        SPL statement

        A documentação de Sintaxe SPL lista todas as instruções disponíveis. Antes da análise, o conteúdo do log é armazenado por padrão no campo content.

        Timeout

        Tempo máximo permitido para a execução de uma única instrução SPL.