gRPC 存取日誌 (proto)

Envoy 存取日誌描述在固定時間內與 Envoy 的輸入互動，通常涵蓋單個請求/回應交換 (例如 HTTP)、串流 (例如透過 HTTP/gRPC) 或代理連線 (例如 TCP)。存取日誌包含在特定協定的 protobuf 訊息中定義的欄位。

除非另有明確聲明，否則所有欄位都描述 Envoy 與已連線用戶端之間的下游互動。描述上游互動的欄位將在其名稱中明確包含 upstream。

data.accesslog.v3.TCPAccessLogEntry

[data.accesslog.v3.TCPAccessLogEntry proto]

{
  "common_properties": {...},
  "connection_properties": {...}
}

common_properties: (data.accesslog.v3.AccessLogCommon) 所有 Envoy 存取日誌共用的通用屬性。

connection_properties: (data.accesslog.v3.ConnectionProperties) TCP 連線的屬性。

data.accesslog.v3.HTTPAccessLogEntry

[data.accesslog.v3.HTTPAccessLogEntry proto]

{
  "common_properties": {...},
  "protocol_version": ...,
  "request": {...},
  "response": {...}
}

common_properties: (data.accesslog.v3.AccessLogCommon) 所有 Envoy 存取日誌共用的通用屬性。

protocol_version: (data.accesslog.v3.HTTPAccessLogEntry.HTTPVersion)

request: (data.accesslog.v3.HTTPRequestProperties) 傳入 HTTP 請求的描述。

response: (data.accesslog.v3.HTTPResponseProperties) 傳出 HTTP 回應的描述。

列舉 data.accesslog.v3.HTTPAccessLogEntry.HTTPVersion

[data.accesslog.v3.HTTPAccessLogEntry.HTTPVersion proto]

HTTP 版本

PROTOCOL_UNSPECIFIED: (預設) ⁣

HTTP10: ⁣

HTTP11: ⁣

HTTP2: ⁣

HTTP3: ⁣

data.accesslog.v3.ConnectionProperties

[data.accesslog.v3.ConnectionProperties proto]

定義連線的欄位

{
  "received_bytes": ...,
  "sent_bytes": ...
}

received_bytes: (uint64) 從下游接收的位元組數。

sent_bytes: (uint64) 傳送到下游的位元組數。

data.accesslog.v3.AccessLogCommon

[data.accesslog.v3.AccessLogCommon proto]

定義所有 Envoy 存取日誌共用的欄位。

{
  "downstream_remote_address": {...},
  "downstream_local_address": {...},
  "tls_properties": {...},
  "start_time": {...},
  "time_to_last_rx_byte": {...},
  "time_to_first_upstream_tx_byte": {...},
  "time_to_last_upstream_tx_byte": {...},
  "time_to_first_upstream_rx_byte": {...},
  "time_to_last_upstream_rx_byte": {...},
  "time_to_first_downstream_tx_byte": {...},
  "time_to_last_downstream_tx_byte": {...},
  "upstream_remote_address": {...},
  "upstream_local_address": {...},
  "upstream_cluster": ...,
  "response_flags": {...},
  "metadata": {...},
  "upstream_transport_failure_reason": ...,
  "route_name": ...,
  "downstream_direct_remote_address": {...},
  "filter_state_objects": {...},
  "custom_tags": {...},
  "duration": {...},
  "upstream_request_attempt_count": ...,
  "connection_termination_details": ...,
  "stream_id": ...,
  "intermediate_log_entry": ...,
  "downstream_transport_failure_reason": ...,
  "downstream_wire_bytes_sent": ...,
  "downstream_wire_bytes_received": ...,
  "upstream_wire_bytes_sent": ...,
  "upstream_wire_bytes_received": ...,
  "access_log_type": ...
}

downstream_remote_address: (config.core.v3.Address) 此欄位是接收使用者請求的遠端/原始位址。注意：這可能不是實際的對等點。例如，如果遠端位址是從 x-forwarder-for 標頭、代理協定等推斷出來的。

downstream_local_address: (config.core.v3.Address) 此欄位是接收使用者請求的本機/目的地位置。

tls_properties: (data.accesslog.v3.TLSProperties) 如果連線是安全的，則此欄位將包含 TLS 屬性。

start_time: (Timestamp) Envoy 開始服務此請求的時間。這實際上是收到第一個下游位元組的時間。

time_to_last_rx_byte: (Duration) 從收到第一個下游位元組到收到最後一個下游位元組之間的時間間隔 (即接收請求所需的時間)。

