简介

使用开源数据收集器软件 Fluentd 从源收集日志数据。安装 OCI Log Analytics 输出插件以将收集的日志数据路由到 Oracle Cloud Log Analytics。

注：Oracle 建议您使用 Oracle Cloud Management Agents，以获得将日志数据摄取到 Oracle Cloud Log Analytics 的最佳体验。但是，如果这对您的用例来说不是可能的选项，则仅使用 OCI Log Analytics Output Plugin for Fluentd。

在本教程中，使用 Fluentd 设置，该设置基于 Oracle Linux 上安装的 td-agent rpm 软件包，但对于 Fluentd 的其他发行版，所需的步骤可能类似。

Fluentd 具有组件，这些组件可以协同工作，从输入源收集日志数据，转换日志，并将日志数据路由到所需的输出。您可以安装和配置 Fluentd 的输出插件，以便从各种源摄取日志到 Oracle Cloud Log Analytics。

插图 fluentd_plugin_overview.png 的说明

目标

  • 了解如何安装 Oracle 提供的 OCI Log Analytics 输出插件以从源摄取日志。
  • 创建 Fluentd 配置以建立从源到 Log Analytics 的日志收集。

将 OCI Log Analytics 输出插件从版本 1.x 迁移到 2.x

如果您是 OCI Log Analytics 输出插件的新用户，并且尚未下载并安装该插件，请跳过此部分并转至先决条件。如果已使用文件 fluent-plugin-oci-logging-analytics-1.0.0.gem 安装插件 version 1.x ，则请注意，迁移至插件 version 2.x 时可能需要进行更改。

以下配置参数在 version 2.x 中重命名：
1.x 2.x
global_metadata oci_la_global_metadata
metadata（元数据） 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
  • 添加了对自动清除 OCI Log Analytics 输出插件日志的支持。
  • 参数 plugin_log_rotation 现在已过时。而是将参数 plugin_log_file_size 和 plugin_log_file_count 结合使用来执行相同的操作。
  • 使用 Install the Output Plugin 一节中提供的命令安装插件 version 2.x 。

执行先决条件

创建 Fluentd 配置文件

要将 Fluentd 配置为将日志数据路由到 Oracle Cloud Log Analytics，请编辑 Fluentd 或 td-agent 提供的配置文件，并提供与 Oracle Cloud Log Analytics 及其他定制相关的信息。

Fluentd 输出插件配置将采用以下格式：

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

建议配置辅助插件，当输出插件在写入缓冲区块时继续失败并超过重试的超时阈值时，Fluentd 将使用该辅助插件转储备份数据。此外，对于不可恢复的错误，Fluentd 将立即中止块并将其移动到辅助目录或备份目录中。请参阅 Fluentd Documentation：Secondary Output 。

输出插件配置参数

在 Fluentd 配置文件中为以下参数提供合适的值：

配置参数 说明
namespace ( Mandatory parameter ) 要将收集的日志数据上载到的 OCI 租户名称空间
config_file_location 包含 OCI 验证详细信息的配置文件的位置
profile_name 要从配置文件使用的 OCI 配置概要信息名称
http_proxy 代理，无凭证。示例：www.proxy.com:80
proxy_ip 需要身份证明时代理 IP 详细信息。示例：www.proxy.com
proxy_port 需要身份证明时代理端口详细信息。示例 ： 80
proxy_username 代理用户名详细信息
proxy_password 需要身份证明时代理密码详细信息
plugin_log_location 输出插件用于写入其自己的日志的文件路径。确保路径存在且可访问。默认值：工作目录。
plugin_log_level 输出插件日志记录级别：调试 < 信息 < 警告 < 错误 < 致命 < 未知。默认值：INFO 。
plugin_log_rotation (DEPRECATED) 输出插件日志文件轮转频率：每日、每周或每月。默认值：每日。
plugin_log_file_size 滚动日志文件时的最大日志文件大小。”（1KB、1MB 等）。默认值：1MB。
plugin_log_file_count 要保留的归档/旋转日志文件数（大于 0）。默认值：10。

如果不为 OCI 计算节点指定参数 config_file_location 和 profile_name ，则使用基于 instance_principal 的验证。

缓冲区配置参数

在上一节中编辑的同一配置文件中，修改缓冲区部分并提供以下必需信息：

必备参数 说明
@type 这指定要用作后端的插件。输入 file 。
路径 存储缓冲区文件的路径。确保路径存在且可访问。

缓冲区块中可以包括以下可选参数：

