簡介

使用開放原始碼資料收集器軟體 Fluentd 從您的來源收集日誌資料。安裝 OCI Log Analytics 輸出 Plugin，將收集的日誌資料遞送至 Oracle Cloud Log Analytics。

注意：Oracle 建議您使用 Oracle Cloud Management Agent 來獲得將日誌資料擷取至 Oracle Cloud Log Analytics 的最佳體驗。不過，如果無法為您的使用案例選擇此選項，則僅使用適用於 Fluentd 的 OCI Log Analytics 輸出外掛程式。

在本教學課程中，Fluentd 設定是根據 Oracle Linux 上安裝的 td-agent rpm 套裝軟體所使用，但所需步驟可能與 Fluentd 的其他發行版本類似。

Fluentd 具有可共同運作的元件，可收集來自輸入來源的日誌資料、轉換日誌，以及將日誌資料遞送至所需的輸出。您可以安裝並設定 Fluentd 的輸出 Plugin，以從各種來源將日誌攝取至 Oracle Cloud Log Analytics。

圖解描述 fluentd_plugin_overview.png

目標

  • 瞭解如何安裝 Oracle 提供的 OCI Log Analytics 輸出外掛程式，以便從您的來源擷取日誌。
  • 建立 Fluentd 組態，以建立從來源到 Log Analytics 的日誌收集。

將 OCI Log Analytics 輸出 Plugin 從 1.x 版本移轉至 2.x

如果您是 OCI Log Analytics 輸出 Plugin 的新使用者，而且尚未下載並安裝，請略過此區段並前往先決條件。如果您已使用 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
中繼資料 oci_la_metadata
個體 ID 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 日誌。
  • 參數 plugin_log_rotation 現在已不再使用。請改用 plugin_log_file_size 和 plugin_log_file_count 參數來執行相同的動作。
  • 使用安裝輸出 Plugin 一節中可用的命令來安裝 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>

建議設定次要 Plugin，當輸出 Plugin 持續無法寫入緩衝區區塊且超過重試的逾時臨界值時，Fluentd 會使用此次要 Plugin 來傾印備份資料。此外，如果發生無法復原的錯誤，Fluentd 會立即中止區塊，並將它移到次要或備份目錄中。請參閱 Fluentd 文件：次要輸出。

輸出外掛程式設定參數

提供適合的值給 Fluentd 組態檔中的下列參數：

組態參數 描述
namespace ( 必要參數 ) 要上傳收集之日誌資料的 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 的檔案路徑。請確定路徑存在且可供存取。預設值：工作目錄。
plugin_log_level 輸出外掛程式紀錄等級 ：除錯 < 資訊中 < 警告 < 錯誤 < 嚴重 < 未知 。預設值：INFO 。
plugin_log_rotation (已棄用) 輸出 Plugin 日誌檔循環頻率：每日、每週或每月。預設值：每日。
plugin_log_file_size 要循環日誌檔的日誌檔大小上限。(1KB、1MB 等)。預設值：1 MB。
plugin_log_file_count 要保留的存檔 / 循環日誌檔數目 (大於 0)。預設值：10。

如果您未指定 OCI Compute 節點的參數 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。建議值：區塊。
disable_chunk_backup false 指定 false 時，將會捨棄備份目錄中無法復原的區塊。
chunk_limit_size 8MB 每個區塊的大小上限。這些事件會寫入區塊中，直到區塊大小變為此大小為止。注意：無論指定的值為何，Log Analytics 輸出 Plugin 目前會將值預設為 1MB。
total_limit_size 64GB (適用於檔案) 儲存的緩衝區大小總計達到此臨界值之後，所有附加作業都會因發生錯誤而失敗 (資料將會遺失)。
flush_interval 60s 將區塊排清至輸出 Plugin 的頻率。

如需參數可能值的詳細資料，請參閱 Fluentd 文件：緩衝區外掛程式。

驗證內送日誌事件的格式

內送日誌事件必須使用特定格式，Oracle 提供的 Fluentd Plugin 才能處理日誌資料、將日誌分塊，並將其傳輸至 Oracle Cloud Log Analytics。

在範例輸入組態中檢視可用於監督 syslog、apache 和 kafka 日誌檔的範例組態。

來源 / 輸入外掛程式設定

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>

下列參數是定義來源區塊的必要參數：

  • @type ：輸入 Plugin 類型。使用尾部來使用本機檔案的事件。其他可能的值可以是 http 、 forward 。

  • path ：來源檔案的路徑。

  • tag ：Oracle Fluentd Plugin 將使用的標記，用來篩選 Log Analytics 必須使用的日誌事件。請確定使用前置碼 oci，例如 oci.syslog。

  • 剖析指令：建議您不要在組態檔中定義剖析指令。保留值 <parse> @type none </parse>。您可以改用 Log Analytics 提供的 Oracle 定義的剖析器和來源，也可以在 Log Analytics 中建立自己的剖析器和來源。對於包裝在 json 包裝函式中的日誌，請使用剖析指令 <parse> @type json </parse>。將 record_transformer 篩選中的訊息欄位覆寫為值 ${record["log"]}。

    注意：

    • 建議您不要使用任何 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>

    而且，將 record_transformer 篩選中的 message 欄位覆寫為 message ${record["log"]}。例如，在下列 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 提供的輸出 Plugin 可以處理您輸入來源的日誌，請確定輸入日誌事件符合指定的格式，例如設定 record_transformer 篩選 Plugin 來相應地更改格式。

提示：請注意，設定 record_transformer 篩選外掛程式只是其中一種在內送事件中包含必要參數的方式。如需其他方法，請參考 Fluentd 文件。

過濾器設定範例 ：

    <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 的原始日誌內容。在這裡，索引鍵是必須先定義的 Log Analytics 欄位，才能在此處指定。全域描述資料會套用至所有日誌檔。
  • oci_la_metadata ：使用此參數以 'key1': 'value1', 'key2': 'value2' 格式定義其他描述資料以及 Log Analytics 的原始日誌內容。在這裡，索引鍵是必須先定義的 Log Analytics 欄位，才能在此處指定。
  • tag ：使用此參數將標記附加至訊息供內部使用。指定格式為 tag ${tag}。
  • 訊息 ${record["log"]} ：在 json 包裝程式中包裝的日誌包含此參數，其中原始日誌訊息是 json 內 log 屬性的值。

可用於監督下列日誌的組態範例：

安裝輸出外掛程式

使用 Oracle 提供的 gem 檔案來安裝 OCI Log Analytics 輸出 Plugin。本節中的步驟適用於以 Oracle Linux 上安裝的 td-agent rpm 套裝軟體為基礎的 Fluentd 設定。

  1. 執行下列指令來安裝輸出外掛程式：

    gem install fluent-plugin-oci-logging-analytics

如需詳細資訊，請參閱 RubyGems 上的 Fluentd 輸出外掛程式，將日誌 / 事件傳送至 OCI Log Analytics ：https://rubygems.org/gems/fluent-plugin-oci-logging-analytics 。

  1. Systemd 會以 td-agent 使用者啟動 td-agent。讓 td-agent 使用者能夠存取 OCI 檔案與資料夾。若要以服務形式執行 td-agent，請執行 OCI Log Analytics 輸出 Plugin 資料夾的 chown 或 chgrp 命令，以及 .OCI pem 檔案 (例如 chown td-agent [FILE])。

  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 篩選 Plugin 計算內送記錄和步驟 2：依 Prometheus 輸出 Plugin 計算外送記錄步驟。

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 教育訓練，成為 Oracle Learning Explorer。

如需產品文件，請造訪 Oracle Help Center 。