Configurar o agente do Logging

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.

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

Observação: a configuração syslog padrão a seguir, como parte do pacote google-fluentd-catch-all-config, é exclusiva para sistemas operacionais Linux.

• 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

Observação: a configuração do plug-in in_forward padrão a seguir, como parte do pacote google-fluentd-catch-all-config, é exclusiva para sistemas operacionais Linux.

• 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

Observação: a configuração padrão de registro de aplicativos terceirizados a seguir, como parte do pacote google-fluentd-catch-all-config, é exclusiva para sistemas operacionais Linux.

• 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^1	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.

¹ Se você estiver usando a estrofe <parse>, especifique o formato do registro usando @type.

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.
grpc_compression_algorithm	enum	none	Se estiver usando gRPC, define qual esquema de compactação usar. Pode ser none ou gzip.
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 exporta telemetria interna. Consulte Telemetria de plug-ins de saída para ver mais detalhes.
monitoring_type	string	opencensus	O tipo de monitoramento. As opções aceitas são opencensus e prometheus. Consulte Telemetria de plug-ins de saída para ver mais 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.

Configuração de monitoramento

Telemetria de plug-in de saída

A opção enable_monitoring controla se o plug-in de saída fluentd do Google Cloud coleta a telemetria interna. Quando definido como true, o agente do Logging acompanha o número de entradas de registro solicitadas para o Cloud Logging e o número real de entradas de registro processadas pelo Cloud Logging. Quando definido como false, nenhuma métrica é coletada pelo plug-in de saída.

A opção monitoring_type controla como essa telemetria é exposta pelo agente. Veja a seguir a lista de métricas.

Quando definido como prometheus, o agente do Logging expõe métricas no formato do Prometheus no endpoint do Prometheus (localhost:24231/metrics por padrão. Consulte a configuração do plug-in Prometheus e o prometheus_monitor (em inglês). para mais detalhes). Nas VMs do Compute Engine, para que essas métricas sejam gravadas na API Monitoring, o agente do Monitoring também precisa ser instalado e executado.

Quando definido como opencensus (padrão desde a v1.6.25), o agente do Logging grava diretamente as próprias métricas de integridade na API Monitoring. Isso exige que o papel roles/monitoring.metricWriter seja concedido à conta de serviço padrão do Compute Engine, mesmo que o agente do Monitoring não esteja instalado.

As métricas a seguir são gravadas na API Monitoring pelo agente do Monitoring e pelo agente do Logging no modo opencensus:

• agent.googleapis.com/agent/uptime com um rótulo version: tempo de atividade do agente do Logging.
• agent.googleapis.com/agent/log_entry_count com um rótulo response_code: contagem de entradas de registro gravadas pelo agente do Logging.
• agent.googleapis.com/agent/log_entry_retry_count com um rótulo response_code: contagem de entradas de registro gravadas pelo agente do Logging.
• agent.googleapis.com/agent/request_count com um rótulo response_code: contagem de solicitações da API do agente do Logging.

Essas métricas são descritas em mais detalhes na página Métricas do agente .

Além disso, as seguintes métricas do Prometheus são expostas pelo plug-in de saída no modo prometheus:

• uptime com um rótulo version: tempo de atividade do agente do Logging.
• stackdriver_successful_requests_count com os rótulos grpc e code: o número de solicitações bem-sucedidas para a API Logging.
• stackdriver_failed_requests_count com os rótulos grpc e code: o número de solicitações com falha para a API Logging, divididas pelo código do erro.
• stackdriver_ingested_entries_count com os rótulos grpc e code: o número de entradas de registro ingeridas pela API Logging.
• stackdriver_dropped_entries_count com os rótulos grpc e code: o número de entradas de registro rejeitadas pela API Logging.
• stackdriver_retried_entries_count com os rótulos grpc e code: o número de entradas de registro que não foram processadas pelo plug-in de saída fluentd do Google Cloud devido a um erro transitório e foram repetidas.

Configuração do plug-in prometheus e prometheus_monitor

Observação: a configuração de monitoramento padrão a seguir é exclusiva dos sistemas operacionais Linux.

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

