Como configurar o agente

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

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

  • você tem interesse em conhecer os detalhes técnicos da configuração do agente do Cloud Logging;

  • você quer alterar a configuração do agente do Cloud Logging.

Configuração padrão

O agente do Logging google-fluentd é uma versão modificada do coletor de dados de registro fluentd. O agente do Logging vem com uma configuração padrão; nos casos mais comuns, nenhuma configuração adicional é obrigatória.

Na configuração padrão, o agente do Logging faz o streaming de registros, como incluído na lista de registros padrão, para o Cloud Logging. É possível configurar o agente para transmitir registros adicionais. Para mais detalhes, acesse Como personalizar a configuração do agente do Logging nesta página.

Como funciona o agente do Logging

O agente do Logging usa plug-ins de entrada fluentd para recuperar e receber registros de eventos de fontes externas, como arquivos em disco, ou para analisar registros de entrada. Os plug-ins de entrada são empacotados com o agente ou podem ser instalados separadamente como gems do Ruby. Revise a lista de plug-ins do pacote (em inglês).

O agente lê registros de registros armazenados em arquivos de registro na instância de VM pelo in_tail plug-in integradofluentd. Cada registro é convertido em uma estrutura de entrada de registro (em inglês) para o Cloud Logging. O conteúdo de cada registro é gravado principalmente no payload das entradas de registro, mas elas também contêm elementos padrão, como carimbo de data/hora e gravidade. O agente do Logging exige que todos os registros tenham tags em formato de string. Todas as consultas 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, esse 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 Cloud 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.

Local do arquivo de configuração raiz

  • Linux: /etc/google-fluentd/google-fluentd.conf

    Esse arquivo de configuração raiz importa todos os arquivos de configuração da pasta /etc/google-fluentd/config.d.

  • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

    Se você estiver executando um agente do Logging antes do v1-5, o local será: C:\GoogleStackdriverLoggingAgent\fluent.conf

Configuração do Syslog

  • Localização dos arquivos de configuração: /etc/google-fluentd/config.d/syslog.conf

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

  • Revise o repositório de configuração (em inglês).

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 registra a última posição que leu no arquivo. Revise a documentação detalhada de fluentd (em inglês).
read_from_head bool true Define se os registros serão lidos do topo do arquivo, em vez do final. Revise a documentação detalhada de fluentd (em inglês).
tag string syslog A tag de registro dessa entrada.

in_forward configuração do plug-in de entrada

  • Localização dos arquivos de configuração: /etc/google-fluentd/config.d/forward.conf

  • Descrição: este arquivo inclui a configuração para configurar o plug-in de entrada in_forward fluentd. O plug-in de entrada in_forward permite que você passe registros por um soquete TCP.

  • Revise a documentação detalhada de fluentd (em inglês) para este plug-in e o repositório de configuração (em inglês).

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: /etc/google-fluentd/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 Apache).

  • Revise o repositório de configuração (em inglês).

Nome da configuração Tipo Padrão Descrição
format string Varia por aplicativo O formato do registro. Revise a documentação detalhada de 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. Revise a documentação detalhada de fluentd (em inglês).
pos_file string Varia por aplicativo O caminho do arquivo de posição para esta entrada de registro. fluentd registra a última posição que leu no arquivo. Revise a documentação detalhada de fluentd (em inglês).
read_from_head bool true Define se os registros serão lidos do topo do arquivo, em vez do final. Revise a documentação detalhada de fluentd (em inglês).
tag string Varia. O nome do aplicativo. A tag de registro dessa entrada.

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

  • 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 antes do v1-5, o local será: C:\GoogleStackdriverLoggingAgent\fluent.conf

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

  • Acesse o repositório de configuração (em inglês).

