コンテンツにスキップ

テレメトリー＠Envoy

はじめに

本サイトにつきまして、以下をご認識のほど宜しくお願いいたします。


01. ログ (アクセスログのみ)

アクセスログ形式と変数

▼ アクセスログ形式

Envoyは、マイクロサービスへのアクセスログ (インバウンド通信とアウトバウンド通信の両方) を作成し、標準出力に出力する。

デフォルトで以下の形式でアクセスログを出力する。

[%START_TIME%] "%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%"
%RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT% %DURATION%
%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)% "%REQ(X-FORWARDED-FOR)%" "%REQ(USER-AGENT)%"
"%REQ(X-REQUEST-ID)%" "%REQ(:AUTHORITY)%" "%UPSTREAM_HOST%"\n

[2016-04-15T20:17:00.310Z] "POST /api/v1/locations HTTP/2" 204 - 154 0 226 100 "10.0.35.28"
"nsq2http" "cc21d9b0-cf5c-432b-8c7e-98aeb7988cd2" "locations" "tcp://10.0.2.1:80"

なお、%REQ()を使用して、好きなリクエストヘッダー値を出力できる。

これは、例えばユーザー定義のIDを使用している場合に役立つ。

[%START_TIME%] %REQ(<リクエストヘッダー名 (例：ユーザー定義のトレースIDのヘッダー)>)% ...


▼ %RESPONSE_FLAGS%

Cluster外からのリクエスト/Pod間通信時のレスポンスの補足メッセージを表す。

ステータスコードと合わせて、レスポンスのエラーや警告の理由を読み取ることに役立つ。

アップストリームが原因のメッセージは以下の通りである。

名前 正式名称 ステータスコード 説明
NC NO_CLUSTER_FOUND なし クラスターの設定が見つからず、Envoyはアップストリームに接続できなかった。
UC UPSTREAM_CONNECTION_TERMINATION 503 遭遇率が一番高い。Envoyは何らかの理由でアップストリームに接続できなかった。
UF UPSTREAM_CONNECTION_FAILURE 503 Envoyは通信障害でアップストリームに接続できなかった。
UT UPSTREAM_REQUEST_TIMEOUT 503 Envoyはタイムアウトでアップストリームに接続できなかった。
UO UPSTREAM_OVERFLOW 503 サーキットブレイカーで、Envoyはアップストリームに接続できなかった。
URX UPSTREAM_RETRY_LIMIT_EXCEEDED なし アップストリームの通信試行回数制限の上限超過で、Envoyはアップストリームに接続拒否されてしまった。
UH NO_HEALTHY_UPSTREAM 503 Envoyはアップストリームの異常で接続できなかった。

ダウンストリームが原因のメッセージは以下の通りである。

名前 正式名称 ステータスコード 説明
DC DOWNSTREAM_CONNECTION_TERMINATION なし Envoyのダウンストリームへのリクエストが中断され、Envoyはレスポンスを受信できなかった。
DPE DOWNSTREAM_PROTOCOL_ERROR なし EnvoyはHTTPプロトコルのエラーでダウンストリームに接続できなかった。
NR NO_ROUTE_FOUND 404 ルートやフィルターチェーンの設定が見つからず、Envoyはダウンストリームに接続できなかった。

監視バックエンドへの送信

▼ CloudWatchログの場合

直接的にCloudWatchログに送信できない。

そのため、Envoyのログを一度標準出力に出力し、これをログ収集ツール (例：FluentBit) でCloudWatchログに転送する。


02. メトリクス

メトリクスの種類

▼ メトリクス名のルール

Envoyのメトリクスには、、

▼ 通信全体に関するメトリクス

envoy_downstream_***** (インバウンド系)、envoy_upstream_***** (アウトバウンド系) のメトリクスがある。

▼ Envoy自身系

envoy_server_*****をプレフィクスとするメトリクスがある。

注意点として、ドキュメントではプレフィクスが省略されてしまっている。

▼ リスナー系

envoy_downstream_***** (インバウンド系)、envoy_upstream_***** (アウトバウンド系) をプレフィクスとするメトリクスがある。

注意点として、ドキュメントではプレフィクスが省略されてしまっている。

▼ ルート系

記入中...

▼ クラスター系

envoy_downstream_***** (インバウンド系)、envoy_upstream_***** (アウトバウンド系) をプレフィクスとするメトリクスがある。

注意点として、ドキュメントではプレフィクスが省略されてしまっている。

▼ エンドポイント系

記入中...


監視バックエンドへの送信

Envoyの15090番ポートでは、メトリクス収集ツール (例：Prometheus) からのリクエストを待ち受ける。

Envoyが、/stats/prometheusエンドポイントでリクエストを待ち受けており、データポイントを含むレスポンスを返信する。

もしサービスメッシュツール (例：Istio、Linkerd、など) を使用する場合、コントロールプレーン側にも同じエンドポイントがあり、メトリクス収集ツールはこちら側を指定することが多い。

# envoyコンテナからメトリクスを取得する。
$ kubectl exec \
    -it foo-pod \
    -n foo-namespace \
    -c envoy \
    -- bash -c "curl http://127.0.0.1:15090/stats/prometheus"


03. 分散トレース

Carrier

Envoyは、自身を通過したリクエストのCarrier (例：HTTPヘッダー、gRPCメタデータ、など) にリクエストIDを設定する。

▼ Carrierの種類

Envoyでは、様々なCarrierを使用できる。

▼ リクエストIDの作成

EnvoyはIDを自動作成する。

また、受信したリクエストのCarrier (例：HTTPヘッダー、gRPCメタデータ、など) にX-REQUEST-IDヘッダーを割り当てる。

▼ IDの結合

Envoyは、X-REQUEST-IDヘッダーの自動作成IDとX-CLIENT-TRACE-IDの外部作成IDを結合する


監視バックエンドへのスパンの送信

▼ スパンの送信

Envoyは、Exporterとしてスパンを監視バックエンドに送信する。

これにより、マイクロサービス側でExporterを実装する必要がなくなる。

ただし、もしマイクロサービス側でExporterを設定しないとEnvoyとマイクロサービスの処理時間を合計したスパンを送信する。

マイクロサービスとEnvoyの両方で設定すると、Envoyとマイクロサービスをちゃんと区別したスパンになる。

▼ トレースコンテキスト仕様

監視バックエンドの種類を指定することで、送信するトレースコンテキストの仕様を切り替えられる。

  • Datadog (Datadogコンテキスト)
  • OpenTelemetry (W3C Trace Context、Baggage)
  • X-Ray (X-Rayコンテキスト)
  • Zipkin (B3)
  • など

▼ X-Rayの場合

スパンをX-Rayデーモンに送信して、X-Rayで分散トレースを監視できる。

一部のサービスメッシュツール (例：AppMesh) では、Envoyのこの機能を使用して、X-Rayにスパンを送信する。

注意点として、サービスメッシュツール (例：Istio) によっては、X-Rayデーモンにスパンを送信できず、代わりにOpenTelemetry Collectorにスパンを送信しないといけない場合がある。