可选的参数 默认值 说明
flush_thread_count 1 要并行刷新/写入块的线程数。
retry_wait 1s 在下次重试刷新之前等待几秒钟。
retry_max_times none 仅当 retry_forever 字段为 false 时，这是必需的。
retry_exponential_backoff_base 2 在下一个指数回退常数因子之前等待数秒。
retry_forever false 如果为 true ，则插件将忽略 retry_max_times 选项并永远重试刷新。
overflow_action throw_exception 可能的值：throw_exception / block / drop_oldest_chunk。Recommended Value：block 。
disable_chunk_backup false 指定 false 时，将放弃备份目录中不可恢复的块。
chunk_limit_size 8MB 每个块的最大大小。事件将写入块中，直到块的大小变为此大小。注：无论指定的值是什么，Log Analytics 输出插件当前都将值默认为 1MB。
total_limit_size 64GB（用于文件） 一旦存储缓冲区的总大小达到此阈值，所有附加操作都将失败并显示错误（并且数据将丢失）。
flush_interval 60s 将块刷新到输出插件的频率。

有关参数可能值的详细信息，请参见 Fluentd Documentation：Buffer Plugins 。

验证传入日志事件的格式

传入日志事件必须采用特定格式，以便 Oracle 提供的 Fluentd 插件可以处理日志数据，将其分块并将其传输到 Oracle Cloud Log Analytics。

在 Example Input Configuration 中查看可用于监视 syslog、apache 和 kafka 日志文件的示例配置。

源/输入插件配置

系统日志日志的源配置示例：

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

必须使用以下参数来定义源块：

  • @type ：输入插件类型。使用 tail 以使用本地文件中的事件。其他可能的值可以是 http 、 forward 。

  • path ：源文件的路径。

  • tag ：Oracle Fluentd 插件将用于筛选必须由 Log Analytics 使用的日志事件的标记。确保使用前缀 oci，例如 oci.syslog。

  • 解析指令：建议不要在配置文件中定义解析指令。保留值 <parse> @type none </parse>。您可以改用 Log Analytics 提供的 Oracle 定义的语法分析器和源，或者在 Log Analytics 中创建自己的语法分析器和源。对于包裹在 json 包装器中的日志，请使用语法分析指令 <parse> @type json </parse>。使用值 ${record["log"]} 覆盖 record_transformer 过滤器中的消息字段。

    注：

    • 建议您不要使用任何 Fluentd 解析器。而应以原始形式将日志发送到 Log Analytics。语法分析指令必须采用以下格式：

      <parse>
    @type none
</parse>

    • 但是，对于多行日志条目，请使用多行语法分析器类型将多行日志作为单个记录发送。例如：

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

    • 对于由 json 包装器包装的原始日志（其中键 - 值对中的某个键为 log ），我们建议您使用以下语法分析指令：

      <parse>
    @type json
</parse>

    并且，使用 message ${record["log"]} 覆盖 record_transformer 过滤器中的 message 字段。例如，在 kafka 日志的以下过滤器块中，日志内容存储在包裹在 json 中的键 log 的值中。

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

源块中可以包含以下可选参数：

  • multiline_flush_interval ：仅为多行日志设置此值，以确保所有日志都由 Log Analytics 使用。如果没有为多行日志设置该值，则 Fluentd 将保持在等待模式下，等待下一批记录。默认情况下，此参数已禁用。
  • pos_file ：使用此参数指定 Fluentd 在其中维护其上次读取位置的记录的文件。

有关其他参数的信息，请参见 Fluentd Documentation：tail 。

筛选器配置

使用这些参数列出必须用于处理日志的 Log Analytics 资源。

要确保 Oracle 提供的输出插件可以处理来自输入源的日志，请验证输入日志事件是否符合规定的格式，例如，通过配置 record_transformer 筛选器插件来相应地更改格式。

提示：请注意，配置 record_transformer 过滤器插件只是将所需参数包括在传入事件中的方法之一。有关其他方法，请参阅 Fluentd Documentation 。

过滤器配置示例：

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

