Introdução

Use o software do coletor de dados de código aberto Fluentd para coletar dados de log da sua origem. Instale o Plug-in de Saída do OCI Log Analytics para rotear os dados de log coletados para a Oracle Cloud Log Analytics.

Observação: A Oracle recomenda que você use os Agentes de Gerenciamento do Oracle Cloud para obter a melhor experiência de ingestão de dados de log no Oracle Cloud Log Analytics. No entanto, se essa não for uma opção possível para seu caso, só use o Plug-in de Saída do OCI Log Analytics para Fluentd.

Neste tutorial, é usada uma configuração do Fluentd baseada no pacote rpm td-agent instalado no Oracle Linux, mas as etapas necessárias podem ser semelhantes para outras distribuições do Fluentd.

O Fluentd tem componentes que trabalham juntos para coletar os dados de log das origens de entrada, transformar os logs e rotear os dados de log para a saída desejada. Você pode instalar e configurar o plug-in de saída do Fluentd para ingerir logs de várias origens no Oracle Cloud Log Analytics.

Descrição da ilustração fluentd_plugin_overview.png

Objetivos

  • Saiba como instalar o plug-in de saída do OCI Log Analytics fornecido pela Oracle para ingerir logs da sua origem.
  • Crie a configuração Fluentd para estabelecer a coleta de logs da sua origem para o Log Analytics.

Migrar o Plug-in de Saída do OCI Log Analytics da versão 1.x para 2.x

Se você for um novo usuário do Plug-in de Saída do OCI Log Analytics e ainda não tiver feito download e instalado, ignore esta seção e vá para Pré-requisitos. Se você instalou o plug-in versão 1.x usando o arquivo fluent-plugin-oci-logging-analytics-1.0.0.gem, observe que podem ser necessárias alterações para migrar para o plug-in versão 2.x.

Os seguintes parâmetros de configuração foram renomeados no version 2.x:
1.x 2.x
global_metadata oci_la_global_metadata
metadados oci_la_metadata
entityId oci_la_entity_id
entityType oci_la_entity_type
logSourceName oci_la_log_source_name
logPath oci_la_log_path
logGroupId oci_la_log_group_id
  • O suporte é adicionado para limpeza automática de logs do Plug-in de Saída do OCI Log Analytics.
  • O parâmetro plugin_log_rotation agora está obsoleto. Em vez disso, use os parâmetros plugin_log_file_size e plugin_log_file_count em conjunto para executar a mesma ação.
  • Instale o plug-in version 2.x usando o comando disponível na seção Instalar o Plug-in de Saída.

Execute os Pré-requisitos

Criar o Arquivo de Configuração Fluentd

Para configurar o Fluentd para rotear os dados de log para o Oracle Cloud Log Analytics, edite o arquivo de configuração fornecido pelo Fluentd ou pelo td-agent e forneça as informações pertencentes ao Oracle Cloud Log Analytics e outras personalizações.

A configuração do plug-in de saída Fluentd terá o seguinte formato:

<match pattern>
@type oci-logging-analytics
 namespace                   <YOUR_OCI_TENANCY_NAMESPACE>

# Auth config file details
 config_file_location        ~/.oci/config 
 profile_name                DEFAULT

# When there is no credentials for proxy
 http_proxy                  "#{ENV['HTTP_PROXY']}"

# To provide proxy credentials
 proxy_ip                    <IP>
 proxy_port                  <port>
 proxy_username              <user>
 proxy_password              <password>

# Configuration for plugin (oci-logging-analytics) generated logs
 plugin_log_location       "#{ENV['FLUENT_OCI_LOG_LOCATION'] || '/var/log'}" 
 plugin_log_level          "#{ENV['FLUENT_OCI_LOG_LEVEL'] || 'info'}"
 plugin_log_rotation       "#{ENV['FLUENT_OCI_LOG_ROTATION'] || 'daily'}"  **(DEPRECATED)**
 plugin_log_file_size      "#{ENV['FLUENT_OCI_LOG_AGE'] || '1MB'}"
 plugin_log_file_count     "#{ENV['FLUENT_OCI_LOG_AGE'] || '10'}"

