Configure o agente de registos

Esta página fornece detalhes sobre as configurações predefinidas e personalizadas do agente do Cloud Logging.

A maioria dos utilizadores não precisa de ler esta página. Leia esta página se:

• Tem interesse em saber detalhes técnicos detalhados da configuração do agente do Cloud Logging.

• Quiser alterar a configuração do agente do Cloud Logging.

Configuração predefinida

O agente de registo google-fluentd é uma versão modificada do coletor de dados de registo fluentd. O agente de registo vem com uma configuração predefinida. Na maioria dos casos comuns, não é necessária nenhuma configuração adicional.

Na sua configuração predefinida, o agente de registo transmite registos, conforme incluído na lista de registos predefinidos, para o Cloud Logging. Pode configurar o agente para transmitir registos adicionais; para obter detalhes, aceda a Personalizar a configuração do agente de registo nesta página.

O agente de registo usa plug-ins de entrada fluentd para obter e extrair registos de eventos de origens externas, como ficheiros no disco, ou para analisar registos de registo recebidos. Os plug-ins de entrada são incluídos no agente ou podem ser instalados separadamente como gems Ruby. Reveja a lista de plug-ins incluídos.

O agente lê os registos de registos armazenados em ficheiros de registos na instância de VM através do plug-in in_tail incorporado do fluentd. Cada registo de registos é convertido numa estrutura de entrada de registo para o Cloud Logging. O conteúdo de cada registo é, na sua maioria, registado no payload das entradas do registo, mas as entradas do registo também contêm elementos padrão, como uma data/hora e a gravidade. O agente de registo requer que cada registo de registo seja etiquetado com uma etiqueta no formato de string. Todos os plug-ins de consulta e saída correspondem a um conjunto específico de etiquetas. Normalmente, o nome do registo segue o formato projects/[PROJECT-ID]/logs/[TAG]. Por exemplo, este nome de registo inclui a etiqueta structured-log:

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

O plug-in de saída transforma cada mensagem estruturada internalizada numa entrada de registo no Cloud Logging. O payload torna-se o texto ou o payload JSON.

As secções seguintes desta página abordam a configuração predefinida em detalhe.

Definições de configuração predefinidas

As secções seguintes descrevem as definições de configuração predefinidas para o syslog, o plug-in de entrada de encaminhamento, as configurações de entrada para registos de aplicações de terceiros, como os da lista de registos predefinidos, e o nosso plug-in de saída do Google Cloud fluentd.

Localização do ficheiro de configuração de raiz

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

  Este ficheiro de configuração raiz também importa todos os ficheiros de configuração da pasta /etc/google-fluentd/config.d.

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

  Se estiver a executar um agente de registos anterior à v1-5, a localização é: C:\GoogleStackdriverLoggingAgent\fluent.conf

Configuração do Syslog

Nota: a seguinte configuração syslog predefinida, como parte do pacote google-fluentd-catch-all-config, é exclusiva dos sistemas operativos Linux.

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

• Descrição: este ficheiro inclui a configuração para especificar o syslog como uma entrada de registo.

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

Nome da configuração	Tipo	Predefinição	Descrição
format	de string	/^(?<message>(?<time>[^ ]*\s*[^ ]* [^ ]*) .*)$/	O formato do syslog.
path	de string	/var/log/syslog	O caminho do ficheiro syslog.
pos_file	de string	/var/lib/google-fluentd/pos/syslog.pos	O caminho do ficheiro de posição para esta entrada de registo. O fluentd regista a posição em que leu pela última vez neste ficheiro. Reveja a fluentd documentação detalhada.
read_from_head	booleano	true	Se deve começar a ler os registos a partir do início do ficheiro em vez da parte inferior. Reveja a fluentd documentação detalhada.
tag	de string	syslog	A etiqueta de registo desta entrada de registo.

Configuração do plugin de introdução in_forward

Nota: a seguinte configuração do plug-in in_forward predefinido, como parte do pacote google-fluentd-catch-all-config, é exclusiva dos sistemas operativos Linux.

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

