Como configurar o agente

Nesta página, fornecemos detalhes sobre as configurações padrão e personalizadas do agente do Stackdriver Logging.

A maioria dos usuários não precisará ler esta página. Leia apenas se:

  • você tiver interesse em aprender detalhes técnicos avançados sobre a configuração do agente do Stackdriver Logging;

  • você quiser alterar a configuração do agente do Stackdriver Logging.

Configuração padrão

O agente do Logging google-fluentd é uma versão modificada do coletor de dados de registro fluentd. Ele é fornecido com uma configuração padrão e, nos casos mais comuns, não requer outras configurações.

Com a configuração padrão, o agente do Logging transmite registros, conforme descrito na lista de registros padrão, para o Stackdriver Logging. É possível configurar o agente para transmitir outros registros. Consulte a seção Como personalizar a configuração do agente do Stackdriver Logging abaixo.

Como funciona o agente do Stackdriver Logging

O agente do Logging usa plug-ins de entrada fluentd para recuperar e extrair logs de eventos de fontes externas, como arquivos em disco, ou para analisar registros de logs de entrada. Os plug-ins de entrada contêm um pacote com o agente ou podem ser instalados separadamente como gems do Ruby. Consulte a lista de plug-ins integrados.

O agente lê registros armazenados nos arquivos usando a instância de VM por meio do plug-in in_tail integrado do fluentd. Cada registro é convertido em uma estrutura de entrada de registro para o Stackdriver Logging. O conteúdo de cada registro de log é gravado principalmente no payload das entradas de registro, mas elas também contêm elementos padrão, como timestamp e severity. O agente do Stackdriver Logging requer que cada registro de log seja marcado com uma tag de formato de string. Todos os filtros e plug-ins de saída correspondem a um conjunto específico de tags. O nome do registro geralmente segue o formato projects/[PROJECT-ID]/logs/[TAG]. Por exemplo, este nome de registro inclui a tag structured-log:

    projects/my-sample-project-12345/logs/structured-log

O plug-in de saída transforma cada mensagem estruturada internalizada em uma entrada de registro no Stackdriver Logging. O payload se torna o texto ou o payload de JSON.

Nas seções a seguir, descrevemos a configuração padrão em detalhes.

Definições da configuração padrão

Nas seções a seguir, descrevemos as definições da configuração padrão do Syslog, o plug-in de entrada direta, as configurações de entrada para registros de aplicativos de terceiros (como os mencionados na lista de registros padrão) e o plug-in fluentd de saída do Google Cloud.

Configuração do Syslog

  • Localização dos arquivos de configuração:

    • Linux: /etc/google-fluentd/config.d/syslog.conf
    • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

      Se você estiver executando um agente do Logging anterior à versão v1-5, o arquivo estará em: C:\GoogleStackdriverLoggingAgent\fluent.conf

  • Descrição: esse arquivo inclui a configuração para especificar o Syslog como uma entrada de registro.

  • Consulte o repositório de configuração.

Nome da configuração Tipo Padrão Descrição
format string /^(?<message>(?<time>[^ ]*\s*[^ ]* [^ ]*) .*)$/ O formato do syslog.
path string /var/log/syslog O caminho do arquivo syslog.
pos_file string /var/lib/google-fluentd/pos/syslog.pos O caminho do arquivo de posição para esta entrada de registro. fluentd gravará a última posição lida nesse arquivo. Consulte a documentação detalhada do fluentd (em inglês).
read_from_head bool true Define se os registros serão lidos a partir do topo do arquivo, em vez do final. Consulte a documentação detalhada do fluentd (em inglês).
tag string syslog A tag de registro dessa entrada.

Configuração do plug-in de entrada in_forward

  • Localização dos arquivos de configuração:

    • Linux: /etc/google-fluentd/config.d/forward.conf
    • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\forward.conf

  • Descrição: esse arquivo inclui a configuração para definir o plug-in de entrada in_forward do fluentd. Com o plug-in in_forward, é possível transmitir os registros por meio de um soquete TCP.

  • Consulte a documentação detalhada do fluentd (em inglês) para saber mais sobre esse plug-in e o repositório de configuração.