# Buffer Configuration
 <buffer>
       @type file
       path                                "#{ENV['FLUENT_OCI_BUFFER_PATH'] || '/var/log'}"
       flush_thread_count                  "#{ENV['FLUENT_OCI_BUFFER_FLUSH_THREAD_COUNT'] || '10'}"
       retry_wait                          "#{ENV['FLUENT_OCI_BUFFER_RETRY_WAIT'] || '2'}"                     #seconds
       retry_max_times                     "#{ENV['FLUENT_OCI_BUFFER_RETRY_MAX_TIMES'] || '10'}"
       retry_exponential_backoff_base      "#{ENV['FLUENT_OCI_BUFFER_RETRY_EXPONENTIAL_BACKOFF_BASE'] || '2'}" #seconds
       retry_forever                       true
       overflow_action                     block
       disable_chunk_backup                true
 </buffer>
	</match>

É recomendável que um plug-in secundário seja configurado, que seria usado pelo Fluentd para fazer dump dos dados de backup quando o plug-in de saída continuar a falhar ao gravar os chunks de buffer e exceder o limite de timeout para novas tentativas. Além disso, para erros irrecuperáveis, o Fluentd abortará o bloco imediatamente e o moverá para o diretório secundário ou de backup. Consulte Documentação do Fluentd: Saída Secundária.

Parâmetros de Configuração do Plug-in de Saída

Forneça valores adequados aos seguintes parâmetros no arquivo de configuração Fluentd:

Parâmetro da configuração Descrição
namespace (Parâmetro obrigatório) Namespace da Tenancy do OCI para o qual os dados de log coletados serão submetidos a upload
config_file_location O local do arquivo de configuração que contém detalhes de autenticação do OCI
profile_name Nome do Perfil de Configuração do OCI a ser usado no arquivo de configuração
http_proxy Proxy sem credenciais. Exemplo: www.proxy.com:80
proxy_ip Detalhes do IP do proxy quando as credenciais são necessárias. Exemplo: www.proxy.com
proxy_port Detalhes da porta proxy quando as credenciais forem necessárias. Exemplo: 80
proxy_username Detalhes do nome de usuário proxy
proxy_password Detalhes da senha do proxy quando as credenciais são obrigatórias
plugin_log_location Caminho do arquivo do plug-in de Saída para gravar seus próprios logs. Verifique se o caminho existe e se está acessível. Valor padrão: Diretório de trabalho.
plugin_log_level Nível de log do plug-in de saída: DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN. Valor padrão: INFO.
plugin_log_rotation (DEPRECATED) Frequência de rotação do arquivo de log do plug-in de saída: diária, semanal ou mensal. Valor padrão: diário.
plugin_log_file_size O tamanho máximo do arquivo de log em que ponto o arquivo de log será girado.' (1KB, 1MB etc.). Valor padrão: 1MB.
plugin_log_file_count O número de arquivos de log arquivados/rotados a serem mantidos (Maior que 0). Valor padrão: 10.

Se você não especificar os parâmetros config_file_location e profile_name para os nós de Computação do OCI, a autenticação baseada em instance_principal será usada.

Parâmetros de Configuração do Buffer

No mesmo arquivo de configuração que você editou na seção anterior, modifique a seção de buffer e forneça as seguintes informações obrigatórias:

Parâmetro Obrigatório Descrição
@type Isso especifica qual plug-in usar como backend. Informe o arquivo.
caminho O caminho onde os arquivos de buffer são armazenados. Verifique se o caminho existe e se está acessível.

Os seguintes parâmetros opcionais podem ser incluídos no bloco de buffer:

Parâmetro Opcional Valor padrão Descrição
flush_thread_count 1 O número de threads para liberar/gravar partes em paralelo.
retry_wait 1s Aguarde em segundos antes da próxima tentativa para liberar.
retry_max_times none Isso é obrigatório somente quando o campo retry_forever é falso.
retry_exponential_backoff_base 2 Aguarde em segundos antes do próximo fator constante de backoff exponencial.
retry_forever false Se for verdadeiro, o plug-in ignorará a opção retry_max_times e tentará executar a descarga novamente para sempre.
overflow_action throw_exception Valores Possíveis: throw_exception / bloco / drop_oldest_chunk. Valor Recomendado: bloco.
disable_chunk_backup false Quando especificado false, partes irrecuperáveis no diretório de backup serão descartadas.
chunk_limit_size 8MB O tamanho máximo de cada bloco. Os eventos serão escritos em pedaços até que o tamanho dos pedaços se torne esse tamanho. Observação: independentemente do valor especificado, o plug-in de saída do Log Analytics atualmente padroniza o valor para 1 MB.
total_limit_size 64GB (para arquivo) Quando o tamanho total do buffer armazenado atingir esse limite, todas as operações de adição falharão com erro (e os dados serão perdidos).
flush_interval 60s Frequência de descarga de chunks para o plug-in de saída.