• Description: este ficheiro inclui a configuração para configurar o plug-in de entrada in_forward fluentd. O plug-in de entrada in_forward permite-lhe transmitir registos através de um soquete TCP.

• Reveja a fluentddocumentação detalhada deste plug-in e o repositório de configuração.

Nome da configuração	Tipo	Predefinição	Descrição
port	int	24224	A porta a monitorizar.
bind	de string	127.0.0.1	O endereço de associação a monitorizar. Por predefinição, apenas são aceites ligações de localhost. Para abrir esta opção, tem de alterar a configuração para 0.0.0.0.

Configuração de entrada de registo de aplicações de terceiros

Nota: a seguinte configuração de registo de aplicações de terceiros predefinida, como parte do pacote google-fluentd-catch-all-config, é exclusiva dos sistemas operativos Linux.

• Localizações dos ficheiros de configuração: /etc/google-fluentd/config.d/[APPLICATION_NAME].conf

• Descrição: este diretório inclui ficheiros de configuração para especificar os ficheiros de registo de aplicações de terceiros como entradas de registo. Cada ficheiro, exceto syslog.conf e forward.conf, representa uma aplicação (por exemplo, apache.conf para a aplicação Apache).

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

Nome da configuração	Tipo	Predefinição	Descrição
format^1	de string	Varia consoante a aplicação	O formato do registo. Reveja a fluentd documentação detalhada.
path	de string	Varia consoante a aplicação	O caminho dos ficheiros de registo. Podem ser especificados vários caminhos, separados por ",". É possível incluir o formato * e strftime para adicionar/remover o ficheiro de observação dinamicamente. Reveja a fluentd documentação detalhada.
pos_file	de string	Varia consoante a aplicação	O caminho do ficheiro de posição para esta entrada de registo. O fluentd regista a posição em que leu pela última vez neste ficheiro. Reveja a fluentddocumentação detalhada).
read_from_head	booleano	true	Se deve começar a ler os registos a partir do início do ficheiro em vez da parte inferior. Reveja a fluentd documentação detalhada.
tag	de string	Varia; o nome da aplicação.	A etiqueta de registo desta entrada de registo.

¹ Se estiver a usar a secção <parse>, especifique o formato do registo através de @type.

Configuração do plugin de saídaGoogle Cloud fluentd

• Localizações dos ficheiros de configuração:

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

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

    Se estiver a executar um agente de registos anterior à v1-5, a localização é: C:\GoogleStackdriverLoggingAgent\fluent.conf

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

• Aceda ao repositório de configuração.

