Envoy によるオブザーバビリティ

このドキュメントでは、Envoy プロキシのトレースとロギングを生成する方法について説明します。また、Cloud Trace と Cloud Logging に情報をエクスポートする方法についても説明します。

サービスメッシュを使用すると、サービスとの間のトラフィックを監視できるため、サービス自体のコードを変更することなく、優れたモニタリングとデバッグが可能になります。Traffic Director が使用するサイドカープロキシのアーキテクチャでは、プロキシは、リクエストを処理し必要なテレメトリー情報を提供するコンポーネントです。テレメトリー情報は、データ分析、アラート、トラブルシューティングなどの目的で使用するために、一元管理された場所に収集して保存する必要があります。

デモ設定

このドキュメントでは、次の構成を使用してトレースとロギングのデモを行います。

HTTP ポートでリッスンし、リクエストを処理した仮想マシン（VM）インスタンスのホスト名を返す単一のアプリケーション。図では、このアプリケーションは右上隅にあり、「HTTP service(s) (10.10.10.10:80)」というラベルが付いています。1 つ以上の VM がこのサービスを提供できます。
このサービスのコンシューマを実行している単一の Compute Engine VM。図では、「Demo Compute Engine VM」というラベルが付いています。
Traffic Director によってインストールされ構成された Envoy サイドカープロキシ。図では、「envoy」というラベルが付いています。
左側のボックス内に示されているサービスコンシューマアプリケーションは、10.10.10.10:80 で実行されている HTTP サービスのコンシューマです。

Envoy のロギングとモニタリングのデモアプリケーション。 — Envoy のロギングとモニタリングのデモアプリケーション（クリックして拡大）

以下の手順は、図の中の番号に対応しています。

Traffic Director は、Envoy プロキシを構成して次の処理を行います。
- 10.10.10.10:80 サービスのトラフィックを負荷分散します。
- このサービスに対して発行されたリクエストごとにアクセスログ情報を保存します。
- サービスのトレース情報を生成します。
コンシューマが 10.10.10.10 にリクエストを送信すると、サイドカープロキシはリクエストを正しい宛先にルーティングします。
サイドカープロキシは、必要なテレメトリー情報も生成します。
1. リクエストに関する追加情報を含むエントリをローカルディスクのアクセスログに追加します。
2. トレースエントリを生成し、OpenCensus Envoy トレースを使用して Trace に送信します。
Logging エージェントはこのデータを Cloud Logging API にエクスポートし、Cloud Logging インターフェースで使用できるようにします。

前提条件

設定手順を完了する前に、次のことを確認してください。

Envoy で Traffic Director を設定する準備で説明されているように、Traffic Director API が有効になっており、他の前提条件を満たしている。
Cloud Trace API が有効になっている。
Compute Engine VM が使用するサービスアカウントには、次の Identity and Access Management（IAM）ロールが構成されています。
- Cloud Trace エージェントのロール（roles/cloudtrace.agent）
- ログ書き込みロール（roles/logging.logWriter）
ファイアウォールルールで、この設定の一環として構成した VM へのトラフィックを許可している。

デモサービスと Traffic Director を設定する

このドキュメントでは、いくつかのシェルスクリプトを使用して、デモサービスの構成に必要な手順を行います。スクリプトが行う具体的な手順について理解するために、スクリプトをご確認ください。