Para obter detalhes sobre os possíveis valores dos parâmetros, consulte Documentação do Fluentd: Plug-ins de buffer.

Verificar o formato dos eventos de registro de entrada

Os eventos de log de entrada devem estar em um formato específico para que o plug-in Fluentd fornecido pela Oracle possa processar os dados de log, fragmentá-los e transferi-los para o Oracle Cloud Log Analytics.

Visualize o exemplo de configuração que pode ser utilizado para monitorar arquivos de log syslog, apache e kafka em Exemplo de configuração de entrada.

Configuração do Plug-in de Origem/Entrada

Exemplo de configuração de origem para logs syslog:

<source>
  @type tail
  @id in_tail_syslog
  multiline_flush_interval 5s
  path /var/log/messages*
  pos_file /var/log/messages*.log.pos
  read_from_head true
  path_key tailed_path
  tag oci.syslog
  <parse>
    @type json
  </parse>
</source>

Os seguintes parâmetros são obrigatórios para definir o bloco de origem:

  • @type: O tipo de plug-in de entrada. Use tail para consumir eventos de um arquivo local. Os outros valores possíveis podem ser http, forward.

  • path: O caminho para os arquivos de origem.

  • tag: A tag que será usada pelo plug-in Fluentd da Oracle para filtrar os eventos de log que devem ser consumidos pelo Log Analytics. Certifique-se de usar o prefixo oci, por exemplo, oci.syslog.

  • Diretiva de parsing: É recomendável que você não defina a diretiva de parsing no arquivo de configuração. Mantenha o valor <parse> @type none </parse>. Em vez disso, você pode usar os Parsers e Origens definidos pela Oracle fornecidos pelo Log Analytics ou criar seus próprios parsers e origens no Log Analytics. Para logs agrupados em um wrapper json, use a diretiva de parsing <parse> @type json </parse>. Substitua o campo de mensagem no filtro record_transformer pelo valor ${record["log"]}.

    Observação:

    • É recomendável que você não use nenhum analisador Fluentd. Em vez disso, envie os logs para o Log Analytics no formato original. A diretiva de análise deve ser da forma:

      <parse>
    @type none
</parse>

    • No entanto, no caso de entradas de log com várias linhas, utilize o tipo de analisador com várias linhas para enviar várias linhas de um log como um único registro. Por exemplo:

      <parse>
    @type multiline
    format_firstline /^\S+\s+\d{1,2}\s+\d{1,2}:\d{1,2}:\d{1,2}\s+/
    format1 /^(?<message>.*)/
</parse>

    • Para logs originais que são encapsulados pelo wrapper json em que uma das chaves nos pares de chave/valor é log, recomendamos que você use a seguinte diretiva de parsing:

      <parse>
    @type json
</parse>

    E, substitua o campo message no filtro record_transformer pelo message ${record["log"]}. Por exemplo, no bloco de filtros a seguir para logs do kafka, o conteúdo do log é armazenado no valor do log da chave que é encapsulado em um json.

    ```
<filter oci.kafka>
@type record_transformer
enable_ruby true
<record>
    oci_la_metadata KEY_VALUE_PAIRS
    oci_la_entity_id LOGGING_ANALYTICS_ENTITY_OCID              # If same across sources. Else keep this in individual filters
    oci_la_entity_type LOGGING_ANALYTICS_ENTITY_TYPE            # If same across sources. Else keep this in individual filters
    oci_la_log_source_name LOGGING_ANALYTICS_SOURCENAME
    oci_la_log_group_id LOGGING_ANALYTICS_LOGGROUP_OCID
    oci_la_log_path "${record['tailed_path']}"
    message ${record["log"]}                            # Will assign the 'log' key value from json wrapped message to 'message' field
    tag ${tag}
</record>
</filter>
```

Os seguintes parâmetros opcionais podem ser incluídos no bloco de origem:

  • multiline_flush_interval: Defina esse valor somente para logs de várias linhas para garantir que todos os logs sejam consumidos pelo Log Analytics. Se o valor não for definido para logs de várias linhas, o Fluentd permanecerá no modo de espera para o próximo lote de registros. Por padrão, este parâmetro permanece desativado.
  • pos_file: Use esse parâmetro para especificar o arquivo no qual o Fluentd mantém o registro da posição que leu pela última vez.

Para obter informações sobre outros parâmetros, consulte Documentação do Fluentd: tail.

Configuração do Filtro

Use esses parâmetros para listar os recursos do Log Analytics que devem ser usados para processar seus logs.