Nome da configuração	Tipo	Predefinição	Descrição
buffer_chunk_limit	de string	512KB	À medida que os registos de registo são recebidos, os que não podem ser escritos nos componentes a jusante com rapidez suficiente são enviados para uma fila de blocos. Esta configuração define o limite de tamanho de cada fragmento. Por predefinição, definimos o limite de blocos de forma conservadora para evitar exceder o tamanho de bloco recomendado de 5 MB por pedido de gravação na API Logging. As entradas de registo no pedido de API podem ser 5 a 8 vezes maiores do que o tamanho do registo original com todos os metadados adicionais anexados. Um bloco de buffer é esvaziado se uma das duas condições for cumprida: 1. O flush_interval é ativado. 2. O tamanho da memória intermédia atinge buffer_chunk_limit.
flush_interval	de string	5s	À medida que os registos de registo são recebidos, os que não podem ser escritos nos componentes a jusante com rapidez suficiente são enviados para uma fila de blocos. A configuração define o tempo que temos antes de ter de limpar um buffer de blocos. Um bloco de buffer é esvaziado se uma das duas condições for cumprida: 1. O flush_interval é ativado. 2. O tamanho da memória intermédia atinge buffer_chunk_limit.
disable_retry_limit	booleano	false	Aplica um limite ao número de novas tentativas de descarga com falhas de blocos de buffer. Reveja as especificações detalhadas em retry_limit, retry_wait e max_retry_wait.
retry_limit	int	3	Quando não é possível esvaziar um fragmento de buffer, o fluentd tenta novamente mais tarde por predefinição. Esta configuração define o número de novas tentativas a realizar antes de rejeitar um fragmento de buffer problemático.
retry_wait	int	10s	Quando não é possível esvaziar um fragmento de buffer, o fluentd tenta novamente mais tarde por predefinição. Esta configuração define o intervalo de espera em segundos antes da primeira repetição. O intervalo de espera duplica em cada nova tentativa (20 s, 40 s,…) até atingir retry_ limit ou max_retry_wait.
max_retry_wait	int	300	Quando não é possível esvaziar um fragmento de buffer, o fluentd tenta novamente mais tarde por predefinição. O intervalo de espera duplica em cada nova tentativa (20 s, 40 s,…) Esta configuração define o máximo de intervalos de espera em segundos. Se o intervalo de espera atingir este limite, a duplicação é interrompida.
num_threads	int	8	O número de descargas de registos simultâneas que podem ser processadas pelo plug-in de saída.
use_grpc	booleano	true	Se deve usar gRPC em vez de REST/JSON para comunicar com a API Logging. Com o gRPC ativado, a utilização da CPU é normalmente mais baixa
grpc_compression_algorithm	enum	none	Se estiver a usar gRPC, define o esquema de compressão a usar. Pode ser none ou gzip.
partial_success	booleano	true	Indica se deve ser suportada a execução parcial para o carregamento de registos. Se true, as entradas de registo inválidas num conjunto completo são ignoradas e as entradas de registo válidas são carregadas com êxito na API Logging. Se false, o conjunto completo seria ignorado se contivesse entradas de registo inválidas.
enable_monitoring	booleano	true	Quando definido como true, o agente de registo exporta a telemetria interna. Consulte o artigo Telemetria do plug-in de saída para ver detalhes.
monitoring_type	de string	opencensus	O tipo de monitorização. As opções suportadas são opencensus e prometheus. Consulte o artigo Telemetria do plug-in de saída para ver detalhes.
autoformat_stackdriver_trace	booleano	true	Quando definido como true, o rastreio é reformatado se o valor do campo de carga útil estruturada logging.googleapis.com/trace corresponder ao formato ResourceTrace traceId. Pode encontrar detalhes sobre a formatação automática em Campos especiais em payloads estruturados nesta página.

Configuração da monitorização

Telemetria do plugin de saída

A opção enable_monitoring controla se o plug-in de saída recolhe a respetiva telemetria interna. Google Cloud fluentd Quando definido como true, o agente de registos monitoriza o número de entradas de registo pedidas para envio para o Cloud Logging e o número real de entradas de registo carregadas com êxito pelo Cloud Logging. Quando definido como false, o plugin de saída não recolhe métricas.

A opção monitoring_type controla a forma como esta telemetria é exposta pelo agente. Consulte a lista de métricas abaixo.

Quando definido como prometheus, o agente de registo expõe métricas no formato Prometheus no ponto final do Prometheus (localhost:24231/metrics por predefinição; consulte a configuração do plug-in prometheus e prometheus_monitor para ver detalhes sobre a personalização). Nas VMs do Compute Engine, para que essas métricas sejam escritas na API Monitoring, o agente Monitoring também tem de estar instalado e em execução.

Quando definida como opencensus (predefinição desde a versão v1.6.25), o agente de registo escreve diretamente as suas próprias métricas de estado na API Monitoring. Isto requer que a função roles/monitoring.metricWriter seja concedida à conta de serviço predefinida do Compute Engine, mesmo que o agente de monitorização não esteja instalado.

As seguintes métricas são escritas na API Monitoring pelo agente de monitorização e pelo agente de registo no modo opencensus:

• agent.googleapis.com/agent/uptime com uma etiqueta version: Tempo de atividade do agente de registos.
• agent.googleapis.com/agent/log_entry_count com uma etiqueta response_code: Contagem de entradas de registo escritas pelo agente de registos.
• agent.googleapis.com/agent/log_entry_retry_count com uma response_code etiqueta: Contagem de entradas de registo escritas pelo agente de registos.
• agent.googleapis.com/agent/request_count com uma etiqueta response_code: Contagem de pedidos de API do agente de registos.

