Documentation

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

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

11.1. ロガー

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

  • job_status: ジョブ、プロジェクト更新、インベントリー更新などのステータスの変更をまとめます。

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

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

  • system_tracking: スキャンジョブテンプレートが実行する Ansible スキャンで収集されるデータを渡します。

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

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

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

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)

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

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

注釈

後方互換性の変更が 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. 設定が正しく行われているかどうかを検証するには テスト をクリックします。これは、テストログメッセージを送信して、応答コードが OK であることを確認して、ロギングの設定を検証します。

  2. 完了したら、保存 をクリックして設定を適用するか、キャンセル をクリックして変更を破棄します。