Nome da configuração Tipo Padrão Descrição
buffer_chunk_limit string 512KB À medida que os registros são recebidos, os que não podem ser gravados em componentes downstream com rapidez suficiente são colocados em uma fila de blocos. Essa configuração define o limite de tamanho de cada bloco. Por padrão, definimos o limite do bloco de forma conservadora para evitar exceder o tamanho recomendado de bloco de 5 MB por solicitação de gravação na Logging API. As entradas de registro na solicitação de API podem ser de cinco a oito vezes maiores do que o tamanho do registro original com todos os metadados extras anexados. Ele é liberado se uma das duas condições a seguir for atendida:
1. flush_interval entra em ação.
2. O tamanho do buffer atinge buffer_chunk_limit.
flush_interval string 5s À medida que os registros são recebidos, os que não podem ser gravados em componentes downstream com rapidez suficiente são colocados em 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 entra em ação.
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. Revise as especificações detalhadas em retry_limit, retry_wait e max_retry_wait.
retry_limit int 3 Quando um bloco de buffer não é liberado, fluentd por padrão tentará novamente mais tarde. Essa configuração define quantas tentativas são executadas antes de descartar um bloco problemático.
retry_wait int 10s Quando um bloco de buffer não é liberado, fluentd por padrão tentará novamente mais tarde. Essa configuração define o intervalo de espera em segundos antes da primeira tentativa. O intervalo de espera dobra em cada tentativa a seguir (20s, 40s…) até que retry_ limit ou max_retry_wait seja alcançado.
max_retry_wait int 300 Quando um bloco de buffer não é liberado, fluentd por padrão tentará novamente mais tarde. O intervalo de espera dobra em cada nova tentativa a seguir (20s, 40s…) 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. Se true, entradas de registro inválidas em um conjunto completo são descartadas e entradas de registro válidas são processadas com sucesso na API Logging. Se false, o conjunto completo será descartado se contiver 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 rastreia o número de entradas de registro solicitadas para serem enviadas ao Cloud Logging, e outra de contagem de entradas que rastreia o número real de entradas de registro ingeridas pelo Cloud Logging de maneira bem-sucedida. Quando definido como false, essas métricas não são expostas.
monitoring_type string prometheus O tipo de monitoramento. A única opção hoje é prometheus, mas poderemos oferecer opções adicionais no futuro. Se enable_monitoring for true e monitoring_type for prometheus, o agente do Logging expõe algumas métricas locais no formato Prometheus em localhost:24231/metrics. Veja os detalhes.
autoformat_stackdriver_trace bool true Quando definido como true, o trace será reformatado se o valor do campo logging.googleapis.com/trace de payload estruturado corresponder ao formato traceId ResourceTrace. Os detalhes da autoformatação podem ser vistos em Campos especiais em payloads estruturados nesta página.

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 é ativado por padrão, aceita apenas registros estruturados e os processa como payloads estruturados (JSON) nas entradas de registro. Para mais detalhes, leia Como fazer streaming de registros estruturados (JSON) por meio do plug-in in_forward nesta página.

Quando a linha de registro é um objeto JSON serializado e a opção detect_json está ativada, o plug-in de saída transforma a entrada de registro em um payload estruturado (JSON). Essa opção é ativada por padrão em instâncias de VM em execução no ambiente flexível do App Engine e no Google Kubernetes Engine. Essa opção não é ativada por padrão em instâncias de VM em execução no ambiente padrão do App Engine. Qualquer JSON analisado com a opção detect_json ativada sempre é ingerido como jsonPayload.

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