Estas métricas são descritas mais detalhadamente na página Métricas do agente.

Além disso, o plug-in de saída expõe as seguintes métricas do Prometheus no modo prometheus:

• uptime com uma etiqueta version: Tempo de atividade do agente de registos.
• stackdriver_successful_requests_count com etiquetas grpc e code: O número de pedidos bem-sucedidos à API Logging.
• stackdriver_failed_requests_count com etiquetas grpc e code: O número de pedidos falhados para a API Logging, discriminado pelo código de erro.
• stackdriver_ingested_entries_count com as etiquetas grpc e code: O número de entradas de registo carregadas pela API Logging.
• stackdriver_dropped_entries_count com etiquetas grpc e code: O número de entradas de registo rejeitadas pela API Logging.
• stackdriver_retried_entries_count com etiquetas grpc e code: O número de entradas de registo que não foram carregadas pelo plug-in de saída Google Cloud fluentd devido a um erro temporário e foram repetidas.

Configuração do plugin prometheus e prometheus_monitor

Nota: a seguinte configuração de monitorização predefinida é exclusiva dos sistemas operativos Linux.

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

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

• Aceda ao repositório de configuração.

Para monitorizar o Fluentd, o servidor de métricas http do Prometheus incorporado está ativado por predefinição. Pode remover a seguinte secção da configuração para impedir que este ponto final seja iniciado:

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

Processamento de payloads

A maioria dos registos suportados na configuração predefinida do agente de registo são provenientes de ficheiros de registo e são carregados como payloads não estruturados (texto) nas entradas de registo.

A única exceção é o plug-in de entrada in_forward, que também está ativado por predefinição e só aceita registos estruturados e carrega-os como payloads estruturados (JSON) nas entradas do registo. Para ver detalhes, leia o artigo Transmitir registos estruturados (JSON) através do plug-in in_forward nesta página.

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

Pode personalizar a configuração do agente para suportar a ingestão de registos estruturados de recursos adicionais. Consulte o artigo Transmitir registos estruturados (JSON) para o Cloud Logging para ver detalhes.

O payload dos registos de registo transmitidos por um agente de registo configurado de forma 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 de registo recebe um registo de registo estruturado, move qualquer chave que corresponda à tabela seguinte para o campo correspondente no objeto LogEntry. Caso contrário, a chave passa a fazer parte do campo LogEntry.jsonPayload. Este comportamento permite-lhe definir campos específicos no objeto LogEntry, que é o que é escrito na API Logging. Por exemplo, se o registo de registo estruturado contiver uma chave de severity, o agente de registo preenche o campo LogEntry.severity.

Campo de registo JSON	LogEntry campo	Função do agente do Cloud Logging	Valor de exemplo
severity	severity	O agente Logging tenta encontrar correspondência com várias strings de gravidade comuns, incluindo a lista de strings LogSeverity reconhecidas pela API Logging.	"severity":"ERROR"
message	textPayload (ou parte de jsonPayload)	A mensagem que aparece na linha de entrada do registo no Logs Explorer.	"message":"There was an error in the application." Nota: message é guardado como textPayload se for o único campo restante após o agente de registo mover os outros campos de fins especiais e detect_json não tiver sido ativado; caso contrário, message permanece em jsonPayload. detect_json não é aplicável a ambientes de registo geridos, como o Google Kubernetes Engine. Se a entrada do registo contiver um rastreio da pilha de exceções, o rastreio da pilha de exceções deve ser definido neste campo do registo JSON message, para que o rastreio da pilha de exceções possa ser analisado e guardado no Error Reporting.
log(Apenas Google Kubernetes Engine antigo)	textPayload	Aplica-se apenas ao Google Kubernetes Engine antigo: se, após mover os campos de fins especiais, restar apenas um campo log, esse campo é guardado como textPayload.
httpRequest	httpRequest	Um registo estruturado no formato do campo LogEntry HttpRequest.	"httpRequest":{"requestMethod":"GET"}
campos relacionados com o tempo	timestamp	Para mais informações, consulte a secção Campos relacionados com o 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 deste campo tem de ser um registo 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 deste campo também é usado pelo Logs Explorer para agrupar entradas de registo 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 de localização do código-fonte associadas à entrada do registo, se existirem. 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 intervalo na rastreio associado à entrada do registo. Para mais informações, consulte spanId na página LogEntry.	"logging.googleapis.com/spanId":"000000000000004a"
logging.googleapis.com/trace	trace	Nome do recurso do rastreio associado à entrada do registo se existir. Para mais informações, consulte trace na página LogEntry.	"logging.googleapis.com/trace":"projects/my-projectid/traces/0679686673a" Nota: se não estiver a escrever para stdout ou stderr, o valor deste campo deve ser formatado como projects/[PROJECT-ID]/traces/[TRACE-ID], para que possa ser usado pelo Explorador de registos e pelo visualizador de rastreios para agrupar entradas de registo e apresentá-las em linha com os rastreios. Se autoformat_stackdriver_trace for verdadeiro e [V] corresponder ao formato de ResourceTrace, o campo traceId LogEntry tem o valor trace.projects/[PROJECT-ID]/traces/[V]
logging.googleapis.com/trace_sampled	traceSampled	O valor deste campo tem de ser true ou false. Para mais informações, consulte traceSampled na página LogEntry.	"logging.googleapis.com/trace_sampled": false