time_to_first_upstream_tx_byte: (Duration) 從收到第一個下游位元組到傳送第一個上游位元組之間的時間間隔。time_to_last_rx_byte 與此值之間可能存在相當大的差異，原因在於篩選器。此外，也適用於 time_to_last_downstream_tx_byte 中關於不考慮核心通訊端緩衝區時間等的相同警告。

time_to_last_upstream_tx_byte: (Duration) 從收到第一個下游位元組到傳送最後一個上游位元組之間的時間間隔。time_to_last_rx_byte 與此值之間可能存在相當大的差異，原因在於篩選器。此外，也適用於 time_to_last_downstream_tx_byte 中關於不考慮核心通訊端緩衝區時間等的相同警告。

time_to_first_upstream_rx_byte: (Duration) 從收到第一個下游位元組到收到第一個上游位元組之間的時間間隔 (即開始接收回應所需的時間)。

time_to_last_upstream_rx_byte: (Duration) 從收到第一個下游位元組到收到最後一個上游位元組之間的時間間隔 (即接收完整回應所需的時間)。

time_to_first_downstream_tx_byte: (Duration) 從收到第一個下游位元組到傳送第一個下游位元組之間的時間間隔。由於篩選器，time_to_first_upstream_rx_byte 與此欄位之間可能存在相當大的差異。此外，也適用於 time_to_last_downstream_tx_byte 中關於不考慮核心通訊端緩衝區時間等的相同警告。

time_to_last_downstream_tx_byte: (Duration) 從收到第一個下游位元組到傳送最後一個下游位元組之間的時間間隔。根據協定、緩衝、視窗化、篩選器等，time_to_last_upstream_rx_byte 與此欄位之間可能存在相當大的差異。另請注意，這是一個近似時間。在目前的實作中，它不包含核心通訊端緩衝區時間。在目前的實作中，它也不包含 HTTP/2 編解碼器內的傳送視窗緩衝。未來可能會努力使此持續時間更準確。

upstream_remote_address: (config.core.v3.Address) 處理此交換的上游遠端/目的地位置。這不包括重試。

upstream_local_address: (config.core.v3.Address) 處理此交換的上游本機/原始位址。這不包括重試。

upstream_cluster: (string) upstream_remote_address 所屬的上游叢集。

response_flags: (data.accesslog.v3.ResponseFlags) 指示請求/回應處理期間發生的情況的旗標。

metadata

(config.core.v3.Metadata) 請求處理期間遇到的所有中繼資料，包括端點選取。

這可用於將附加到用於處理此請求的各種組態的 ID 與存取日誌項目關聯。例如，從具有某個 ID 的較高層級轉送規則建立的路由可以將該 ID 放置在此欄位中並稍後交叉參考。它也可用於確定是否使用了 Canary 端點。

upstream_transport_failure_reason: (string) 如果上游連線由於傳輸通訊端 (例如 TLS 交握) 而失敗，則提供來自傳輸通訊端的失敗原因。此欄位的格式取決於組態的上游傳輸通訊端。常見的 TLS 失敗在 TLS 問題排解中。

route_name: (string) 路由的名稱

downstream_direct_remote_address: (config.core.v3.Address) 此欄位是接收使用者請求的下游直接遠端位址。注意：這始終是實際的對等點，即使遠端位址是從 x-forwarder-for 標頭、代理協定等推斷出來的。

filter_state_objects: (重複 map<string, Any>) 已設定為記錄的串流資訊中篩選器狀態的對應。如果篩選器狀態序列化為 google.protobuf.Any 以外的任何訊息，則會將其封裝到 google.protobuf.Any 中。

custom_tags: (重複 map<string, string>) 自訂標籤的清單，用於以其他資訊註解日誌。若要設定此值，使用者應設定 custom_tags。

duration: (Duration) 針對 HTTP：從開始時間到最後一個位元組傳出的請求總持續時間 (以毫秒為單位)。針對 TCP：下游連線的總持續時間 (以毫秒為單位)。這是請求的總持續時間 (即，當請求的 ActiveStream 被銷毀時)，並且可能長於 time_to_last_downstream_tx_byte。

upstream_request_attempt_count: (uint32) 針對 HTTP：請求在上游嘗試的次數。請注意，當請求從未在上游嘗試時，會省略此欄位。針對 TCP：連線請求在上游嘗試的次數。請注意，當連線請求從未在上游嘗試時，會省略此欄位。