Nome da configuração Tipo Padrão Descrição
port int 24224 A porta a ser monitorada.
bind string 127.0.0.1 O endereço de vinculação a ser monitorado. Por padrão, somente as conexões do host local são aceitas. Para abrir esse host, esta configuração precisa ser alterada para 0.0.0.0.

Configuração da entrada de registro de aplicativos de terceiros

  • Localização dos arquivos de configuração:

    • Linux: /etc/google-fluentd/config.d/[APPLICATION_NAME].conf
    • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\[APPLICATION_NAME].conf

  • Descrição: esse diretório inclui arquivos de configuração para especificar arquivos de registros de aplicativos de terceiros como entradas. Cada arquivo, exceto syslog.conf e forward.conf, representa um aplicativo. Por exemplo, apache.conf para o aplicativo do Apache.

  • Consulte o repositório de configuração.

Nome da configuração Tipo Padrão Descrição
format string Varia por aplicativo O formato do registro. Consulte a documentação detalhada do fluentd (em inglês).
path string Varia por aplicativo O caminho dos arquivos de registros. Vários caminhos podem ser especificados, separados por ",". *, e o formato strftime pode ser incluído para adicionar/remover o arquivo de observação dinamicamente. Consulte a documentação detalhada do fluentd (em inglês).
pos_file string Varia por aplicativo O caminho do arquivo de posição para esta entrada de registro. fluentd gravará a última posição lida nesse arquivo. Consulte a documentação detalhada do fluentd (em inglês).
read_from_head bool true Define se os registros serão lidos a partir do topo do arquivo, em vez do final. Consulte a documentação detalhada do fluentd (em inglês).
tag string Varia. O nome do aplicativo. A tag de registro dessa entrada.

Configuração do plug-in de saída fluentd do Google Cloud

  • Localização dos arquivos de configuração:

    • Linux: /etc/google-fluentd/google-fluentd.conf
    • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

      Se você estiver executando um agente do Logging anterior à versão v1-5, o arquivo estará em: C:\GoogleStackdriverLoggingAgent\fluent.conf

  • Descrição: esse arquivo inclui opções de configuração para controlar o comportamento do plug-in de saída do fluentd do Google Cloud.

  • Consulte o repositório de configuração.