Campos relacionados com o tempo

Em geral, as informações relacionadas com o tempo sobre uma entrada de registo 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 registo são dados estruturados, o agente Logging usa as seguintes regras para pesquisar os campos na entrada jsonPayload para informações relacionadas com o tempo:

1. Procure um campo timestamp que seja um objeto JSON que inclua os campos seconds e nanos, que representam, respetivamente, um número assinado de segundos desde a época UTC e um número não negativo de segundos fracionários:

   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 são encontradas informações relacionadas com o tempo, o agente de registo usa essas informações para definir o valor de LogEntry.timestamp e não copia essas informações do registo estruturado para o objeto LogEntry.jsonPayload.

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

Personalizar a configuração do agente

Além da lista de registos predefinidos que o agente de registo transmite por predefinição, pode personalizar o agente de registo para enviar registos adicionais para o registo ou ajustar as definições do agente adicionando configurações de entrada.

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

• Localizações dos ficheiros de configuração principais:

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

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

    Se estiver a executar um agente de registos anterior à v1-5, a localização é: C:\GoogleStackdriverLoggingAgent\fluent.conf

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

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

Registo de streaming de entradas adicionais

Pode personalizar o agente de registo para enviar registos adicionais para o registo adicionando configurações de entrada.

Streaming de registos não estruturados (texto) através de ficheiros de registo

Nota: esta secção contém um exemplo de comando do Linux. Se usar o Windows, tem de adaptar os passos dos comandos a esse ambiente. C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d é o diretório de configuração de terceiros para o Windows. Além disso, certifique-se de que usa barras (/) no ficheiro de configuração para Windows. Para mais informações sobre o motivo pelo qual isto é necessário, consulte o artigo O padrão de caráter universal no caminho não funciona no Windows.

1. Na linha de comandos do Linux, crie um ficheiro de registo:

   touch /tmp/test-unstructured-log.log
   

2. Crie um novo ficheiro de configuração com a etiqueta 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
   

   Em alternativa à criação de um novo ficheiro, pode adicionar as informações de configuração a um ficheiro de configuração existente.

3. Reinicie o agente para aplicar as alterações de configuração:

   sudo service google-fluentd restart
   

4. Gerar um registo no ficheiro de registo:

   echo 'This is a log from the log file at test-unstructured-log.log' >> /tmp/test-unstructured-log.log
   

5. Verifique o Explorador de registos para ver a entrada de registo carregada:

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

Streaming de registos estruturados (JSON) através de ficheiros de registo

Nota: esta secção contém um exemplo de comando do Linux. Se usar o Windows, tem de adaptar os passos dos comandos a esse ambiente. C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d é o diretório de configuração de terceiros para o Windows. Além disso, certifique-se de que usa barras (/) no ficheiro de configuração para Windows. Para mais informações sobre o motivo pelo qual isto é necessário, consulte o artigo O padrão de caráter universal no caminho não funciona no Windows.

