Documentation

12. ロギングおよびアグリゲーション

ロギングは、複数の種類のサードパーティーの外部ログアグリゲーションサービスに詳細なログを送信できる機能です。このデータフィードに接続されるサービスは、コントローラーの使用状況や技術的な傾向の見解を得るための便利な手段として機能します。このデータは、インフラストラクチャー内のイベントの分析、異常な点がないかの監視、サービス別のイベントの相関確認に使用できます。コントローラーで最も便利なデータのタイプは、ジョブファクトデータ、ジョブイベント/ジョブラン、アクティビティーストリームデータ、およびログメッセージです。これらのデータは、最小限のサービス固有の微調整をカスタムハンドラーに加えるか、インポートしたライブラリーを使用し、JSON 形式で HTTP 接続で送信されます。

automation controller をインストールすると、rsyslog の新しいバージョンをインストールし、RHEL ベースで提供されるバージョンに置き換わります。automation controller によりインストールされる rsyslog のバージョンには、以下の rsyslog モジュールが含まれていません。

  • rsyslog-udpspoof.x86_64

  • rsyslog-libdbi.x86_64

automation controller のインストール後、RHEL が提供する rsyslog パッケージで実行されていた可能性があるコントローラー外のロギングには、コントローラーが提供した rsyslog パッケージのみを使用してください。コントローラーインスタンスでシステムログを記録するために rsyslog をすでに使用している場合は、別の rsyslog プロセスを実行して (コントローラーが同一バージョンの rsyslog を使用)、別の /etc/rsyslog.conf を指定することで、引き続き rsyslog を使用してコントローラーの外部からのログを処理します。

注釈

コントローラー (コントローラー仮想マシン/マシン上) 外で rsyslog を使用するシステムの場合は、コントローラーに付属の rsyslog の新しいバージョンでも発生する可能性がある競合を考慮してください。

/api/v2/settings/logging/ エンドポイントから、外部ロガーがオフラインになった場合に、コントローラーの rsyslog プロセスで送信されていないメッセージを処理する方法を設定できます。

  • LOG_AGGREGATOR_MAX_DISK_USAGE_GB: 外部ログアグリゲーターの停止中に保存するデータ容量 (GB、デフォルトは 1)。rsyslogd queue.maxdiskspace 設定と同じです。

  • LOG_AGGREGATOR_MAX_DISK_USAGE_PATH: 外部ログアグリゲーターが停止した後に再試行する必要のあるログを永続化する場所 (デフォルト: /var/lib/awx)。rsyslogd queue.spoolDirectory の設定と同じです。

たとえば、Splunk がオフラインになると、rsyslogd は Splunk がオンラインになるまでキューをディスクに保存します。デフォルトでは、(Splunk がオフラインの場合に) 最大 1GB のイベントを保存しますが、必要に応じて 1GB を超える値を設定したり、キューを保存するパスを変更できます。

12.1. ロガー

以下は、予測可能な構造または半構造化形式で大量の情報を提供する特別なロガー (汎用的なサーバーログで構成される awx は除く) です。これらは、API からのデータを取得するときの構造と同じ形式を取ります。

  • job_events: Ansible コールバックモジュールから返されるデータを渡します。

  • activity_stream: automation controller アプリケーション内のオブジェクトに対する変更記録を表示します。

  • system_tracking: ジョブテンプレートを Enable Fact Cache を選択して実行する際に Ansible setup モジュール (つまり gather_facts: True) によって収集されるファクトデータを提供します。

  • awx: ファイルに通常記述されるログなど、汎用的なサーバーログを渡します。これには、全ログが持つ標準メタデータが含まれます (ただし、このログにはログステートメントからのメッセージだけが含まれます)。

これらのロガーは、ログレベルが INFO のものだけを使用します。例外は、awx ロガーで、これはどのレベルでも使用できます。

さらに、標準のコントローラーログは、これと同じメカニズムで提供可能です。ローカルの設定ファイルで複雑なディクショナリーを操作せずに 5 つの各データソースを有効または無効にする方法や、標準のコントローラーログから使用するログレベルを調節する方法は、すぐに分かります。

automation controller でさまざまなロギングコンポーネントを設定するには、左側のナビゲーションバーから 設定 をクリックし、システムオプションの一覧から ロギング設定 を選択します。

12.1.1. ログメッセージスキーマ

全ロガーに対する共通のスキーマ

  • cluster_host_id: コントローラークラスターにあるホストの一意識別子

  • level: 標準の Python ログレベル。イベントの重大度をほぼ反映します。この機能に含まれるデータロガーはすべて INFO レベルを使用しますが、コントローラーログは随時、異なるレベルを使用します。

  • logger_name: "activity_stream" など、設定で使用するロガー名

  • @timestamp: ログの時間

  • path: ログが生成されたコードのファイルパス