connection_termination_details: (string) 連線終止詳細資訊可能會提供關於為何 Envoy 因 L4 原因而終止連線的額外資訊。

stream_id: (string) 用於記錄和追蹤的串流（TCP 連線、長存活 HTTP2 串流、HTTP 請求）的可選唯一 ID。這可以是任何可用於識別一個串流的格式字串。

intermediate_log_entry: (bool) 此日誌條目是否為串流完成後刷新之最終日誌條目，或是串流期間定期刷新之中間日誌條目。對於每個長存活串流（TCP 連線、長存活 HTTP2 串流），可能有多個中間日誌條目和只有一個最終日誌條目。如果需要，可以將唯一 ID 或識別符號新增至日誌條目 stream_id，以關聯所有這些中間日誌條目和最終日誌條目。

注意

此欄位已棄用，改用 access_log_type 以更清楚地指示存取日誌記錄的類型。

downstream_transport_failure_reason: (string) 如果監聽器中的下游連線因傳輸層 Socket（例如 TLS 交握）而失敗，則會提供來自傳輸層 Socket 的失敗原因。此欄位的格式取決於已設定的下游傳輸層 Socket。常見的 TLS 失敗位於 TLS 疑難排解中。

downstream_wire_bytes_sent: (uint64) 對於 HTTP：HTTP 串流傳送至下游的總位元組數。對於 TCP：TCP Proxy 傳送至下游的總位元組數。

downstream_wire_bytes_received: (uint64) 對於 HTTP：HTTP 串流從下游接收到的總位元組數。Envoy 會將管線中的請求位元組加總到目前正在處理的請求位元組，從而高估接收到的 HTTP/1.1 管線請求大小。對於 TCP：TCP Proxy 從下游接收到的總位元組數。

upstream_wire_bytes_sent: (uint64) 對於 HTTP：HTTP 串流傳送至上游的總位元組數。此值會在上游重試期間累積。對於 TCP：TCP Proxy 傳送至上游的總位元組數。

upstream_wire_bytes_received: (uint64) 對於 HTTP：HTTP 串流從上游接收到的總位元組數。對於 TCP：TCP Proxy 傳送至上游的總位元組數。

access_log_type: (data.accesslog.v3.AccessLogType) 存取日誌的類型，指示記錄日誌的時間。請參閱 ACCESS_LOG_TYPE 以取得可用值。如果存取日誌是由不對應於其中一個支援值的流程記錄，則預設值將為 NotSet。如需關於存取日誌的行為方式以及記錄時間的詳細資訊，請參閱存取日誌記錄。

data.accesslog.v3.ResponseFlags

[data.accesslog.v3.ResponseFlags proto]

指示請求/回應處理期間發生的標誌。

{
  "failed_local_healthcheck": ...,
  "no_healthy_upstream": ...,
  "upstream_request_timeout": ...,
  "local_reset": ...,
  "upstream_remote_reset": ...,
  "upstream_connection_failure": ...,
  "upstream_connection_termination": ...,
  "upstream_overflow": ...,
  "no_route_found": ...,
  "delay_injected": ...,
  "fault_injected": ...,
  "rate_limited": ...,
  "unauthorized_details": {...},
  "rate_limit_service_error": ...,
  "downstream_connection_termination": ...,
  "upstream_retry_limit_exceeded": ...,
  "stream_idle_timeout": ...,
  "invalid_envoy_request_headers": ...,
  "downstream_protocol_error": ...,
  "upstream_max_stream_duration_reached": ...,
  "response_from_cache_filter": ...,
  "no_filter_config_found": ...,
  "duration_timeout": ...,
  "upstream_protocol_error": ...,
  "no_cluster_found": ...,
  "overload_manager": ...,
  "dns_resolution_failure": ...,
  "downstream_remote_reset": ...
}

failed_local_healthcheck: (bool) 指示本機伺服器健康檢查失敗。

no_healthy_upstream: (bool) 指示沒有健全的上游。

upstream_request_timeout: (bool) 指示發生上游請求逾時。

local_reset: (bool) 指示已在串流上傳送本機編解碼器層級重設。

upstream_remote_reset: (bool) 指示已在串流上接收到遠端編解碼器層級重設。

upstream_connection_failure: (bool) 指示連線集區因初始連線失敗而進行本機重設。

upstream_connection_termination: (bool) 指示串流因上游連線終止而重設。

upstream_overflow: (bool) 指示串流因資源溢位而重設。

no_route_found: (bool) 指示找不到請求的路由。