Compute Engine VM を起動し、VM に HTTP サービスを構成します。
```
curl -sSO https://storage.googleapis.com/traffic-director/demo/observability/setup_demo_service.sh
chmod 755 setup_demo_service.sh && ./setup_demo_service.sh
```
setup_demo_service.sh スクリプトは、VM の起動時に apache2 を起動する VM テンプレートと、このテンプレートを使用するマネージドインスタンスグループを作成します。このスクリプトは、自動スケーリングを有効にせずに単一のインスタンスを起動します。
Traffic Director を使用して 10.10.10.10 サービスのルーティングを構成します。
```
curl -sSO https://storage.googleapis.com/traffic-director/demo/observability/setup_demo_trafficdirector.sh
chmod 755 setup_demo_trafficdirector.sh && ./setup_demo_trafficdirector.sh
```
setup_demo_trafficdirector.sh スクリプトは、手動 Envoy デプロイで Compute Engine VM に Traffic Director を設定するで説明されているように、Traffic Director のマネージドサービスに必要なパラメータを構成します。
サイドカープロキシを VM にインストールして構成し、HTTP サービスのコンシューマを実行する Compute Engine VM を起動します。次のコマンドで、PROJECT_ID はトレース情報の送信先のプロジェクト ID に置き換えます。通常、これは VM が属している Google Cloud プロジェクトです。
```
curl -sSO https://storage.googleapis.com/traffic-director/demo/observability/setup_demo_client.sh
chmod 755 setup_demo_client.sh && ./setup_demo_client.sh PROJECT_ID
```
setup_demo_client.sh スクリプトは、Traffic Director を使用するように事前構成された Envoy プロキシを持つ Compute Engine VM を作成します。この構成は、手動 Envoy デプロイで Compute Engine VM に Traffic Director を設定するで説明されている構成と似ています。

次の追加の構成設定により、トレースとロギングが有効になります。

Traffic Director の Envoy ブートストラップ属性の構成で説明されているように、TRAFFICDIRECTOR_ACCESS_LOG_PATH と TRAFFICDIRECTOR_ENABLE_TRACING のブートストラップノードメタデータ変数によってロギングとトレースを有効にします。
静的ブートストラップ構成により、OpenCensus を使用してトレース情報を Trace にエクスポートできます。

これらのスクリプトを実行したら、td-observability-demo-client VM にログインし、10.10.10.10 で使用可能な HTTP サービスにアクセスできます。

curl http://10.10.10.10

この時点で、Envoy はアクセスロギングとトレース情報を生成します。次のセクションでは、ログとトレースの情報をエクスポートする方法について説明します。

Cloud Trace にトレースエクスポートを設定する

setup-demo-client.sh スクリプトを実行した際に作成した Envoy ブートストラップ構成で、トレース情報を生成できます。その他の構成はすべて任意です。追加のパラメータを構成する場合は、OpenCensus Envoy 構成ページを参照し、Envoy ブートストラップ構成でトレースオプションを変更します。

デモサーバー（curl 10.10.10.10）にサンプルリクエストを発行した後、Google Cloud Console で Trace のインターフェースに移動します（[トレース] > [トレースリスト] の順に選択）。発行されたリクエストに対応するトレースレコードが表示されます。

Trace の使用方法については、Cloud Trace のドキュメントをご覧ください。

Logging へのアクセスログエクスポートを設定する

この段階で Envoy は、実行されている VM のローカルディスクにアクセスログ情報を記録しているはずです。これらのレコードを Logging にエクスポートするには、Logging エージェントをローカルにインストールする必要があります。これには、Logging エージェントのインストールと構成が必要です。

Logging エージェントをインストールする

ロギング情報のエクスポート元の VM に Logging エージェントをインストールします。この構成例では、VM は td-observability-demo-vm です。

curl -sSO https://dl.google.com/cloudagents/add-logging-agent-repo.sh
sudo bash add-logging-agent-repo.sh --also-install

詳細については、単一の VM に Cloud Logging エージェントをインストールするをご覧ください。

Logging エージェントを構成する

Envoy のログは、非構造化テキストまたは構造化テキストとしてエクスポートできます。

Envoy のログを非構造化テキストとしてエクスポートする

このオプションでは、アクセスログのログレコードを未加工テキストとして Cloud Logging にエクスポートします。アクセスログの各エントリは、単一のエントリとして Logging にエクスポートされます。この構成は、Logging エージェントの現在のバージョンとともに配布されるパーサーに依存しているため、インストールは簡単です。ただし、このオプションを使用して未加工テキストのログエントリのフィルタリングや処理を行うことは困難です。

Envoy のアクセスログに関する非構造化エクスポート構成ファイルをダウンロードしてインストールします。