12.1.2. アクティビティーストリームスキーマ

  • (common): これは、上記の全ロガーに共通するフィールドすべてを使用します。

  • actor: ログに記述されたアクションを行ったユーザーのユーザー名

  • changes: 変更されたフィールド、以前/新規の概要 (JSON)

  • operation: "associate" など、アクティビティーストリームにログ記録された変更の基本カテゴリー

  • object1: 操作を行うプライマリーオブジェクトに関する情報。アクティビティーストリームに表示する内容と一貫性があります。

  • object2: 該当する場合には、アクションに関連する 2 つ目のオブジェクト

12.1.3. ジョブイベントのスキーマ

このロガーは、想定されるロガーからの標準フィールドと矛盾してしまう場合 (このような場合はこれらのフィールドはネス化されます) を除き、ジョブイベントに保存されるデータを反映します。特に、job_event モデルのフィールドホストは、event_host とされます。プレイロード内には event_data というサブディクショナリーフィールドもあり、これには、Ansible イベントの内容によっては含まれるフィールドが異なります。

このロガーには、以下の共通のフィールドが含まれます。

12.1.4. スキャン/ファクト/システム追跡データスキーマ

これらには、サービス、パッケージまたはファイルの詳細ディクショナリータイプフィールドが含まれます。

  • (common): これは、上記の全ロガーに共通するフィールドすべてを使用します。

  • services: サービススキャンの場合は、このフィールドが含まれ、このフィールドにはサービス名をもとにしたキーがあります。注記: 名前の Elastic Search ではピリオドは使用できず、ログフォーマッターにより "_" に置き換えられます

  • package: パッケージスキャンからのログメッセージに含まれます

  • files: ファイルスキャンからのログメッセージに含まれます

  • host: 適用されるホストスキャン名

  • inventory_id: 含まれるインベントリー id ホスト

12.1.5. ジョブステータスの変更

これは、ジョブイベントに比べ、ジョブの状態の変更に関する情報源は少量とし、ジョブテンプレートをベースとするジョブ以外で、統合されたジョブタイプに対する変更を取得することが目的です。

共通のフィールドに加え、これらのログには、ジョブモデルに表示されるフィールドも含まれます。

12.1.6. コントローラーのログ

一般的なフィールドのほかに、これにはログメッセージを含む msg フィールドが含まれます。エラーには別の traceback フィールドが含まれます。これらのログは、ロギング設定ページから ENABLE EXTERNAL LOGGING オプションで有効または無効にできます。

12.1.7. ログアグリゲーターサービス

ログアグリゲーターサービスは、以下の監視またはデータ分析システムと連携します。

12.1.7.1. Splunk

Automation controller の Splunk ロギング統合では、Splunk HTTP Collector を使用します。SPLUNK ログアグリゲーターを設定する場合は、以下のように、HTTP Event Collector ホストに完全 URL を追加します。

https://yourcontrollerfqdn.com/api/v2/settings/logging

{
    "LOG_AGGREGATOR_HOST": "https://yoursplunk:8088/services/collector/event",
    "LOG_AGGREGATOR_PORT": null,
    "LOG_AGGREGATOR_TYPE": "splunk",
    "LOG_AGGREGATOR_USERNAME": "",
    "LOG_AGGREGATOR_PASSWORD": "$encrypted$",
    "LOG_AGGREGATOR_LOGGERS": [
        "awx",
        "activity_stream",
        "job_events",
        "system_tracking"
    ],
    "LOG_AGGREGATOR_INDIVIDUAL_FACTS": false,
    "LOG_AGGREGATOR_ENABLED": true,
    "LOG_AGGREGATOR_CONTROLLER_UUID": ""
}

Splunk HTTP Event Collector はデフォルトで 8088 をリッスンし、受信要求を適切に処理するために完全 HEC イベント URL (ポートを使用) を提供する必要があります。この値は、以下の例に入力されます。

_images/logging-splunk-tower-example.png

HTTP Event Collector の設定方法は Splunk documentation を参照してください。

12.1.7.2. Loggly

Loggly の HTTP エンドポイント経由でのログの送信を設定するには、https://www.loggly.com/docs/http-endpoint/ を参照してください。Loggly は、http://logs-01.loggly.com/inputs/TOKEN/tag/http/ に記載の URL 規則を使用します。これは、以下の例の ログアグリゲーター フィールドに入力して紹介しています。

_images/logging-loggly-tower-example.png