在筛选器块中提供以下必需信息：

  • <filter oci.kafka>：用于为源块中指定的标记定义过滤器块的参数。
  • @type record_transformer ：记录转换器插件将原始日志记录转换为 OCI Log Analytics 输出插件可以使用的表单。
  • enable_ruby ：这允许在 ${...} 中使用 Ruby 表达式。
  • oci_la_entity_id ：先前在用于映射主机的先决条件任务中创建的 Log Analytics 实体的 OCID。
  • oci_la_entity_type ：先前在先决条件任务中创建的 Log Analytics 实体的实体类型。
  • oci_la_log_source_name ：必须用于处理日志记录的 Log Analytics 源。
  • oci_la_log_path ：指定日志文件的原始位置。如果 oci_la_log_path 的值不是专用值或无效，则：
    • 如果 tag 可用，则将其用作 oci_la_log_path
    • 如果 tag 不可用，则 oci_la_log_path 设置为 UNDEFINED
  • oci_la_log_group_id ：必须存储日志的 Log Analytics 日志组的 OCID。

您可以选择在过滤器块中提供以下附加参数：

  • <filter oci.**>：使用此筛选器提供适用于所有源的配置信息。如果使用此筛选器，请确保它首先按筛选器之间的执行顺序排列。如果在全局筛选器和单个源筛选器中指定了相同的关键字，则源级别筛选器值将覆盖全局筛选器。建议使用 oci 作为所有标记的前缀。
  • oci_la_global_metadata ：使用此参数以 'key1': 'value1', 'key2': 'value2' 格式指定 Log Analytics 的附加元数据以及原始日志内容。此处， Key 是 Log Analytics Field ，必须先定义该字段，然后才能在此处指定它。全局元数据将应用于所有日志文件。
  • oci_la_metadata ：使用此参数以 'key1': 'value1', 'key2': 'value2' 格式定义 Log Analytics 的附加元数据以及原始日志内容。此处， Key 是 Log Analytics Field ，必须先定义该字段，然后才能在此处指定它。
  • tag ：使用此参数将标记附加到消息以供内部使用。以 tag ${tag} 格式指定。
  • 消息 $｛record［“log”］｝：在 json 包装器中包装的日志中包括此参数，其中原始日志消息是 json 内 log 属性的值。

可用于监视以下日志的配置示例：

安装输出插件

使用 Oracle 提供的 gem 文件安装 OCI Log Analytics 输出插件。本节中的步骤适用于基于 Oracle Linux 上安装的 td-agent rpm 软件包的 Fluentd 设置。

  1. 通过运行以下命令安装输出插件：

    gem install fluent-plugin-oci-logging-analytics

有关详细信息，请参阅 Fluentd Output plugin to ship logs/events to OCI Log Analytics ，网址为 RubyGems：https://rubygems.org/gems/fluent-plugin-oci-logging-analytics 。

  1. Systemd 使用 td-agent 用户启动 td-agent。为 td-agent 用户提供对 OCI 文件和文件夹的访问权限。要将 td-agent 作为服务运行，请对 OCI Log Analytics 输出插件文件夹和 .OCI pem 文件（例如 chown td-agent [FILE]）运行 chown 或 chgrp 命令。

  2. 要在 Oracle Cloud Log Analytics 中开始收集日志，请运行 td-agent：

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

    如果在日志收集期间或设置期间遇到问题，可以使用日志文件 /var/log/td-agent/td-agent.log 进行调试。

    要随时停止 td-agent，请运行以下命令：

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

开始在 Log Analytics 中查看日志

转到日志浏览器，然后使用 Oracle Cloud Log Analytics 的“可视化”面板查看表单中的日志数据，以帮助您更好地了解和分析。根据您希望通过数据集实现的目标，您可以选择最适合您应用的可视化类型。

创建和执行搜索查询后，您可以将日志搜索保存并共享为小部件以供进一步重用。

您可以通过添加 Oracle 定义的窗口部件或您创建的定制窗口部件，在“仪表盘”页面上创建定制仪表盘。

使用 Prometheus 监视 Fluentd

您可以使用 Prometheus 根据需要监视 Fluentd。有关将以下度量和 Fluentd 发出的其他度量暴露给 Prometheus 的步骤，请参见 Fluentd Documentation：Monitoring by Prometheus 。如果要仅监视核心 Fluentd 和这些度量，请跳过所引用的 Fluentd 文档中的步骤步骤 1：按 Prometheus 筛选器插件对传入记录进行计数和步骤 2：按 Prometheus 输出插件对传出记录进行计数。

Fluentd 插件以 Prometheus 格式发出以下度量，提供有关插件收集和处理的数据的洞察：

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

了解更多

其他学习资源

浏览 Oracle Learn 上的其他教程，或访问 Oracle Learning YouTube 频道上的更多免费学习内容。此外，请访问 Oracle Education ，成为 Oracle Learning Explorer。

有关产品文档，请访问 Oracle 帮助中心。