Nome da configuração Tipo Padrão Descrição
buffer_chunk_limit string 1M À medida que os registros de log são recebidos, aqueles que não podem ser gravados em componentes de downstream com rapidez suficiente serão enviados por push para uma fila de blocos. Essa configuração define o limite de tamanho de cada bloco. Por padrão, definimos o limite de maneira conservadora para evitar exceder o tamanho de bloco recomendado de 5 MB por solicitação de gravação na Logging API. Um bloco de buffer é liberado se uma das duas condições a seguir for atendida:
1. flush_interval é usado.
2. O tamanho do buffer atinge buffer_chunk_limit.
flush_interval string 5s À medida que os registros de log são recebidos, aqueles que não podem ser gravados em componentes de downstream com rapidez suficiente serão enviados por push para uma fila de blocos. A configuração define o período de espera até a liberação de um bloco de buffer. Ele é liberado se uma das duas condições a seguir for atendida:
1. flush_interval é usado.
2. O tamanho do buffer atinge buffer_chunk_limit.
disable_retry_limit bool false Força um limite para o número de tentativas de liberação de blocos de buffer com falha. Veja as especificações detalhadas em retry_limit, retry_wait e max_retry_wait.
retry_limit int 3 Quando a limpeza de um bloco de buffer falha, o fluentd tentará novamente por padrão. Essa configuração define quantas tentativas são executadas antes de descartar um bloco problemático.
retry_wait int 10s Quando a limpeza de um bloco de buffer falha, o fluentd tentará novamente por padrão. Essa configuração define o intervalo de espera em segundos antes da primeira tentativa. Esse intervalo será dobrado a cada nova tentativa (20 s, 40 s…) até que retry_ limit ou max_retry_wait seja atingido.
max_retry_wait int 300 Quando a limpeza de um bloco de buffer falha, o fluentd tentará novamente por padrão. O intervalo de espera será dobrado a cada nova tentativa (20 s, 40 s…) Essa configuração define o máximo de intervalos de espera em segundos. Se o intervalo atingir esse limite, a duplicação será interrompida.
num_threads int 8 O número de liberações de registro simultâneas que podem ser processadas pelo plug-in de saída.
use_grpc bool true Define se é preciso usar gRPC em vez de REST/JSON para se comunicar com a API Logging. Com o gRPC ativado, o uso de CPU normalmente será menor.
partial_success bool true Define se o sucesso parcial para a ingestão de registros é aceito. Caso o resultado seja true, as entradas de registro inválidas em um conjunto completo serão descartadas e as entradas de registro válidas serão ingeridas na API Logging. Se o resultado for false, o conjunto completo será descartado caso haja entradas de registro inválidas.
enable_monitoring bool true Quando definido como true, o agente do Logging expõe duas métricas: uma de contagem de solicitações, que acompanha o número de entradas de registro a serem enviadas ao Stackdriver Logging, e uma contagem de entradas que controla o número real de entradas de registro ingeridas pelo Stackdriver Logging. Quando o valor for false, essas métricas não serão expostas.
monitoring_type string prometheus O tipo de monitoramento. A única opção hoje é prometheus, mas poderemos oferecer mais alternativas no futuro. Se enable_monitoring for true e monitoring_type for prometheus, o agente do Logging exibirá algumas métricas locais no formato do Prometheus em localhost:24231/metrics. Veja mais detalhes.
autoformat_stackdriver_trace bool true Quando definido como true, o trace será reformatado se o valor do campo de payload estruturado logging.googleapis.com/trace corresponder ao formato traceId do ResourceTrace. Veja mais detalhes sobre formatação automática em Campos especiais em payloads estruturados.

Como processar payloads

A maioria dos registros compatíveis na configuração padrão do agente do Logging é de arquivos de registro e é ingerida como payloads não estruturados (de texto) nas entradas.

A única exceção é que o plug-in de entrada in_forward, que também está ativado por padrão, aceita apenas registros estruturados e os ingere como payloads estruturados (JSON) nas entradas de registro. Consulte Como fazer streaming de registros estruturados (JSON) pelo in_forward para mais informações sobre esse plug-in.

É possível personalizar a configuração dos agentes para aceitar a ingestão de registros estruturados de outros recursos. Consulte Como fazer streaming de registros de log estruturados (JSON) para o Stackdriver Logging para mais detalhes.

O payload dos registros de log transmitidos por um agente do Logging configurado de maneira personalizada pode ser uma única mensagem de texto não estruturada (textPayload) ou uma mensagem JSON estruturada (jsonPayload).

Campos especiais em payloads estruturados

Quando o agente do Logging recebe um registro de log estruturado, ele trata os campos a seguir de maneira especial, permitindo que você defina campos específicos no objeto LogEntry que é gravado na API Logging.

Todos os campos da tabela abaixo são removidos do payload, se inclusos.