Para garantir que os logs da sua origem de entrada possam ser processados pelo plug-in de saída fornecido pela Oracle, verifique se os eventos de log de entrada estão em conformidade com o formato prescrito, por exemplo, configurando o plug-in de filtro record_transformer para alterar o formato adequadamente.

Dica: Observe que a configuração do plug-in de filtro record_transformer é apenas uma das maneiras de incluir os parâmetros necessários nos eventos de entrada. Consulte a Documentação do Fluentd para obter outros métodos.

Exemplo de configuração de filtro:

    <filter oci.kafka>
    @type record_transformer
    enable_ruby true
    <record>
        oci_la_metadata KEY_VALUE_PAIRS
        oci_la_entity_id LOGGING_ANALYTICS_ENTITY_OCID              # If same across sources. Else keep this in individual filters
        oci_la_entity_type LOGGING_ANALYTICS_ENTITY_TYPE            # If same across sources. Else keep this in individual filters
        oci_la_log_source_name LOGGING_ANALYTICS_SOURCENAME
        oci_la_log_group_id LOGGING_ANALYTICS_LOGGROUP_OCID
        oci_la_log_path "${record['tailed_path']}"
        message ${record["log"]}                            # Will assign the 'log' key value from json wrapped message to 'message' field
        tag ${tag}
    </record>
    </filter>`

Forneça as seguintes informações obrigatórias no bloco de filtros:

  • <filter oci.kafka>: O parâmetro para definir um bloco de filtro para a tag especificada no bloco de origem.
  • @type record_transformer: O plug-in do transformador de registro transforma o registro de log original em um formulário que pode ser consumido pelo plug-in de saída do OCI Log Analytics.
  • enable_ruby: Permite o uso da expressão Ruby dentro de ${...}.
  • oci_la_entity_id: O OCID da Entidade do Log Analytics que você criou anteriormente na tarefa de pré-requisito para mapear seu host.
  • oci_la_entity_type: O tipo de entidade da Entidade do Log Analytics que você criou anteriormente na tarefa de pré-requisito.
  • oci_la_log_source_name: A Origem do Log Analytics que deve ser usada para processar os registros de log.
  • oci_la_log_path: Especifique o local original dos arquivos de log. Se o valor de oci_la_log_path não for privado ou for inválido, então:
    • se a tag estiver disponível, ela será usada como oci_la_log_path
    • se a tag não estiver disponível, oci_la_log_path será definido como UNDEFINED
  • oci_la_log_group_id: O OCID do Grupo de Logs do Log Analytics no qual os logs devem ser armazenados.

Opcionalmente, você pode fornecer os seguintes parâmetros adicionais no bloco de filtros:

  • <filter oci.**>: Use este filtro para fornecer as informações de configuração aplicáveis em todas as origens. Se você usar esse filtro, certifique-se de que ele esteja primeiro na ordem de execução entre os filtros. Se a mesma chave for especificada no filtro global e no filtro de origem individual, o valor do filtro de nível de origem substituirá o filtro global. É recomendável usar oci como prefixo para todas as tags.
  • oci_la_global_metadata: Use esse parâmetro para especificar metadados adicionais junto com o conteúdo de log original para o Log Analytics no formato 'key1': 'value1', 'key2': 'value2'. Aqui, Key é o Field do Log Analytics que já deve estar definido antes de especificá-lo aqui. Os metadados globais são aplicados a todos os arquivos de log.
  • oci_la_metadata: Use esse parâmetro para definir metadados adicionais junto com o conteúdo de log original para o Log Analytics no formato 'key1': 'value1', 'key2': 'value2'. Aqui, Key é o Field do Log Analytics que já deve estar definido antes de especificá-lo aqui.
  • tag: Use esse parâmetro para anexar uma tag à mensagem para uso interno. Especifique no formato tag ${tag}.
  • mensagem ${record["log"]}: Inclua este parâmetro para logs que são encapsulados em um encapsulador json em que a mensagem de log original é o valor do atributo log dentro do json.

Exemplos de configurações que você pode usar para monitorar os seguintes logs:

Instalar o Plug-in de Saída

Use o arquivo gem fornecido pela Oracle para a instalação do OCI Log Analytics Output Plugin. As etapas desta seção são para a configuração do Fluentd com base no pacote rpm td-agent instalado no Oracle Linux.

  1. Instale o plug-in de saída executando o seguinte comando:

    gem install fluent-plugin-oci-logging-analytics

Para obter mais informações, consulte Plug-in de Saída Fluentd para enviar logs/eventos para o OCI Log Analytics em RubyGems: https://rubygems.org/gems/fluent-plugin-oci-logging-analytics.

  1. Systemd inicia o td-agent com o usuário td-agent. Dê ao usuário td-agent o acesso aos arquivos e pastas do OCI. Para executar o td-agent como serviço, execute o comando chown ou chgrp para as pastas do plug-in de saída do OCI Log Analytics e o arquivo pem .OCI, por exemplo, chown td-agent [FILE].

  2. Para começar a coletar logs no Oracle Cloud Log Analytics, execute td-agent:

    TZ=utc /etc/init.d/td-agent start

    Você pode usar o arquivo de log /var/log/td-agent/td-agent.log para depurar se encontrar problemas durante a coleta de logs ou durante a configuração.

    Para interromper o td-agent em qualquer ponto, execute o seguinte comando:

    TZ=utc /etc/init.d/td-agent stop

Comece a Exibir os Logs no Log Analytics

Vá para o Log Explorer e use o painel Visualizar do Oracle Cloud Log Analytics para exibir os dados de log em um formulário que ajude a entender e analisar melhor. Com base no que deseja obter com seu conjunto de dados, você pode selecionar o tipo de visualização mais adequado ao seu aplicativo.

Depois de criar e executar uma consulta de pesquisa, você poderá salvar e compartilhar suas pesquisas de log como widget para reutilização posterior.

Você pode criar painéis de controle personalizados na página Painéis de Controle adicionando os widgets definidos pela Oracle ou os widgets personalizados que você criou.

Monitorar Fluentd usando Prometheus

Você pode opcionalmente monitorar o Fluentd usando o Prometheus. Para ver as etapas para expor as métricas abaixo e outras emitidas pelo Fluentd para o Prometheus, consulte Documentação do Fluentd: Monitoramento por Prometheus. Se você quiser monitorar apenas o Fluentd básico e essas métricas, ignore as etapas Etapa 1: Contando Registros de Entrada por Plug-in de Filtro Prometheus e Etapa 2: Contando Registros de Saída por Plug-in de Saída Prometheus na documentação Fluentd referida.

O plug-in Fluentd emite as seguintes métricas no formato Prometheus, que fornece insights sobre os dados coletados e processados pelo plug-in:

Metric Name: oci_la_fluentd_output_plugin_records_received 
labels: [:tag,:oci_la_log_group_id,:oci_la_log_source_name,:oci_la_log_set]
Description: Number of records received by the OCI Log Analytics Fluentd output plugin.
Type : Gauge

Metric Name: oci_la_fluentd_output_plugin_records_valid 
labels: [:tag,:oci_la_log_group_id,:oci_la_log_source_name,:oci_la_log_set]
Description: Number of valid records received by the OCI Log Analytics Fluentd output plugin.
Type : Gauge 

Metric Name: oci_la_fluentd_output_plugin_records_invalid 
labels: [:tag,:oci_la_log_group_id,:oci_la_log_source_name,:oci_la_log_set,:reason]
Description: Number of invalid records received by the OCI Log Analytics Fluentd output plugin. 
Type : Gauge

Metric Name: oci_la_fluentd_output_plugin_records_post_error 
labels: [:tag,:oci_la_log_group_id,:oci_la_log_source_name,:oci_la_log_set,:error_code, :reason]
Description: Number of records failed posting to OCI Log Analytics by the Fluentd output plugin.
Type : Gauge
    
Metric Name: oci_la_fluentd_output_plugin_records_post_success 
labels: [:tag,:oci_la_log_group_id,:oci_la_log_source_name,:oci_la_log_set]
Description: Number of records posted by the OCI Log Analytics Fluentd output plugin. 
Type : Gauge  

Metric Name: oci_la_fluentd_output_plugin_chunk_time_to_receive
labels: [:tag]
Description: Average time taken by Fluentd to deliver the collected records from Input plugin to OCI Log Analytics output plugin.
Type : Histogram  

Metric Name: oci_la_fluentd_output_plugin_chunk_time_to_post 
labels: [:oci_la_log_group_id]
Description: Average time taken for posting the received records to OCI Log Analytics by the Fluentd output plugin.
Type : Histogram

Saiba Mais

Outros Recursos de Aprendizagem

Explore outros tutoriais sobre o Oracle Learn ou acesse mais conteúdo de aprendizado gratuito no canal do Oracle Learning YouTube. Além disso, acesse o Oracle Education para se tornar um Oracle Learning Explorer.

Para obter a documentação do produto, visite o Oracle Help Center.