12.1.7.3. Sumologic

Sumologic では、json ファイルに含まれる検索基準を作成します。json ファイルには、必要なデータを収集するのに使用するパラメーターが指定されています。

_images/logging_sumologic_main.png

12.1.7.4. Elastic stack (以前の ELK stack)

ゼロの状態から独自の Elastic Stack バージョンを開始する場合は、変更の必要があるのは、logstash logstash.conf ファイルに以下の行を追加するだけです。

filter {
  json {
    source => "message"
  }
}

注釈

後方互換性の変更が Elastic 5.0.0 で導入され、使用するバージョンによっては、異なる設定が必要になる可能性があります。

12.2. ロギングの設定

いずれかのアグリゲータータイプにロギングを設定する方法:

  1. 左側のナビゲーションバーで 設定 をクリックします。

  2. システムオプションの一覧で、ロギング設定 を選択します。

  3. ロギング設定画面下部で、編集 をクリックします。

  4. 表示されたフィールドで設定可能なオプションを設定します。

  • 外部ログの有効化: 外部のログアグリゲーターにログを送信するには、切り替えボタンをクリックして ON にします。

  • ログアグリゲーター: ログを送信するホスト名または IP アドレスを入力します。

  • ログアグリゲーターポート: 必要な場合には、アグリゲーターポートを指定します。

注釈

接続タイプが HTTPS の場合は、URL にポート番号が付いたホスト名を入力します。そのため、再度ポートを入力する必要はありません。ただし、TCP や UDP 接続は、URL ではなく、ホスト名とポート番号の組み合わせで判断されるため、TCP/UDP 接続の場合は、指定のフィールドにポートを入力してください。URL がホストフィールド (ログアグリゲーター フィールド) に入力された場合には、実際のホスト名としてホスト名の部分が抽出されます。

  • ログアグリゲータータイプ: クリックして、ドロップダウンメニューからアグリゲーターサービスを選択します。

_images/configure-tower-system-logging-types.png
  • ログアグリゲーターユーザー名: 必要な場合には、ログアグリゲーターのユーザー名を入力します。

  • ログアグリゲーターパスワード/トークン: 必要な場合にはログアグリゲーターのパスワードを入力します。

  • ログアグリゲーターフォームにデータを送信するロガー: デフォルトでは、データ 4 種類すべてが事前投入されています。各データタイプに関する追加情報は、フィールドの横にあるヒント help アイコンをクリックします。必要がなくなればデータタイプを削除してください。

  • ログシステムによるファクトの個別トラッキング: オンに切り替えるか、デフォルトのままオフにしておくかなど、追加情報を確認するにはヒント help アイコンをクリックします。

  • ログアグリゲーターのプロトコル: ログアグリゲーターと通信する接続タイプ (プロトコル) を選択するにはこれをクリックします。今後表示されるオプションは、選択したオプションにより異なります。

  • TCP 接続のタイムアウト: 接続のタイムアウトを秒単位で指定します。このオプションは、HTTP と TCP ログアグリゲータープロトコルにのみ適用されます。

  • ログアグリゲーターレベルのしきい値: ログハンドラーがレポートする重大度レベルを選択します。

  • HTTPS 証明書の検証を有効化/無効化: デフォルトでは、HTTPS ログプロトコルに対する証明書の検証は有効です。接続の確立前に、外部ログアグリゲーターが送信した HTTPS 証明書をログハンドラーに検証させないようにするには、ボタンを OFF に切り替えます。

  1. 選択したログアグリゲーションの内容を確認します。以下は、Splunk 用に設定した一例です。

_images/configure-tower-system-logging-splunk-example.png
  1. 完了したら、保存 をクリックして設定を適用するか、キャンセル をクリックして変更を破棄します。

  2. 設定が正しく設定されていることを確認するには、まず Save をクリックしてから Test をクリックします。これにより、automation controller における現在のロギング設定を使用してテストログメッセージがログアグリゲーターに送信されます。このテストメッセージを外部ログアグリゲーターが確実に受け取っていることを確認してください。

注釈

Test ボタンが無効になっている場合は、フィールドが初期値とは異なることを示しています。したがって、最初に変更を保存して Enable External Logging トグルボタンを ON に設定してください。

12.3. ロギングのトラブルシューティング

テストボタンのあるメッセージを http/https で設定したロギングサービスに送信し、メッセージを受信しなかった場合は、/var/log/tower/rsyslog.err ログファイルを確認してください。これは、rsyslog を http/https の外部ロギングサービスで認証する際に発生した場合にエラーが保存されます。エラーがない場合には、このファイルが存在しないことに注意してください。