Documentation

11. Tower のロギングおよびアグリゲーション

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

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

  • rsyslog-udpspoof.x86_64

  • rsyslog-libdbi.x86_64

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

注釈

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

/api/v2/settings/logging/ エンドポイントから、外部ロガーがオフラインになった場合に、Tower 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 を超える値を設定したり、キューを保存するパスを変更できます。

11.1. ロガー

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

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

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

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

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

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

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

Ansible Tower でさまざまなロギングコンポーネントを設定するには、左のナビゲーションバーの (settings) メニューから システム を選択します。

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

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

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

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

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

  • @timestamp: ログの時間

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

11.1.6. Tower ログ

共通のフィールド以外に、これには、ログメッセージなどの msg フィールドが含まれます。エラーには、別個の traceback フィールドが含まれます。これらのログは、Tower の設定ユーザーインターフェースの ENABLE EXTERNAL LOGGING の設定で有効化または無効化できます。

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

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

11.1.7.1. Splunk

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

https://yourtowerfqdn.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_TOWER_UUID": ""
}

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

_images/logging-splunk-tower-example.png

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

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

11.1.7.3. Sumologic

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

_images/logging_sumologic_main.png

11.1.7.4. Elastic stack (以前の ELK stack)

Standing up your own version the elastic stack requires no modification to the logstash logstash.conf file.

注釈

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

11.2. Tower でのロギングの設定

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

  1. 左のナビゲーションバーから設定 (settings) アイコンをクリックします。

  1. システム を選択します。

  2. システム画面で、ロギング タブを選択します。

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

  • 外部ログの有効化: 外部のログアグリゲーターにログを送信するには、切り替えボタンをクリックして 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 をクリックします。これにより、Ansible Tower における現在のロギング設定を使用してテストログメッセージがログアグリゲーターに送信されます。このテストメッセージを外部ログアグリゲーターが確実に受け取っていることを確認してください。

注釈

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

11.3. Tower でのロギングのトラブルシューティング

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