delay_injected: (bool) 指示請求在 Proxy 之前已延遲。

fault_injected: (bool) 指示請求已使用插入的錯誤代碼中止。

rate_limited: (bool) 指示請求在本機受速率限制。

unauthorized_details: (data.accesslog.v3.ResponseFlags.Unauthorized) 指示是否視請求為未經授權以及原因。

rate_limit_service_error: (bool) 指示請求因速率限制服務中發生錯誤而遭拒。

downstream_connection_termination: (bool) 指示串流因下游連線終止而重設。

upstream_retry_limit_exceeded: (bool) 指示超出上游重試限制，導致下游錯誤。

stream_idle_timeout: (bool) 指示已達到串流閒置逾時，導致下游 408 錯誤。

invalid_envoy_request_headers: (bool) 指示請求因 Envoy 請求標頭未通過嚴格驗證而遭拒。

downstream_protocol_error: (bool) 指示下游請求發生 HTTP 通訊協定錯誤。

upstream_max_stream_duration_reached: (bool) 指示上游請求已達到最大串流持續時間。

response_from_cache_filter: (bool) 指示回應來自快取篩選器。

no_filter_config_found: (bool) 指示沒有可用的篩選器設定。

duration_timeout: (bool) 指示請求或連線超出下游連線持續時間。

upstream_protocol_error: (bool) 指示上游回應發生 HTTP 通訊協定錯誤。

no_cluster_found: (bool) 指示找不到請求的叢集。

overload_manager: (bool) 指示過載管理員已終止請求。

dns_resolution_failure: (bool) 指示 DNS 解析失敗。

downstream_remote_reset: (bool) 指示已在串流上接收到下游遠端編解碼器層級重設

data.accesslog.v3.ResponseFlags.Unauthorized

[data.accesslog.v3.ResponseFlags.Unauthorized proto]

{
  "reason": ...
}

reason: (data.accesslog.v3.ResponseFlags.Unauthorized.Reason)

列舉 data.accesslog.v3.ResponseFlags.Unauthorized.Reason

[data.accesslog.v3.ResponseFlags.Unauthorized.Reason proto]

請求未經授權的原因

REASON_UNSPECIFIED: (預設) ⁣

EXTERNAL_SERVICE: ⁣請求遭到外部授權服務拒絕。

data.accesslog.v3.TLSProperties

[data.accesslog.v3.TLSProperties proto]

已協商的 TLS 連線的屬性。

{
  "tls_version": ...,
  "tls_cipher_suite": {...},
  "tls_sni_hostname": ...,
  "local_certificate_properties": {...},
  "peer_certificate_properties": {...},
  "tls_session_id": ...,
  "ja3_fingerprint": ...
}

tls_version: (data.accesslog.v3.TLSProperties.TLSVersion) 已協商的 TLS 版本。

tls_cipher_suite

(UInt32Value) 在交握期間協商的 TLS 加密套件。該值是由 IANA TLS 加密套件登錄定義的四位數十六進位碼（例如，009C 代表 TLS_RSA_WITH_AES_128_GCM_SHA256）。

此處表示為整數。

tls_sni_hostname: (string) 來自交握的 SNI 主機名稱。

local_certificate_properties: (data.accesslog.v3.TLSProperties.CertificateProperties) 用於協商 TLS 的本地憑證屬性。

peer_certificate_properties: (data.accesslog.v3.TLSProperties.CertificateProperties) 用於協商 TLS 的對等憑證屬性。

tls_session_id: (string) TLS 工作階段 ID。

ja3_fingerprint: (string) 啟用 JA3 指紋識別時的 JA3 指紋。

data.accesslog.v3.TLSProperties.CertificateProperties

[data.accesslog.v3.TLSProperties.CertificateProperties proto]

{
  "subject_alt_name": [],
  "subject": ...,
  "issuer": ...
}

subject_alt_name: (repeated data.accesslog.v3.TLSProperties.CertificateProperties.SubjectAltName) 憑證中存在的 SAN。

subject: (string) 憑證的主體欄位。

issuer: (string) 憑證的簽發者欄位。

data.accesslog.v3.TLSProperties.CertificateProperties.SubjectAltName

[data.accesslog.v3.TLSProperties.CertificateProperties.SubjectAltName proto]

{
  "uri": ...
}

uri: (string)

列舉 data.accesslog.v3.TLSProperties.TLSVersion

[data.accesslog.v3.TLSProperties.TLSVersion proto]

VERSION_UNSPECIFIED: (預設) ⁣