• Descrição: este arquivo inclui opções de configuração para controlar o comportamento dos plug-ins prometheus e prometheus_monitor. O plug-in prometheus_monitor monitora a infraestrutura principal do Fluentd. O plug-in prometheus expõe as métricas, incluindo as do plug-in prometheus_monitor e do plug-in google_cloud, por meio de uma porta local no formato do Prometheus. Veja mais detalhes em https://docs.fluentd.org/deployment/monitoring-prometheus.

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

Para monitorar o Fluentd, o servidor de métricas HTTP integrado do Prometheus é ativado por padrão. É possível remover a seguinte seção da configuração para interromper a inicialização desse endpoint:

# Prometheus monitoring.
<source>
  @type prometheus
  port 24231
</source>
<source>
  @type prometheus_monitor
</source>

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 move qualquer chave que corresponda à tabela a seguir para o campo correspondente no objeto LogEntry. Caso contrário, a chave se tornará parte do campo LogEntry.jsonPayload. Esse comportamento permite que você defina campos específicos no objeto LogEntry, que é o que está gravado na API Logging. Por exemplo, se o registro de log estruturado contiver uma chave de severity, o agente do Logging vai preencher o campo LogEntry.severity.

Campo do registro JSON	campo LogEntry	Função do agente do Cloud Logging	Valor de exemplo
severity	severity	O agente do Logging tenta corresponder diversas strings de gravidade comum, que incluem a lista de strings LogSeverity reconhecida pela API Logging.	"severity":"ERROR"
message	textPayload (ou parte de jsonPayload)	A mensagem que aparece na linha de entrada do registro no Explorador de registros.	"message":"There was an error in the application." Observação: 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. detect_json não é aplicável a ambientes de geração de registros gerenciados, como o Google Kubernetes Engine. Se a entrada de registro tiver um rastreamento de pilha de exceção, o rastreamento 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 o campo será salvo como textPayload.
httpRequest	httpRequest	Um registro estruturado no formato do campo LogEntry HttpRequest.	"httpRequest":{"requestMethod":"GET"}
campos relacionados ao tempo	timestamp	Para mais informações, consulte Campos relacionados ao tempo.	"time":"2020-10-12T07:20:50.52Z"
logging.googleapis.com/insertId	insertId	Para mais informações, consulte insertId na página LogEntry.	"logging.googleapis.com/insertId":"42"
logging.googleapis.com/labels	labels	O valor desse campo precisa ser um registro estruturado. Para mais informações, consulte labels na página LogEntry.	"logging.googleapis.com/labels": {"user_label_1":"value_1","user_label_2":"value_2"}
logging.googleapis.com/operation	operation	O valor desse campo também é usado pelo Explorador de registros para agrupar entradas de registro relacionadas. Para mais informações, consulte operation na página LogEntry.	"logging.googleapis.com/operation": {"id":"get_data","producer":"github.com/MyProject/MyApplication", "first":"true"}
logging.googleapis.com/sourceLocation	sourceLocation	Informações do local do código-fonte associadas à entrada do registro, se houver. Para mais informações, consulte LogEntrySourceLocation na página LogEntry.	"logging.googleapis.com/sourceLocation": {"file":"get_data.py","line":"142","function":"getData"}
logging.googleapis.com/spanId	spanId	O ID do período dentro do trace associado à entrada de registro. Para mais informações, consulte spanId na página LogEntry.	"logging.googleapis.com/spanId":"000000000000004a"
logging.googleapis.com/trace	trace	Nome do recurso do trace associado à entrada de registro, se houver. Para mais informações, consulte trace na página LogEntry.	"logging.googleapis.com/trace":"projects/my-projectid/traces/0679686673a" Observação: se não for gravando em stdout ou stderr, o valor deste campo deverá ser formatado como projects/[PROJECT-ID]/traces/[TRACE-ID] para que possa ser usado pelo Explorador de registros e pelo Visualizador de Trace para agrupar entradas de registro e exibi-las alinhadas aos traces. Se autoformat_stackdriver_trace for verdadeiro e [V] corresponder ao formato 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 precisa ser true ou false. Para mais informações, consulte traceSampled na página LogEntry.	"logging.googleapis.com/trace_sampled": false

Campos relacionados ao tempo

Em geral, as informações de uma entrada de registro relacionadas ao tempo são armazenadas no campo timestamp do objeto LogEntry:

{
insertId: "1ad8d08f-6529-47ea-832e-467f869a2da4"
...
resource: {2}
timestamp: "2023-10-30T16:33:15.505196Z"
}

