ノート:

Fluentdを使用したOCIログ・アナリティクスへのログの収集

イントロダクション

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

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

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

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

図fluentd_plugin_overview.pngの説明

目的

OCIロギング・アナリティクス出力プラグインのバージョン1.xから2.xへの移行

OCIロギング・アナリティクス出力プラグインの新しいユーザーで、まだダウンロードしてインストールしていない場合は、このサブセクションをスキップして前提条件に進みます。ファイル fluent-plugin-oci-logging-analytics-1.0.0.gemを使用してプラグイン version 1.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

前提条件

Fluentd構成ファイルの作成

Oracle Cloud Logging Analyticsにログ・データをルーティングするようにFluentdを構成するには、Fluentdまたはtd- agentが提供する構成ファイルを編集し、Oracle Cloud Logging 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: Second 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 なし これは、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 各チャンクの最大サイズ。イベントは、チャンクのサイズがこのサイズになるまでチャンクに書き込まれます。ノート: 指定した値に関係なく、現在ロギング・アナリティクス出力プラグインでは値が1MBにデフォルト設定されます。
total_limit_size 64GB (ファイル用) ストアド・バッファの合計サイズがこのしきい値に達すると、追加操作はすべてエラーで失敗し、データは失われます。
flush_interval 60s 出力プラグインへのチャンクのフラッシュの頻度。

パラメータの可能な値の詳細は、Fluentd Documentation: Buffer Pluginsを参照してください。

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

Oracleが提供するFluentdプラグインがログ・データを処理し、チャンク化してOracle Cloud Logging 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>

ソース・ブロックを定義するには、次のパラメータが必須です。

次のオプション・パラメータをソース・ブロックに含めることができます。

その他のパラメータについては、Fluentd Documentation: tailを参照してください。

フィルタ構成

これらのパラメータを使用して、ログの処理に使用するロギング・アナリティクス・リソースをリストします。

入力ソースからのログが Oracleによって提供される出力プラグインによって処理されるようにするには、record_transformerフィルタプラグインを構成して、それに応じて形式を変更することによって、入力ログイベントが規定された形式に準拠していることを確認します。

ヒント: record_transformerフィルタプラグインの構成は、受信イベントに必要なパラメータを含める方法の1つにすぎません。その他の方法については、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>`

フィルタ・ブロックに次の必須情報を指定します。

オプションで、フィルタ・ブロックに次の追加パラメータを指定できます。

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

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

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

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

    gem install fluent-plugin-oci-logging-analytics

詳細は、RubyGems: https://rubygems.org/gems/fluent-plugin-oci-logging-analyticsのFluentd Output plugin to Ship log/events to OCI Logging Analyticsを参照してください。

  1. Systemdは、td- agentユーザーでtd- agentを起動します。td- agentユーザーにOCIファイルおよびフォルダへのアクセス権を付与します。td- agentをサービスとして実行するには、OCIロギング・アナリティクス出力プラグイン・フォルダおよび.OCI pemファイル(chown td-agent [FILE]など)に対してchownまたはchgrpコマンドを実行します。

  2. Oracle Cloud Logging 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

ログ・アナリティクスのログの表示の開始

「ログ・エクスプローラ」に移動し、Oracle Cloud Logging 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 Logging 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 Logging 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 Logging 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 Logging 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 Logging 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 Logging 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 Logging Analytics by the Fluentd output plugin.
Type : Histogram

さらに学ぶ

その他の学習リソース

他のラボをdocs.oracle.com/learnで探すか、Oracle LearningのYouTubeチャネルでより無料の学習コンテンツにアクセスします。また、education.oracle.com/learning-explorerにアクセスしてOracle Learningエクスプローラになります。

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