Envoy Gateway 数据平面可观测性指南

一篇基于 Prometheus、Loki 和 Tempo 的 Envoy Gateway 数据平面可观测性配置实践指南。

阅读原文请转到：https://jimmysong.io/blog/envoy-gateway-data-plane-observability/
注意：本文基于 Envoy Gateway v1.3.2 编写。

在大规模微服务架构中，可观测性是理解与运维系统的核心能力。Envoy Gateway 构建于 Envoy Proxy 之上，提供了丰富的可观测性功能，包括指标、日志和追踪。本文将通过动手实践的方式，讲解如何基于 Prometheus、Loki 和 Tempo 等开源后端，为 Envoy Gateway 的数据平面（即 Envoy proxy 本身）配置可观测性功能。

前置条件

在开始配置之前，请确保你已经完成 Envoy Gateway 的基本安装。下图展示了 Envoy Gateway 的可观测性组件架构：

Envoy Gateway 可观测性管道

OpenTelemetry Collector 是一个可插拔的数据中转组件，负责接收、处理和转发可观测性数据（如指标和追踪），来源包括 Envoy Gateway 等系统。通过将数据生成与数据消费解耦，它能够灵活对接多种可观测性后端（如 Prometheus、Tempo、Jaeger），同时支持数据增强、格式转换和多路导出。

安装 Envoy Gateway

按照官方快速开始指南^[1] 安装 Envoy Gateway：

go 复制代码

helm install eg oci://docker.io/envoyproxy/gateway-helm --version v1.3.2 -n envoy-gateway-system --create-namespace
kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available
kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/v1.3.2/quickstart.yaml -n default

安装可观测性组件

使用官方 Helm chart 安装可观测性组件：

go 复制代码

helm install eg-addons oci://docker.io/envoyproxy/gateway-addons-helm --version v1.3.2 -n monitoring --create-namespace --set opentelemetry-collector.enabled=true

注意：OpenTelemetry Collector 默认未启用，需显式开启。

安装完成后，将部署以下组件：

组件	角色	描述
FluentBit	日志收集器	收集并转发日志到 Loki
Grafana	可视化界面	展示指标、日志和追踪的仪表盘
Loki	日志存储	聚合和索引日志
OpenTelemetry Collector	遥测收集器	将指标/追踪数据导出到 Prometheus / Tempo
Prometheus	指标后端	收集并存储 Prometheus 指标数据
Tempo	追踪后端	存储和查询分布式追踪数据

生成测试流量

为了测试可观测性组件，我们可以向 Envoy Gateway 发送一些简单的请求。由于使用的是 Minikube，本地可通过端口转发的方式访问：

go 复制代码

export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}')
kubectl port-forward -n envoy-gateway-system svc/${ENVOY_SERVICE} 8888:80
curl --verbose --header "Host: www.example.com" http://localhost:8888/get

指标（Metrics）

通过以下配置禁用默认的 Prometheus 指标输出，并启用 OpenTelemetry Sink：

go 复制代码

cat <<EOF|kubectlapply-f-
apiVersion:gateway.networking.k8s.io/v1
kind:Gateway
metadata:
name:eg
namespace:envoy-gateway-system
spec:
gatewayClassName:eg
infrastructure:
    parametersRef:
      group:gateway.envoyproxy.io
      kind:EnvoyProxy
      name:unified-telemetry
listeners:
    -name:http
      protocol:HTTP
      port:80
---
apiVersion:gateway.envoyproxy.io/v1alpha1
kind:EnvoyProxy
metadata:
name:unified-telemetry
namespace:envoy-gateway-system
spec:
telemetry:
    metrics:
      prometheus:
        disable:true
      sinks:
        -type:OpenTelemetry
          openTelemetry:
            host:otel-collector.monitoring.svc.cluster.local
            port:4317
EOF

下图展示了 Envoy Proxy 指标可观测性的整体流程：Envoy 原生采集网络流量等关键指标，并通过 /stats/prometheus 接口暴露，Prometheus 进行抓取并在 Grafana 中可视化。此外，Envoy 还支持自定义指标，并可选集成 StatsD 等系统，实现灵活的监控体系。

指标可观测性

使用 Prometheus 查看指标

本地暴露 Prometheus：

go 复制代码

kubectl port-forward -n monitoring svc/prometheus 9090:80

访问 http://localhost:9090^[2] 并执行如下查询：

go 复制代码

topk(1,envoy_cluster_upstream_cx_connect_ms_sum)

Prometheus UI

使用 Grafana 查看指标

go 复制代码

kubectl port-forward -n monitoring svc/grafana 3000:80

打开 http://localhost:3000^[3]，默认账户密码为 admin/admin。
Grafana - Envoy Clusters dashboard

详细配置参考 Proxy Metrics 指南^[4]。

日志（Logs）

Envoy Gateway 使用访问日志（Access Log）进行流量记录，支持格式和输出目标的自定义。

应用以下配置，启用将日志发送至 OpenTelemetry Sink：

go 复制代码

kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/refs/heads/main/examples/kubernetes/accesslog/otel-accesslog.yaml