curl -sSO https://storage.googleapis.com/traffic-director/demo/observability/envoy_access_fluentd_unstructured.conf
sudo cp envoy_access_fluentd_unstructured.conf /etc/google-fluentd/config.d/envoy_access.conf

エージェントを再起動します。これらの変更はエージェントの起動時に有効になります。
```
sudo service google-fluentd restart
```

Envoy のログを構造化テキストとしてエクスポートする

GitHub から Envoy アクセスログパーサーをインストールします。
```
sudo /opt/google-fluentd/embedded/bin/gem install fluent-plugin-envoy-parser
```

Envoy アクセスログを構造化形式でエクスポートするための構成ファイルをダウンロードしてインストールします。

curl -sSO https://storage.googleapis.com/traffic-director/demo/observability/envoy_access_fluentd_structured.conf
sudo cp envoy_access_fluentd_structured.conf /etc/google-fluentd/config.d/envoy_access.conf

エージェントを再起動します。これらの変更はエージェントの起動時に有効になります。
```
sudo service google-fluentd restart
```

詳細については、Logging エージェントを構成するをご覧ください。

構成を確認する

サイドカープロキシ VM から、デモサービスへのリクエストを生成します。これにより、新しいローカルログレコードが作成されます。たとえば、curl 10.10.10.10 を実行できます。
Google Cloud コンソールで、[ロギング] > [ログエクスプローラ] に移動します。プルダウンメニューで、[envoy-access] ログタイプを選択します。前に選択した構成タイプに応じて、最新のリクエストのログエントリが非構造化形式または構造化形式で表示されます。

トラブルシューティング

複数プロジェクトにわたるトレースを構成する

複数のプロジェクトにデプロイされた Envoy のリクエストをトレースする場合は、次の点に注意してください。

各 Envoy は、それが実行されているプロジェクトの認証情報で構成する必要があります。
各 Envoy は、その認証情報に対応するプロジェクトにトレースデータを送信します。
リクエストの作成時にアプリケーションで X-Cloud-Trace-Context HTTP ヘッダーの値が保持される場合は、プロジェクト間のリクエストのトレーススパンを確認できます。

プロキシレス gRPC アプリケーションとのトレースの互換性

Envoy の OpenCensus トレーサー構成を使用すると、プロキシレス gRPC アプリケーションや Envoy プロキシからエクスポートされたトレースの完全な互換性をサービスメッシュ内で確保できるようになります。互換性を確保するため、Envoy ブートストラップでは、OpenCensusConfig に GRPC_TRACE_BIN トレース形式が含まれるようにトレースコンテキストを構成する必要があります。

tracing:
  http:
      name: envoy.tracers.opencensus
      typed_config:
        "@type": type.googleapis.com/envoy.config.trace.v2.OpenCensusConfig
        stackdriver_exporter_enabled: "true"
        stackdriver_project_id: "PROJECT_ID"
        incoming_trace_context: ["CLOUD_TRACE_CONTEXT", "GRPC_TRACE_BIN"]
        outgoing_trace_context: ["CLOUD_TRACE_CONTEXT", "GRPC_TRACE_BIN"]

構成が完了しても使用可能なトレースまたはロギングエントリが表示されない場合は、次を確認します。

Compute Engine VM のサービスアカウントには、前提条件で指定されている Trace と Logging の IAM 権限が割り当てられている必要があります。Trace の IAM 権限の詳細については、アクセス制御をご覧ください。Logging の権限の詳細については、アクセス制御をご覧ください。
ロギングについて: /var/log/google-fluentd/google-fluentd.log にエラーがないことを確認します。
ロギングについて: リクエストが発行された際に、ローカルのアクセスログファイルに新しいエントリが表示されることを確認します。

次のステップ

関連情報については、プロキシレス gRPC アプリケーションによるオブザーバビリティをご覧ください。
Traffic Director の一般的なトラブルシューティング情報については、Envoy を使用するデプロイのトラブルシューティングをご覧ください。