O payload dos registros transferidos 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 a seguir serão removidos do payload, caso estejam sendo exibidos.

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) message é salvo como textPayload se for o único campo restante depois que o agente do Logging remover os outros campos de finalidade especial e detect_json não tiver sido ativado. Caso contrário, message permanecerá em jsonPayload. Se a entrada de registro tiver um rastreamento de pilha de exceção, ele precisa ser definido neste campo de registro JSON message para que o rastreamento de pilha de exceção possa ser analisado e salvo no Error Reporting.
log (somente Google Kubernetes Engine legado) textPayload Aplica-se somente ao Google Kubernetes Engine legado: se, após a remoção de campos de finalidade especial, apenas um campo log permanecer, então log será salvo como textPayload.
httpRequest httpRequest Esse é um registro estruturado no formato do campo LogEntry HttpRequest.
campos relacionados ao tempo timestamp Para mais detalhes, leia Campos relacionados ao tempo nesta página.
logging.googleapis.com/insertId insertId
logging.googleapis.com/labels labels O valor desse campo deve ser um registro estruturado.
logging.googleapis.com/operation operation O valor desse campo também é usado pelo Visualizador de registros para agrupar entradas de registro relacionadas.
logging.googleapis.com/sourceLocation sourceLocation Este é um registro estruturado no formato do campo LogEntry LogEntrySourceLocation.
logging.googleapis.com/spanId spanId
logging.googleapis.com/trace trace O valor desse campo deve ser formatado como projects/[PROJECT-ID]/traces/[TRACE-ID]. Portanto, ele pode ser usado pelo Visualizador de registros e pelo Visualizador de trace para agrupar entradas de registro e exibi-las alinhadas aos traces. Se autoformat_stackdriver_trace é true e [V] corresponde ao formato de traceId do ResourceTrace, o campo trace do LogEntry tem o valor projects/[PROJECT-ID]/traces/[V].
logging.googleapis.com/trace_sampled traceSampled O valor desse campo deve ser formatado como true ou false.

Todos os campos de registros estruturados restantes permanecem como parte de jsonPayload. Na ausência de detect_json, se houver apenas um campo 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 recolhe em uma única representação no campo timestamp no objeto LogEntry:

  • jsonPayload contém um campo timestamp que inclui os campos seconds e nanos, representando um número atribuído de segundos entre a época UTC e um número não negativo de segundos fracionários:

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

    {
       "timestampSeconds": CURRENT_SECONDS,
       "timestampNanos": CURRENT_NANOS
    }
    
  • jsonPayload contém um campo time que contém as mesmas informações de segundos, escritas como uma string, conforme definido por RFC 3339:

    {
        "time": CURRENT_TIME_RFC3339
    }
    

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, é possível 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 nessas seções aplicam-se somente ao plug-in de saída fluent-plugin-google-cloud e especificam como os registros são transformados e ingeridos no Cloud 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 antes do v1-5, o local será: C:\GoogleStackdriverLoggingAgent\fluent.conf

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

  • Revise o repositório de configuração (em inglês).

Como fazer streaming de registros a partir de entradas adicionais

Você pode 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. No prompt de comando do Linux, crie um arquivo de registros:

    touch /tmp/test-unstructured-log.log
    
  2. Crie um novo arquivo de configuração rotulado test-unstructured-log.conf no diretório de configuração terceirizado /etc/google-fluentd/config.d:

    sudo tee /etc/google-fluentd/config.d/test-unstructured-log.conf <<EOF
    <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>
    EOF
    

    Uma alternativa à criação de um novo arquivo é adicionar as informações de configuração a um arquivo de configuração atual.

  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

É possível configurar o agente do Logging para exigir que cada entrada de registro para determinadas entradas de registro sejam estruturadas. Também é possível personalizar o agente do Logging para ingerir o conteúdo formatado em JSON de um arquivo de registros. Quando o agente estiver configurado para ingerir conteúdo JSON, a entrada precisa ser formatada para que cada objeto JSON esteja em uma nova linha:

    {"name" : "zeeshan", "age" : 28}
    {"name" : "reeba", "age" : 15}

Para configurar o agente do Logging para ingerir o conteúdo formatado em JSON, faça o seguinte:

  1. No prompt de comando do Linux, crie um arquivo de registros:

    touch /tmp/test-structured-log.log
    
  2. Crie um novo arquivo de configuração rotulado test-structured-log.conf no diretório de configuração terceirizado /etc/google-fluentd/config.d:

    sudo tee /etc/google-fluentd/config.d/test-structured-log.conf <<EOF
    <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>
     EOF
    

    Uma alternativa à criação de um novo arquivo é adicionar as informações de configuração a um arquivo de configuração atual.

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

    No visualizador de registros, filtre por tipo de recurso e um logName de structured-log.

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.

Registros estruturados de streaming (JSON) pelo plug-in in_forward

Além disso, é possível enviar registros pelo plug-in fluentd in_forward. fluentd-cat é uma ferramenta integrada que facilita o envio de registros para o plug-in in_forward. A documentação fluentd contém mais detalhes sobre essa ferramenta.

