イントロダクション

オープン・ソースのデータ収集ソフトウェアであるFluentdを使用して、ソースからログ・データを収集します。OCI Log Analytics出力プラグインをインストールして、収集したログ・データをOracle Cloud Log Analyticsにルーティングします

ノート: Oracleでは、Oracle Cloud Log Analyticsにログ・データを取り込む最良の経験を得るために、Oracle Cloud Management Agentを使用することをお薦めします。ただし、ユース・ケースではこれを指定できない場合は、FluentdのOCI Log Analytics出力プラグインを使用します。

このチュートリアルでは、Oracle Linuxにインストールされているtd-agent rpmパッケージに基づくFluentdセットアップを使用しますが、必要なステップはFluentdの他のディストリビューションに似ている可能性があります。

Fluentdには、入力ソースからログ・データを収集し、ログを変換し、ログ・データを目的の出力にルーティングするために連携するコンポーネントがあります。様々なソースからOracle Cloud Log Analyticsにログを取り込むために、Fluentdの出力プラグインをインストールおよび構成できます。

図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を使用してプラグインバージョン1.xをインストールした場合は、プラグインバージョン2.xに移行するために行う必要がある変更があることに注意してください。

バージョン2.xでは、次の構成パラメータの名前が変更されました。

1.x	2.x
global_metadata	oci_la_global_metadata
メタデータ(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_log_rotationは非推奨になりました。かわりに、パラメータplugin_log_file_sizeおよびplugin_log_file_countを組み合せて使用して、同じアクションを実行します。
• 「出力プラグインのインストール」の項にあるコマンドを使用して、プラグインバージョン2.xをインストールします。

前提条件の実行

• Fluentdおよび入力プラグインのインストール: 次のステップを実行する前に、Fluentdおよび入力ソースに関連する入力プラグインがインストールされていることを確認してください。

  Fluentd Documentationを参照してください。

• キー・リソースの階層の理解: エンティティ、ソースおよびパーサーは、ログ収集の設定に使用されるOracle Cloud Log Analyticsのキー・リソースの一部です。ログ・エクスプローラでログの表示を開始する前に、前提条件タスクを実行するための相互依存性を理解してください。

  Log Analyticsのドキュメンテーション: Log Analyticsについてを参照してください。

• Log Analyticsの有効化: Log Analyticsドキュメント: クイック・スタート。エンティティのOCIDとタイプ、および後の項で使用するログ・グループのOCIDを書き留めます。

• ソースおよびパーサーの作成: 後の項でエンティティに関連付けるために構成で指定する必要がある、既存のOracle定義またはユーザー定義のソースおよびパーサーを識別します。または、ユースケースに合せて独自のパーサーおよびソースを作成できます。

  Log Analyticsドキュメント: パーサーの作成およびLog Analyticsドキュメント: ソースの構成を参照してください。

• マルチ・プロセス・ワーカー機能: トラフィックが増えると、Fluentdはより多くのCPUバウンドになる傾向があります。このような場合は、複数就業者機能の使用を検討してください。

  Fluentdドキュメント: Multi Process WorkersおよびFluentd Documentation: Performance Tuningを参照してください。

• 認証: OCIに接続するには、OCIコンソールから作成できるAPI署名キーが必要です。

  OCIドキュメント: API署名キーの生成方法を参照してください。

Fluentd構成ファイルの作成

Oracle Cloud Log Analyticsにログ・データをルーティングするようにFluentdを構成するには、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 (必須パラメータ)	収集されたログ・データのアップロード先となる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	出力プラグインのログレベル: DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN.デフォルト値: INFO。
plugin_log_rotation	(非推奨)出力プラグイン・ログ・ファイルのローテーション頻度: 日次、週次または月次。デフォルト値: daily。
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。推奨値: block。
disable_chunk_backup	false	falseを指定すると、バックアップディレクトリ内の回復不能なチャンクは破棄されます。
chunk_limit_size	8MB	各チャンクの最大サイズ。チャンクのサイズがこのサイズになるまで、イベントはチャンクに書き込まれます。ノート: 指定した値に関係なく、Log Analytics出力プラグインでは現在、値が1MBにデフォルト設定されています。
total_limit_size	64GB (ファイル用)	ストアド・バッファの合計サイズがこのしきい値に達すると、すべての追加操作がエラーで失敗します(データは失われます)。
flush_interval	60s	出力プラグインへのチャンクのフラッシュの頻度。

パラメータに指定可能な値の詳細は、Fluentdドキュメント: バッファ・プラグインを参照してください。

受信ログ・イベントの形式の確認

Oracleが提供するFluentdプラグインがログ・データを処理し、チャンク化して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: 入力プラグイン・タイプ。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_transformerフィルタのメッセージ・フィールドを値${record["log"]}でオーバーライドします。

  ノート:

  • Fluentdパーサーを使用しないことをお薦めします。かわりに、ログを元の形式でLog Analyticsに送信します。解析ディレクティブは次の形式である必要があります。

    <parse>
        @type none
    </parse>
    

  • ただし、複数行ログ・エントリの場合は、複数行パーサー・タイプを使用して、1つのログの複数行を1つのレコードとして送信します。たとえば:

    <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が提供する出力プラグインで処理できるようにするには、たとえば、record_transformerフィルタ・プラグインを構成してフォーマットを適宜変更することによって、入力ログ・イベントが所定のフォーマットに準拠していることを確認します。

ヒント: record_transformerフィルタ・プラグインの構成は、受信イベントに必須パラメータを含める方法の1つのみであることに注意してください。その他の方法については、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: このパラメータを使用して、Log Analyticsへの元のログ・コンテンツとともに'key1': 'value1', 'key2': 'value2'の形式で追加のメタデータを指定します。ここで、キーは、ここで指定する前にすでに定義しておく必要があるLog Analyticsフィールドです。グローバル・メタデータは、すべてのログ・ファイルに適用されます。
• oci_la_metadata: このパラメータを使用して、Log Analyticsへの元のログ・コンテンツとともに追加のメタデータを'key1': 'value1', 'key2': 'value2'の形式で定義します。ここで、キーは、ここで指定する前にすでに定義しておく必要があるLog Analyticsフィールドです。
• tag: このパラメータを使用して、内部使用のためにタグをメッセージに添付します。tag ${tag}の形式で指定します。
• メッセージ${record["log"]}: jsonラッパーにラップされるログにこのパラメータを含めます。元のログ・メッセージはjson内のlog属性の値です。

次のログの監視に使用できる構成の例:

• Syslogログ
• Apacheエラー・ログ
• Kafkaログ

出力プラグインのインストール

OCI Log Analytics出力プラグインのインストールには、Oracleが提供するgemファイルを使用します。この項のステップは、Oracle Linuxにインストールされているtd-agent rpmパッケージに基づくFluentdの設定用です。

1. 次のコマンドを実行して、出力プラグインをインストールします。

   gem install fluent-plugin-oci-logging-analytics
   

詳細は、RubyGems(https://rubygems.org/gems/fluent-plugin-oci-logging-analytics)のログ/イベントをOCI Log Analyticsに出荷するためのFluentd出力プラグインを参照してください。

1. Systemdは、td-agentユーザーを使用してtd-agentを起動します。OCIファイルおよびフォルダへのアクセス権をtd-agentユーザーに付与します。td-agentをサービスとして実行するには、OCI Log Analytics出力プラグイン・フォルダの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ドキュメント: 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

さらに学ぶ

• Fluentdのドキュメント
• Log Analyticsドキュメント: チャートおよびコントロールを使用したデータのビジュアル化
• Log Analyticsドキュメント: ダッシュボードの作成
• Log Analyticsドキュメント: ログ検索の保存と共有

その他の学習リソース

Oracle Learnで他のチュートリアルを探すか、Oracle Learning YouTubeチャネルで無料のラーニング・コンテンツにアクセスしてください。また、Oracle Educationにアクセスし、Oracle Learning Explorerとなります。

製品ドキュメントについては、Oracle Help Centerを参照してください。

---

タイトルおよび著作権情報

Ingest Logs to OCI Log Analytics Using Fluentd

F51439-05

2025年7月

Copyright ©2025,

Oracle and/or its affiliates.