Quando a origem de uma entrada de registro são dados estruturados, o agente do Logging usa as seguintes regras para pesquisar informações relacionadas ao tempo nos campos da entrada jsonPayload:

1. Pesquise um campo timestamp que seja um objeto JSON com os campos seconds e nanos representando, respectivamente, um número assinado de segundos da época UTC e um número não negativo de frações de segundos:

   jsonPayload: {
     ...
     "timestamp": {
       "seconds": CURRENT_SECONDS,
       "nanos": CURRENT_NANOS
     }
   }
   

2. Se a pesquisa anterior falhar, pesquise um par de campos timestampSeconds e timestampNanos:

   jsonPayload: {
     ...
     "timestampSeconds": CURRENT_SECONDS,
     "timestampNanos": CURRENT_NANOS
   }
   

3. Se a pesquisa anterior falhar, pesquise um campo time que seja uma string no formato RFC 3339:

   jsonPayload: {
     ...
     "time": CURRENT_TIME_RFC3339
   }
   

Quando informações relacionadas ao tempo são encontradas, o agente do Logging as usa para definir o valor de LogEntry.timestamp e não copia essas informações do registro estruturado para o objeto LogEntry.jsonPayload.

Os campos relacionados ao tempo que não são usados para definir o valor do campo LogEntry.timestamp são copiados do registro estruturado para o objeto LogEntry.jsonPayload. Por exemplo, se o registro estruturado contiver um objeto JSON timestamp e um campo time, os dados no objeto JSON timestamp serão usados para definir o campo LogEntry.timestamp. O objeto LogEntry.jsonPayload contém um campo time, porque esse campo não foi usado para definir o valor LogEntry.timestamp.

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

Observação: esta seção contém um exemplo de comando do Linux. Se você usa o Windows, será necessário adaptar as etapas de comando a esse ambiente. C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d é o diretório de configuração terceirizado para Windows. Além disso, use barras (/) no arquivo de configuração do Windows. Para mais informações sobre por que isso é necessário, consulte O padrão de caractere curinga no caminho não funciona no Windows.

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 adicional /etc/google-fluentd/config.d:

   sudo tee /etc/google-fluentd/config.d/test-unstructured-log.conf <<EOF
   <source>
       @type tail
       <parse>
           # 'none' indicates the log is unstructured (text).
           @type none
       </parse>
       # 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. No Explorador de registros, veja a entrada de registro 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

Observação: esta seção contém um exemplo de comando do Linux. Se você usa o Windows, será necessário adaptar as etapas de comando a esse ambiente. C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d é o diretório de configuração terceirizado para Windows. Além disso, use barras (/) no arquivo de configuração do Windows. Para mais informações sobre por que isso é necessário, consulte O padrão de caractere curinga no caminho não funciona no Windows.

É 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 adicional /etc/google-fluentd/config.d:

   sudo tee /etc/google-fluentd/config.d/test-structured-log.conf <<EOF
   <source>
       @type tail
       <parse>
           # 'json' indicates the log is structured (JSON).
           @type json
       </parse>
       # 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. No Explorador de registros, veja a entrada de registro 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 Explorador 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. No Explorador de registros, veja a entrada de registro 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 LogEntry:

• Dinamicamente, substituindo rótulos específicos em uma entrada estruturada por rótulos diferentes. Para mais detalhes, acesse Como configurar rótulos em entradas de registro estruturadas nesta página.
• Estaticamente, anexando um rótulo a qualquer ocorrência de um valor. Para detalhes, acesse Como configurar rótulos estaticamente nesta página.

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 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. 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.

Opções de configuração relacionadas ao buffer

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, ele gera exceções. Essa opção em combinação com buffer_chunk_limit determina o espaço em disco máximo que o fluentd ocupa para armazenamento em buffer.
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.

Opções de configuração relacionadas a recursos monitorados e projetos

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 Google Cloud ou da AWS 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_json^1	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.

¹Esse 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/
   

   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.

2. Opcional. Valide a mudança de configuração executando o comando a seguir:

   sudo service google-fluentd configtest
   

3. Reinicie o agente executando o seguinte comando:

   sudo service google-fluentd force-reload
   

Instância do Windows

Observação: se você estiver executando uma versão do agente anterior à v1-5, não será possível adicionar os próprios arquivos de configuração. Atualize para o agente mais recente.

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.