Campo do registro JSON Campo LogEntry Função do agente do Logging
severity severity O agente do Logging tenta corresponder diversas strings de gravidade comuns. Isso inclui a lista de strings do LogSeverity reconhecidas pela API Logging.
message textPayload (ou parte de jsonPayload) Define que, se houver apenas um campo de message restante após a remoção dos campos de finalidade especial, essa message será salva como textPayload. Se a entrada de registro contiver um rastreamento de pilha de exceção, o campo de registro JSON da message precisará ser configurado para que a entrada possa ser analisada e salva no Stackdriver Error Reporting.
log textPayload (ou parte de jsonPayload) Aplica-se apenas ao Cloud Functions e ao Kubernetes Engine: se, após a remoção dos campos de finalidade especial, houver apenas um campo log restante, esse log será salvo como textPayload.
httpRequest httpRequest Retirado do jsonPayload e atribuído ao campo HttpRequest do LogEntry.
campos relacionados ao tempo timestamp Para detalhes, consulte Campos relacionados ao tempo.
logging.googleapis.com/trace trace logging.googleapis.com/trace é retirado do jsonPayload e atribuído ao campo trace do LogEntry. Por exemplo, suponha que o valor de logging.googleapis.com/trace seja [V]. [V] precisa ser formatado como projects/[PROJECT-ID]/traces/[TRACE-ID] para que possa ser usado pelo Visualizador de registros e pelo Visualizador de trace a fim de agrupar as entradas de registro e exibi-las alinhadas aos traces. Se autoformat_stackdriver_trace for true e [V] corresponder ao formato traceId do ResourceTrace, o campo LogEntry trace terá o valor projects/[PROJECT-ID]/traces/[V].
logging.googleapis.com/spanId spanId Esse campo é retirado do jsonPayload e atribuído ao campo spanId do LogEntry.
logging.googleapis.com/operation operation Esse valor é retirado do jsonPayload e atribuído a LogEntryOperation. Esse campo também é usado pelo Visualizador de registros para agrupar entradas de registro relacionadas.
logging.googleapis.com/sourceLocation sourceLocation Esse valor é retirado do jsonPayload e atribuído a LogEntrySourceLocation.

Os campos de registro estruturados restantes se tornam parte do jsonPayload. Se houver apenas um campo de message restante, o valor desse campo será armazenado como textPayload na entrada de registro.

Campos relacionados ao tempo

O agente do Logging pode receber e processar campos relacionados ao tempo em vários formatos JSON. Se uma das seguintes representações de carimbo de data/hora do JSON estiver presente em um registro estruturado, o agente do Logging removerá os campos de jsonPayload e os recolherá em uma única representação no campo timestamp no objeto LogEntry:

  • jsonPayload contém um campo timestamp que inclui os campos seconds e nanos. Eles representam um número de segundos do período UTC com sinalização e um número não negativo de frações de segundo:

    {
      "timestamp": {
        "seconds": CURRENT_SECONDS,
        "nanos": CURRENT_NANOS
      }
    }
    
  • jsonPayload contém os campos timestampSeconds e timestampNanos:

    {
       "timestampSeconds": CURRENT_SECONDS,
       "timestampNanos": CURRENT_NANOS
    }
    
  • jsonPayload contém o campo time com as mesmas informações de segundos e nanossegundos escritas como uma string: "[-]sssssssss.nnnnnnnnn".

    {
        "time": CURRENT_TIME
    }
    

Depois que o agente do Logging detectar uma representação de carimbo de data/hora, nenhum outro detalhamento relacionado ao carimbo ocorrerá, mesmo se mais representações de formatação aceitável estiverem presentes no registro estruturado.

Como personalizar a configuração do agente

Além da lista de registros padrão que o agente do Logging transmite por padrão, você pode personalizar esse agente para enviar outros registros para o Logging ou ajustar as configurações dele adicionando configurações de entrada.

As definições de configuração nestas seções aplicam-se apenas ao plug-in de saída fluent-plugin-google-cloud e especificam como os registros são transformados e ingeridos no Stackdriver Logging.

  • Locais do arquivo de configuração principal:

    • Linux: /etc/google-fluentd/google-fluentd.conf
    • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

      Se você estiver executando um agente do Logging anterior à versão v1-5, o arquivo estará em: C:\GoogleStackdriverLoggingAgent\fluent.conf

  • Descrição: esse arquivo inclui opções de configuração para controlar o comportamento do plug-in de saída fluent-plugin-google-cloud.

  • Consulte o repositório de configuração.

Como fazer streaming de registros a partir de entradas adicionais

É possível personalizar o agente do Logging para enviar outros registros ao Logging por meio da adição de configurações de entrada.