通过 Loki 查询日志示例：

go 复制代码

curl -s "http://localhost:3100/loki/api/v1/query_range" --data-urlencode "query={exporter=\"OTLP\"}" | jq '.data.result[0].values'

你将看到类似以下格式的输出：

go 复制代码

[
   [
     "1693314563284333000",
     "{"body":"[2025-04-17T13:09:23.284Z] \"- - HTTP/1.1\" 400 DPE 0 11 0 \"-\" \"-\" \"-\" \"-\" \"-\"\n","resources":{"cluster_name":"default/eg","k8s.cluster.name":"cluster-1","log_name":"otel_envoy_accesslog","node_name":"envoy-default-eg-64656661-6fccffddc5-662np","zone_name":""}}"
   ]
 ]

下图展示了日志可观测性流程：Envoy 支持自定义日志格式、输出到文件/stdout/syslog/HTTP 目标，亦支持按需采样、过滤，并可包含安全相关字段用于审计。

日志可观测性

日志配置详情参考 Proxy Access Logs 指南^[5]。

在 Grafana 中查看日志

1. 暴露 Grafana：

go 复制代码

kubectl port-forward -n monitoring svc/grafana 3000:80

1. 打开浏览器访问 http://localhost:3000^[6]，首次登录使用 admin/admin。
1. 点击左侧导航栏的齿轮图标 → Data sources ，确保 Loki 数据源配置正确，地址为 http://loki:3100。
1. 下载并导入日志仪表盘：envoy-gateway-logs-dashboard.json^[7]
1. 打开 Envoy Gateway Logs 仪表盘，即可查询和过滤日志数据：

Envoy Gateway Logs dashboard

追踪（Traces）

追踪提供了请求路径的详细可视化，是定位性能瓶颈的重要手段。

Envoy Gateway 原生支持 OpenTelemetry 格式的追踪，生成带有 Trace ID 和 Span ID 的请求链路数据，可通过配置发送到 Tempo、Zipkin 等支持 OpenTracing 协议的后端。

启用追踪：

go 复制代码

kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/refs/heads/main/examples/kubernetes/tracing/default.yaml

使用 Tempo 验证追踪数据

暴露 Tempo：

go 复制代码

kubectl port-forward svc/tempo 3100:3100 -n monitoring

查询 trace 概览：

go 复制代码

curl -s "http://localhost:3100/api/search" --data-urlencode "q={ component=envoy }" | jq .traces

示例输出：

go 复制代码

[
  {
   "traceID": "8010d4fd89e024c0626d984621babd71",
   "rootServiceName": "eg.default",
   "rootTraceName": "ingress",
   "startTimeUnixNano": "1693377719403756000"
  }
]

查询指定 trace：

go 复制代码

curl -s "http://localhost:3100/api/traces/<trace_id>" | jq

返回信息将包含完整的 trace span 数据，包括服务名、请求起止时间、状态码、上下游节点等详细字段。

详细参考 Proxy Tracing 指南^[8]。

在 Grafana 中查看追踪数据

1. 在 Grafana 左侧导航栏点击 Data sources ，确认已配置名为 tempo 的 Tempo 数据源，地址为 http://tempo:3100。
1. 下载并导入追踪仪表盘：envoy-gateway-traces-dashboard.json^[9]
1. 打开 Envoy Gateway Traces 仪表盘，浏览可用的 trace 数据：

Envoy Gateway Traces Dashboard

点击任意 trace 可查看其详细的 span 结构：
Trace Spans

总结

通过本文的实践操作，你已掌握了如何为 Envoy Gateway 的数据平面启用完整的可观测性功能。结合 OpenTelemetry Collector 的中转能力，以及 Prometheus、Loki 和 Tempo 等后端系统，你可以构建一个具备可扩展性、可插拔性和一致性的可观测性体系，帮助你在无需修改应用代码的前提下，实现对系统流量、性能和错误的深入洞察与排障能力。

引用链接

[1] 快速开始指南:https://gateway.envoyproxy.io/docs/tasks/quickstart
[2]http://localhost:9090:http://localhost:9090/
[3]http://localhost:3000:http://localhost:3000/
[4]Proxy Metrics 指南:https://gateway.envoyproxy.io/docs/tasks/observability/proxy-metric/
[5]Proxy Access Logs 指南:https://gateway.envoyproxy.io/docs/tasks/observability/proxy-accesslog/
[6]http://localhost:3000:http://localhost:3000/
[7]envoy-gateway-logs-dashboard.json:https://gist.githubusercontent.com/rootsongjc/539b9fd1cf3006e3e1b0af90c844f155/raw/e05b9ccf54ebe030bd38e84085b89f21e023cf48/envoy-gateway-logs-dashboard.json
[8]Proxy Tracing 指南:https://gateway.envoyproxy.io/docs/tasks/observability/proxy-accesslog/
[9]envoy-gateway-traces-dashboard.json:https://gist.githubusercontent.com/rootsongjc/bc2c3612658b302146a0e6c5aca97a79/raw/77722c5862e5f527a523237ce8a66397ca2d4bce/envoy-gateway-traces-dashboard.json