TLSv1: ⁣

TLSv1_1: ⁣

TLSv1_2: ⁣

TLSv1_3: ⁣

data.accesslog.v3.HTTPRequestProperties

[data.accesslog.v3.HTTPRequestProperties proto]

{
  "request_method": ...,
  "scheme": ...,
  "authority": ...,
  "port": {...},
  "path": ...,
  "user_agent": ...,
  "referer": ...,
  "forwarded_for": ...,
  "request_id": ...,
  "original_path": ...,
  "request_headers_bytes": ...,
  "request_body_bytes": ...,
  "request_headers": {...},
  "upstream_header_bytes_sent": ...,
  "downstream_header_bytes_received": ...
}

request_method: (config.core.v3.RequestMethod) 請求方法 (RFC 7231/2616)。

scheme: (string) 傳入請求 URI 的 scheme 部分。

authority: (string) HTTP/2 :authority 或 HTTP/1.1 Host 標頭值。

port: (UInt32Value) 傳入請求 URI 的埠號 (目前未使用，因為埠號已組成 authority)。

path: (string) 傳入請求 URI 的路徑部分。

user_agent: (string) User-Agent 請求標頭的值。

referer: (string) Referer 請求標頭的值。

forwarded_for: (string) X-Forwarded-For 請求標頭的值。

request_id

(string) X-Request-Id 請求標頭的值

此標頭由 Envoy 用於唯一識別請求。它將為所有外部請求以及尚未具有請求 ID 的內部請求生成。

original_path: (string) X-Envoy-Original-Path 請求標頭的值。

request_headers_bytes

(uint64) HTTP 請求標頭的大小 (以位元組為單位)。

此值是從 OSI 第 7 層的角度擷取的，也就是說，它不包含其他網路層的框架或編碼的額外負荷。

request_body_bytes

(uint64) HTTP 請求主體的大小 (以位元組為單位)。

此值是從 OSI 第 7 層的角度擷取的，也就是說，它不包含其他網路層的框架或編碼的額外負荷。

request_headers: (repeated map<string, string>) 已設定要記錄的其他標頭對應。

upstream_header_bytes_sent

(uint64) 由 http 串流傳送到上游的標頭位元組數，包括協定額外負荷。

此值會在上游重試期間累積。

downstream_header_bytes_received: (uint64) 由 http 串流從下游接收的標頭位元組數，包括協定額外負荷。

data.accesslog.v3.HTTPResponseProperties

[data.accesslog.v3.HTTPResponseProperties proto]

{
  "response_code": {...},
  "response_headers_bytes": ...,
  "response_body_bytes": ...,
  "response_headers": {...},
  "response_trailers": {...},
  "response_code_details": ...,
  "upstream_header_bytes_received": ...,
  "downstream_header_bytes_sent": ...
}

response_code: (UInt32Value) Envoy 傳回的 HTTP 回應碼。

response_headers_bytes

(uint64) HTTP 回應標頭的大小 (以位元組為單位)。

此值是從 OSI 第 7 層的角度擷取的，也就是說，它不包含協定額外負荷，或其他網路層的框架或編碼的額外負荷。

response_body_bytes

(uint64) HTTP 回應主體的大小 (以位元組為單位)。

此值是從 OSI 第 7 層的角度擷取的，也就是說，它不包含其他網路層的框架或編碼的額外負荷。

response_headers: (repeated map<string, string>) 已設定要記錄的其他標頭對應。

response_trailers: (repeated map<string, string>) 已設定要記錄的追蹤程式對應。

response_code_details: (string) HTTP 回應碼詳細資訊。

upstream_header_bytes_received: (uint64) 由 http 串流從上游接收的標頭位元組數，包括協定額外負荷。

downstream_header_bytes_sent: (uint64) 由 http 串流傳送到下游的標頭位元組數，包括協定額外負荷。

列舉 data.accesslog.v3.AccessLogType

[data.accesslog.v3.AccessLogType proto]

NotSet: (預設) ⁣

TcpUpstreamConnected: ⁣

TcpPeriodic: ⁣

TcpConnectionEnd: ⁣

DownstreamStart: ⁣

DownstreamPeriodic: ⁣

DownstreamEnd: ⁣

UpstreamPoolReady: ⁣

UpstreamPeriodic: ⁣

UpstreamEnd: ⁣

DownstreamTunnelSuccessfullyEstablished: ⁣

UdpTunnelUpstreamConnected: ⁣

UdpPeriodic: ⁣

UdpSessionEnd: ⁣