Como fazer streaming de registros não estruturados (texto) por meio de arquivos de registro

  1. Crie um arquivo de registros com o seguinte comando:

    $ touch /tmp/test-unstructured-log.log
    
  2. Crie um novo arquivo de configuração no diretório de configuração de terceiros (/etc/google-fluentd/config.d no Linux ou C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d no Windows) com a configuração a seguir. Se preferir, adicione a configuração a qualquer arquivo atual no arquivo principal:

    $ sudo vim /etc/google-fluentd/config.d/test-unstructured-log.conf
    $ cat /etc/google-fluentd/config.d/test-unstructured-log.conf
    <source>
        @type tail
        # Format 'none' indicates the log is unstructured (text).
        format none
        # The path of the log file.
        path /tmp/test-unstructured-log.log
        # The path of the position file that records where in the log file
        # we have processed already. This is useful when the agent
        # restarts.
        pos_file /var/lib/google-fluentd/pos/test-unstructured-log.pos
        read_from_head true
        # The log tag for this log input.
        tag unstructured-log
    </source>
    
  3. Reinicie o agente para aplicar as mudanças de configuração:

    $ sudo service google-fluentd restart
    
  4. Gere um registro de log no arquivo de registros:

    $ echo 'This is a log from the log file at test-unstructured-log.log' >> /tmp/test-unstructured-log.log
    
  5. Consulte o Visualizador de registros para ver a entrada ingerida:

      {
       insertId:  "eps2n7g1hq99qp"
       labels: {
        compute.googleapis.com/resource_name:  "add-unstructured-log-resource"
       }
       logName:  "projects/my-sample-project-12345/logs/unstructured-log"
       receiveTimestamp:  "2018-03-21T01:47:11.475065313Z"
       resource: {
        labels: {
         instance_id:  "3914079432219560274"
         project_id:  "my-sample-project-12345"
         zone:  "us-central1-c"
        }
        type:  "gce_instance"
       }
       textPayload:  "This is a log from the log file at test-unstructured-log.log"
       timestamp:  "2018-03-21T01:47:05.051902169Z"
      }
    

Como fazer streaming de registros estruturados (JSON) por meio de arquivos de registro

Você pode ativar a geração de registros estruturados para determinadas entradas ao instalar o agente do Logging. Para mais informações, consulte Como gerar registros estruturados.

Você também pode personalizar o agente do Logging para adicionar uma entrada de registro JSON. Essa configuração faz com que o agente espere que cada registro de log seja um objeto JSON:

  1. Crie um arquivo de registros:

    $ touch /tmp/test-structured-log.log
    
  2. Crie um novo arquivo de configuração no diretório de configuração de terceiros (/etc/google-fluentd/config.d no Linux ou C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d no Windows) com a configuração a seguir. Se preferir, adicione a configuração a qualquer arquivo atual no arquivo principal:

    $ sudo vim /etc/google-fluentd/config.d/test-structured-log.conf
    $ cat /etc/google-fluentd/config.d/test-structured-log.conf
    <source>
        @type tail
        # Format 'JSON' indicates the log is structured (JSON).
        format json
        # The path of the log file.
        path /tmp/test-structured-log.log
        # The path of the position file that records where in the log file
        # we have processed already. This is useful when the agent
        # restarts.
        pos_file /var/lib/google-fluentd/pos/test-structured-log.pos
        read_from_head true
        # The log tag for this log input.
        tag structured-log
    </source>
    
  3. Reinicie o agente para aplicar as mudanças de configuração:

    $ sudo service google-fluentd restart
    
  4. Gere um registro de log no arquivo de registros:

    $ echo '{"code": "structured-log-code", "message": "This is a log from the log file at test-structured-log.log"}' >> /tmp/test-structured-log.log
    
  5. Consulte o Visualizador de registros para ver a entrada ingerida:

    {
     insertId:  "1m9mtk4g3mwilhp"
     jsonPayload: {
      code:  "structured-log-code"
      message:  "This is a log from the log file at test-structured-log.log"
     }
     labels: {
      compute.googleapis.com/resource_name:  "add-structured-log-resource"
     }
     logName:  "projects/my-sample-project-12345/logs/structured-log"
     receiveTimestamp:  "2018-03-21T01:53:41.118200931Z"
     resource: {
      labels: {
       instance_id:  "5351724540900470204"
       project_id:  "my-sample-project-12345"
       zone:  "us-central1-c"
      }
      type:  "gce_instance"
     }
     timestamp:  "2018-03-21T01:53:39.071920609Z"
    }
    