Para enviar registros por meio do plug-in fluentd in_forward, leia 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 os conectores em várias linguagens para enviar registros estruturados a partir do código do aplicativo. Para mais informações, consulte a documentação fluentd (em inglês). Esses conectores são criados com base no plug-in in_forward.

Como configurar rótulos de entrada de registro

As opções de configuração a seguir permitem modificar os rótulos LogEntry e MonitoredResource ao ingerir registros para o Cloud Logging. Todas as entradas de registro são associadas a recursos monitorados. Para mais informações, analise a lista de Tipos de recursos monitorados do Cloud 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 com valores enviados como rótulos em vez de como parte do payload estruturado. Cada entrada no mapa é um par {field_name: label_name}. Quando field_name (como analisado pelo plug-in de entrada), um rótulo com o label_name é adicionado à entrada de registro. O valor do campo é usado como o valor do rótulo. O mapa oferece a flexibilidade extra na especificação de nomes de rótulos, incluindo a capacidade de usar caracteres que não seriam permitidos como parte de nomes de campo fluentd. Por exemplo, acesse Como configurar rótulos em entradas de registro estruturadas.
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 suponha que você queira converter o campo de payload env em um rótulo de metadados environment. Para fazer isso, adicione o seguinte à 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 Cloud Logging
  <match **>
    type google_cloud
    label_map {
      "env": "environment"
    }
    ...
  </match>

A configuração label_map substitui o rótulo env no payload com environment. Portanto, a entrada de registro resultante tem 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 simplesmente adicionar um rótulo de metadados estático chamado environment, adicione o seguinte à 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 Cloud Logging
  <match **>
    type google_cloud
    labels {
      "environment": "production"
    }
    ...
  </match>

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

Para saber mais sobre como configurar labels, label_map e outras configurações de agente do Logging, acesse Como configurar os rótulos de entrada de registro nesta página.

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 é filter_record_transformer. Com ele, é possível 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 fornece funcionalidade semelhante à 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. Observe que o campo tag na configuração é obrigatório; também recomendamos que você modifique esse campo para evitar inserir um loop morto.

O plug-in de saída fluent-plugin-detect-exceptions verifica um registro de registros, não estruturado (texto) ou de 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, continue lendo esta página.

As opções de configuração a seguir permitem que você ajuste o mecanismo de armazenamento em 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 velocidade suficiente são colocados em um buffer. O buffer pode estar na memória ou em arquivos reais. Valor recomendado: buf_file. O padrão buf_memory é rápido, mas não persistente. Existe o risco de perder registros. Se buffer_type for buf_file, buffer_path precisará ser especificado também.
buffer_path string Especificado pelo usuário O caminho onde os blocos de buffer são armazenados. Este parâmetro será 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 de buffer alcança muitos blocos, o comportamento do buffer é controlado por buffer_queue_full_action. Por padrão, isso gera 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: lance BufferQueueLimitError quando a fila estiver cheia. 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: este modo interrompe o thread 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ção de bloqueio para evitar BufferQueueLimitError. Se você clicar em BufferQueueLimitError com frequência, isso significa que sua capacidade de destino é insuficiente para seu tráfego.
3. drop_oldest_chunk: esse modo descarta os blocos mais antigos.

As opções de configuração a seguir permitem que você especifique 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, isso substitui a project_id identificando o projeto do GCP ou AWS subjacente em que o agente do Logging está em execução.
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. Se essa opção for true, e uma entrada de registro não estruturada (texto) for detectada no formato JSON, ela será analisada e enviada 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 definido como true, qualquer caractere não UTF-8 seria substituído pela sequência especificada por non_utf8_replacement_string. Se definido como false, qualquer caractere não UTF-8 acionaria o plug-in para gerar um erro.
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 de qualquer tag que não seja string para uma string e por meio da limpeza de caracteres que não sejam 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.

1Esse recurso é ativado por padrão em instâncias de VM em execução 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 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 no 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 arquivos de configuração fluentd, consulte a documentação da sintaxe do arquivo de configuração da fluentd.