Pode configurar o agente de registo para exigir que cada entrada de registo para determinadas entradas de registo seja estruturada. Também pode personalizar o agente do Logging para carregar conteúdo formatado em JSON a partir de um ficheiro de registo. Quando o agente está configurado para carregar conteúdo JSON, a entrada tem de ser formatada de modo que cada objeto JSON esteja numa nova linha:

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

Para configurar o agente de registo para carregar conteúdo formatado em JSON, faça o seguinte:

1. Na linha de comandos do Linux, crie um ficheiro de registo:

   touch /tmp/test-structured-log.log
   

2. Crie um novo ficheiro de configuração com a etiqueta 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
   

   Em alternativa à criação de um novo ficheiro, pode adicionar as informações de configuração a um ficheiro de configuração existente.

3. Reinicie o agente para aplicar as alterações de configuração:

   sudo service google-fluentd restart
   

4. Gerar um registo no ficheiro de registo:

   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. Verifique o Explorador de registos para ver a entrada de registo carregada:

   {
     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 registos, filtre por tipo de recurso e logName de structured-log.

Para ver opções adicionais de personalização do formato de entrada de registos para aplicações comuns de terceiros, consulte o artigo Formatos de registos comuns e como analisá-los.

Streaming de registos estruturados (JSON) através do plug-in in_forward

Além disso, pode enviar registos através do plug-in fluentd in_forward. fluentd-cat é uma ferramenta integrada que ajuda a enviar facilmente registos para o plug-in in_forward. A fluentd documentação contém mais detalhes sobre esta ferramenta.

Para enviar registos através do plugin fluentd in_forward, leia as seguintes instruções:

1. Execute o seguinte comando na VM com o agente 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. Verifique o Explorador de registos para ver a entrada de registo carregada:

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

Streaming de registos estruturados (JSON) do código da aplicação

Pode ativar conetores em vários idiomas para enviar registos estruturados a partir do código da aplicação. Para mais informações, reveja a fluentddocumentação. Estes conetores são criados com base no plug-in in_forward.

Definir etiquetas de entradas do registo

As seguintes opções de configuração permitem substituir as etiquetas LogEntry e as etiquetas MonitoredResource quando carrega registos para o Cloud Logging. Todas as entradas de registo estão associadas a recursos monitorizados. Para mais informações, reveja a lista de tipos de recursos monitorizados do Cloud Logging.

Nome da configuração	Tipo	Predefinição	Descrição
label_map	hash	nil	label_map (especificado como um objeto JSON) é um conjunto não ordenado de nomes de campos fluentd cujos valores são enviados como etiquetas em vez de como parte do payload estruturado. Cada entrada no mapa é um par {field_name: label_name}. Quando é encontrado field_name (analisado pelo plug-in de entrada), é adicionada uma etiqueta com o label_name correspondente à entrada do registo. O valor do campo é usado como o valor da etiqueta. O mapa oferece-lhe flexibilidade adicional na especificação dos nomes das etiquetas, incluindo a capacidade de usar carateres que não seriam legais como parte dos nomes dos campos fluentd. Para ver um exemplo, aceda a Definir etiquetas em entradas de registo estruturadas.
labels	hash	nil	labels (especificado como um objeto JSON) é um conjunto de etiquetas personalizadas fornecidas no momento da configuração. Permite-lhe inserir informações ambientais adicionais em todas as mensagens ou personalizar etiquetas detetadas automaticamente. Cada entrada no mapa é um par {label_name: label_value}.

O plug-in de saída do agente de registos suporta três formas de definir etiquetas LogEntry:

• Substituindo dinamicamente etiquetas específicas numa entrada estruturada por etiquetas diferentes. Para obter detalhes, aceda a Definir etiquetas em entradas de registo estruturadas nesta página.
• Atribuir estaticamente uma etiqueta a qualquer ocorrência de um valor. Para ver detalhes, aceda à secção Definir etiquetas estaticamente nesta página.

Definir etiquetas em entradas de registo estruturadas

Suponhamos que escreveu um payload de entrada de registo estruturado como este:

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

Suponhamos que quer traduzir o campo de carga útil env para uma etiqueta de metadados environment. Para tal, adicione o seguinte à configuração do plug-in de saída no ficheiro 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 definição label_map aqui substitui a etiqueta env no payload por environment, pelo que a entrada de registo resultante tem uma etiqueta environment com o valor production.

Definir etiquetas de forma estática

Se não tiver estas informações na carga útil e quiser simplesmente adicionar uma etiqueta de metadados estática denominada environment, adicione o seguinte à configuração do plug-in de saída no ficheiro 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>

Neste caso, em vez de usar um mapa para substituir uma etiqueta por outra, usamos uma definição labels para anexar uma etiqueta com um determinado valor literal a uma entrada de registo, independentemente de a entrada já ter uma etiqueta ou não. Esta abordagem pode ser usada mesmo que esteja a enviar registos não estruturados.

Para mais informações sobre como configurar labels, label_map e outras definições do agente de registo, aceda a Definir etiquetas de entradas de registo nesta página.

Modificar registos de registo

O Fluentd oferece plug-ins de filtro incorporados que podem ser usados para modificar as entradas do registo.

O plug-in de filtro mais usado é o filter_record_transformer. Permite-lhe:

• Adicione novos campos às entradas do registo
• Atualize campos nas entradas do registo
• Elimine campos em entradas de registo

Alguns plug-ins de saída também lhe permitem modificar as entradas do registo. O plugin de saída fluent-plugin-record-reformer oferece uma funcionalidade semelhante à do plugin de filtro filter_record_transformer, exceto que também lhe permite modificar as etiquetas de registo. É esperado um maior consumo de recursos com este plug-in: sempre que uma etiqueta de registo é atualizada, gera uma nova entrada de registo com a nova etiqueta. Tenha em atenção que o campo tag na configuração é obrigatório. Também recomendamos que modifique este campo para evitar a entrada num ciclo infinito.

O plug-in de saída fluent-plugin-detect-exceptions analisa uma stream de registo, não estruturada (texto) ou registos de registo no formato JSON, para encontrar rastreios de pilha de exceções de várias linhas. Se uma sequência consecutiva de entradas de registo formar um rastreio de pilha de exceções, as entradas de registo são encaminhadas como uma única mensagem de registo combinada. Caso contrário, a entrada do registo é encaminhada tal como estava.

Definições de configuração avançadas (não predefinidas)

Se quiser personalizar a configuração do seu agente de registo, além da configuração predefinida, continue a ler esta página.

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

As seguintes opções de configuração permitem ajustar o mecanismo de armazenamento em buffer interno do agente de registo.

Nome da configuração	Tipo	Predefinição	Descrição
buffer_type	de string	buf_memory	Os registos que não podem ser escritos na API Logging com rapidez suficiente são enviados para um buffer. O buffer pode estar na memória ou em ficheiros reais. Valor recomendado: buf_file. A predefinição buf_memory é rápida, mas não persistente. Existe o risco de perder registos. Se buffer_type for buf_file, também tem de especificar buffer_path.
buffer_path	de string	Especificado pelo utilizador	O caminho onde os fragmentos de buffer são armazenados. Este parâmetro é obrigatório se buffer_type for file. Esta configuração tem de ser exclusiva para evitar uma condição de concorrência.
buffer_queue_limit	int	64	Especifica o limite de comprimento da fila de blocos. Quando a fila de buffer atinge este número de fragmentos, o comportamento do buffer é controlado por buffer_queue_full_action. Por predefinição, gera exceções. Esta opção, em combinação com buffer_chunk_limit, determina o espaço máximo no disco que o fluentd ocupa para o armazenamento temporário.
buffer_queue_full_action	de string	exception	Controla o comportamento do buffer quando a fila do buffer está cheia. Valores possíveis: 1. exception: lançar BufferQueueLimitError quando a fila estiver cheia. A forma como o BufferQueueLimitError é processado depende dos plug-ins de entrada. Por exemplo, o plugin de entrada in_tail deixa de ler novas linhas, enquanto o plugin de entrada in_forward devolve um erro. 2. block: este modo para a thread do plug-in de entrada até que a condição de buffer cheio seja resolvida. Esta ação é adequada para exemplos de utilização semelhantes a lotes. O fluentd não recomenda a utilização da ação de bloqueio para evitar BufferQueueLimitError. Se atingir o limite BufferQueueLimitError com frequência, significa que a capacidade do destino é insuficiente para o seu tráfego. 3. drop_oldest_chunk: este modo elimina os fragmentos mais antigos.

Opções de configuração relacionadas com o projeto e o recurso monitorizado

As seguintes opções de configuração permitem-lhe especificar manualmente um projeto e determinados campos do objeto MonitoredResource. Estes valores são recolhidos automaticamente pelo agente de registo. Não é recomendado especificá-los manualmente.

Nome da configuração	Tipo	Predefinição	Descrição
project_id	de string	nil	Se for especificado, substitui o project_id que identifica o projeto subjacente Google Cloud ou da AWS no qual o agente do Logging está a ser executado.
zone	de string	nil	Se for especificado, substitui a zona.
vm_id	de string	nil	Se for especificado, substitui o ID da VM.
vm_name	de string	nil	Se for especificado, isto substitui o nome da VM.

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

Nome da configuração	Tipo	Predefinição	Descrição
detect_json^1	booleano	false	Se deve tentar detetar se o registo é uma entrada de registo de texto com conteúdo JSON que precisa de ser analisado. Se esta opção estiver true e for detetada uma entrada de registo não estruturada (texto) no formato JSON, esta é analisada e enviada como um payload estruturado (JSON).
coerce_to_utf8	booleano	true	Se devem ser permitidos carateres não UTF-8 nos registos do utilizador. Se estiver definido como true, qualquer caráter que não seja UTF-8 é substituído pela string especificada por non_utf8_replacement_string. Se estiver definido como false, qualquer caráter que não seja UTF-8 aciona um erro no plugin.
require_valid_tags	booleano	false	Rejeita entradas de registo com etiquetas inválidas. Se esta opção estiver definida como false, as etiquetas são validadas convertendo qualquer etiqueta que não seja uma string numa string e limpando quaisquer carateres que não sejam UTF-8 ou outros carateres inválidos.
non_utf8_replacement_string	de string	""(space)	Se coerce_to_utf8 estiver definido como true, qualquer caráter que não seja UTF-8 é substituído pela string especificada aqui.

¹Esta funcionalidade está ativada por predefinição em instâncias de VM em execução no ambiente flexível do App Engine e no Google Kubernetes Engine.

Aplicar configuração do agente personalizada

A personalização do agente de registo permite-lhe adicionar os seus próprios fluentd ficheiros de configuração:

Instância do Linux

1. Copie os ficheiros de configuração para o seguinte diretório:

   /etc/google-fluentd/config.d/
   

   O script de instalação do agente de registo preenche este diretório com os ficheiros de configuração de captura geral predefinidos. Para mais informações, consulte o artigo Obter o código fonte do agente Logging.

2. Opcional. Valide a alteração da configuração executando o seguinte comando:

   sudo service google-fluentd configtest
   

3. Reinicie o agente executando o seguinte comando:

   sudo service google-fluentd force-reload
   

Instância do Windows

Nota: se estiver a executar uma versão do agente anterior à v1-5, não pode adicionar os seus próprios ficheiros de configuração. Atualize para o agente mais recente.

1. Copie os ficheiros de configuração para o subdiretório config.d do diretório de instalação do agente. Se aceitou o diretório de instalação predefinido, este diretório é:

   C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\
   

2. Reinicie o agente executando os seguintes comandos numa shell de linha de comandos:

   net stop  StackdriverLogging
   net start StackdriverLogging
   

Para mais informações sobre os fluentdficheiros de configuração, consulte a documentação sobre a sintaxe dos ficheiros de configuração do fluentd.