Para ver outras opções de personalização do formato de entrada de registro em aplicativos comuns de terceiros, consulte Formatos de registro comuns e como analisá-los.

Como fazer streaming de registros estruturados (JSON) por meio do plug-in in_forward

Além disso, você pode enviar registros por meio do plug-in fluentd in_forward. fluentd-cat é uma ferramenta integrada que ajuda a enviar registros com facilidade para o plug-in in_forward. A documentação do fluentd contém mais detalhes sobre essa ferramenta.

Para enviar registros por meio do plug-in in_forward do fluentd, consulte as seguintes instruções:

  1. Execute o seguinte comando na VM com o agente do Logging instalado:

     $ echo '{"code": "send-log-via-fluent-cat", "message": "This is a log from in_forward plugin."}' | /opt/google-fluentd/embedded/bin/fluent-cat log-via-in-forward-plugin
    
  2. Consulte o visualizador de registros para ver a entrada ingerida:

      {
       insertId:  "1kvvmhsg1ib4689"
       jsonPayload: {
        code:  "send-log-via-fluent-cat"
        message:  "This is a log from in_forward plugin."
       }
       labels: {
        compute.googleapis.com/resource_name:  "add-structured-log-resource"
       }
       logName:  "projects/my-sample-project-12345/logs/log-via-in-forward-plugin"
       receiveTimestamp:  "2018-03-21T02:11:27.981020900Z"
       resource: {
        labels: {
         instance_id:  "5351724540900470204"
         project_id:  "my-sample-project-12345"
         zone:  "us-central1-c"
        }
        type:  "gce_instance"
       }
       timestamp:  "2018-03-21T02:11:22.717692494Z"
      }
    

Como fazer streaming de registros de log estruturados (JSON) a partir do código do aplicativo

É possível ativar conectores em várias linguagens para enviar registros estruturados com base no código do aplicativo. Para mais informações, consulte a documentação do fluentd (em inglês). Esses conectores são criados com base no plug-in in_forward.

Como configurar rótulos de entrada de registro

Com as opções de configuração abaixo, é possível modificar os rótulos do LogEntry e do MonitoredResource ao ingerir os registros no Stackdriver Logging. Todas as entradas de registro estão associadas a recursos monitorados. Para mais informações, consulte a lista de tipos de recursos monitorados do Stackdriver Logging.

Nome da configuração Tipo Padrão Descrição
label_map hash nil label_map (especificado como um objeto JSON) é um conjunto não ordenado de nomes de campo fluentd. Os valores dele são enviados como rótulos, e não como parte do payload estruturado. Cada entrada no mapa é um par {field_name:label_name}. Quando field_name (conforme analisado pelo plug-in de entrada) é encontrado, um rótulo com o label_name correspondente é adicionado à entrada de registro. O valor do campo é usado como o valor do rótulo. O mapa oferece mais flexibilidade para especificar nomes de rótulos, inclusive a capacidade de usar caracteres que não seriam permitidos como parte de nomes de campo do fluentd. Consulte Como configurar rótulos em entradas de registro estruturadas para ver exemplos.
labels hash nil labels (especificado como um objeto JSON) é um conjunto de rótulos personalizados fornecidos no momento da configuração. Ele permite que você injete informações adicionais sobre o ambiente em cada mensagem ou personalize rótulos detectados automaticamente. Cada entrada no mapa é um par {label_name:label_value}.

O plug-in de saída do agente do Logging aceita três maneiras de definir rótulos do LogEntry:

Como configurar rótulos em entradas de registro estruturadas

Suponha que você tenha criado um payload de entrada de registro estruturado como este:

{ "message": "This is a log message", "timestamp": "Aug 10 20:07:00", "env": "production" }

E imagine que você quer converter o campo env do payload acima em um rótulo de metadados environment. Para fazer isso, adicione o seguinte comando à configuração do plug-in de saída no arquivo de configuração principal (/etc/google-fluentd/google-fluentd.conf no Linux ou C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf no Windows):

  # Configure all sources to output to Stackdriver Logging
  <match **>
    type google_cloud
    label_map {
      "env": "environment"
    }
    ...
  </match>

Essa configuração label_map substitui o rótulo env no payload por environment. Portanto, a entrada de registro resultante terá um rótulo environment com o valor production.

Como configurar rótulos estaticamente

Se você não tiver essas informações no payload e quiser apenas adicionar um rótulo de metadados estático denominado environment, insira o seguinte comando na configuração do plug-in de saída no arquivo de configuração principal (/etc/google-fluentd/google-fluentd.conf no Linux ou C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf no Windows): # Configure all sources to output to Stackdriver Logging type google_cloud labels { "environment": "production" } ...

Nesse caso, em vez de usar um mapa para substituir um rótulo por outro, utilizamos uma configuração labels para anexar um rótulo com um valor literal a uma entrada de registro, independentemente de ela já ter um rótulo ou não. Essa abordagem pode ser usada mesmo se você estiver enviando registros não estruturados.

Para saber mais sobre como definir labels, label_map e outras configurações do agente do Logging, consulte Como definir rótulos de entrada de registro.

Como modificar registros

O fluentd fornece plug-ins de filtro integrados que podem ser usados para modificar entradas de registro.

O plug-in de filtro mais usado é o filter_record_transformer. Com ele, você pode realizar as seguintes ações:

  • adicionar novos campos para registrar entradas
  • atualizar campos em entradas de registro
  • excluir campos em entradas de registro

É possível também modificar entradas de registro usando alguns plug-ins de saída. O plug-in de saída fluent-plugin-record-reformer inclui recursos similares ao plug-in de filtro filter_record_transformer, mas também permite que você modifique as tags de registro. Com esse plug-in, esperamos que o uso dos recursos aumente: cada vez que uma tag de registro é atualizada, ela gera uma nova entrada de registro com a nova tag. O campo tag na configuração é obrigatório. Recomendamos que você modifique esse campo para evitar a inserção de um loop morto.

O plug-in de saída fluent-plugin-detect-exceptions verifica um fluxo de registros, não estruturados (texto) ou no formato JSON, para traces de pilha de exceção de várias linhas. Se uma sequência consecutiva de entradas de registro formar um trace de pilha de exceção, as entradas de registro serão encaminhadas como uma única mensagem de registro combinada. Caso contrário, a entrada de registro será encaminhada no formato em que estava.

Definições da configuração avançada (não padrão)

Se você quiser personalizar a configuração do agente do Logging além da configuração padrão, consulte as seções a seguir.

As opções de configuração abaixo permitem ajustar o mecanismo de buffer interno do agente do Logging.

Nome da configuração Tipo Padrão Descrição
buffer_type string buf_memory Os registros que não podem ser gravados na API Logging com rapidez suficiente serão enviados por push para um buffer. O buffer pode estar na memória ou em arquivos reais. Valor recomendado: buf_file. O buf_memory padrão é rápido, mas não é permanente. Existe o risco de perder registros. Se buffer_type for buf_file, é preciso especificar buffer_path.
buffer_path string Especificado pelo usuário O caminho onde os blocos de buffer são armazenados. Este parâmetro é obrigatório se buffer_type for file. Essa configuração precisa ser exclusiva para evitar uma condição de corrida.
buffer_queue_limit int 64 Especifica o limite de comprimento da fila de blocos. Quando a fila do buffer atingir esse número de blocos, o comportamento do buffer é controlado por buffer_queue_full_action. Por padrão, ele lançará exceções.
buffer_queue_full_action string exception Controla o comportamento do buffer quando a fila do buffer está cheia. Valores possíveis:
1. exception: lança BufferQueueLimitError quando a fila está cheia. A maneira como BufferQueueLimitError é tratado depende dos plug-ins de entrada. Por exemplo, o plug-in de entrada in_tail para de ler novas linhas, enquanto o plug-in de entrada in_forward retorna um erro.
2. block: esse modo interrompe o encadeamento do plug-in de entrada até que a condição de buffer cheio seja resolvida. Essa ação é útil para casos de uso em lote. fluentd não recomenda o uso de ações de bloqueio para evitar BufferQueueLimitError. Se você alcança o valor de BufferQueueLimitError com frequência, isso significa que sua capacidade de destino é insuficiente para o tráfego.
3. drop_oldest_chunk: esse modo descarta os blocos mais antigos.

As configurações abaixo permitem especificar manualmente um projeto e determinados campos do objeto MonitoredResource. Esses valores são coletados automaticamente pelo agente do Logging. Não é recomendável especificá-los manualmente.

Nome da configuração Tipo Padrão Descrição
project_id string nil Se especificado, modifica o project_id que identifica o projeto do GCP ou AWS subjacente em que o agente do Logging está sendo executado.
zone string nil Se especificado, modifica a zona.
vm_id string nil Se especificado, modifica o código da VM.
vm_name string nil Se especificado, modifica o nome da VM.

Outras opções de configuração do plug-in de saída

Nome da configuração Tipo Padrão Descrição
detect_json1 bool false Define se o plug-in tentará detectar se o registro de log é uma entrada de registro de texto com conteúdo JSON que precisa ser analisado. Caso essa configuração seja true e uma entrada não estruturada (texto) seja detectada como no formato JSON, o registro será analisado e enviado como um payload estruturado (JSON).
coerce_to_utf8 bool true Define se caracteres não UTF-8 são permitidos nos registros do usuário. Se configurado como true, qualquer caractere não UTF-8 é substituído pela string especificada por non_utf8_replacement_string. Se definido como false, qualquer caractere não UTF-8 acionará um erro no plug-in.
require_valid_tags bool false Define se as entradas de registro com tags inválidas são rejeitadas. Se essa opção for definida como false, as tags serão validadas por meio da conversão das tags não formatadas como string para string e por meio da remoção de qualquer caractere não UTF-8 ou outros caracteres inválidos.
non_utf8_replacement_string string ""(espaço) Se coerce_to_utf8 for definido como true, qualquer caractere não UTF-8 será substituído pela string especificada aqui.

1Quando o registro tem apenas um campo de mensagem de texto, o plug-in de saída às vezes pode detectar quando essa mensagem é JSON e transformar o payload em JSON. Esse recurso está ativado por padrão em instâncias de VM executadas no ambiente flexível do App Engine e no Google Kubernetes Engine.

Como aplicar a configuração de agente personalizada

A personalização do agente do Logging permite que você adicione seus próprios arquivos de configuração do fluentd:

Instância do Linux

  1. Copie os arquivos de configuração para este diretório:

    /etc/google-fluentd/config.d/
    
  2. Reinicie o agente executando o seguinte comando:

    sudo service google-fluentd force-reload
    

O script de instalação do agente do Logging preencherá esse diretório com os arquivos de configuração “pega-tudo” padrão. Para mais informações, consulte Como conseguir o código-fonte do agente do Logging.

Instância do Windows

  1. Copie seus arquivos de configuração para o subdiretório config.d do diretório de instalação do agente. Se você tiver aceitado o diretório de instalação padrão, o caminho dele será:

    C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\
    
  2. Execute os seguintes comandos em um shell de linha de comando para reiniciar o agente:

    net stop  StackdriverLogging
    net start StackdriverLogging
    

Para mais informações sobre os arquivos de configuração do fluentd, consulte a documentação sobre a sintaxe do arquivo de configuração do fluentd (em inglês).

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Stackdriver Logging
Precisa de ajuda? Acesse nossa página de suporte.