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

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

  • 2025/04/17
  • Envoy
  • 9 分钟
  • 1911 字
版权声明
本文为 Jimmy Song 原创。转载请注明来源： 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 的可观测性组件架构：

image
Envoy Gateway 可观测性管道

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

安装 Envoy Gateway

按照官方 快速开始指南 安装 Envoy Gateway：

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 安装可观测性组件：

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，本地可通过端口转发的方式访问：

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：

kubectl apply -f - <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
  name: envoy-gateway-config
  namespace: envoy-gateway-system
data:
  envoy-gateway.yaml: |
    apiVersion: gateway.envoyproxy.io/v1alpha1
    kind: EnvoyGateway
    provider:
      type: Kubernetes
    gateway:
      controllerName: gateway.envoyproxy.io/gatewayclass-controller
    telemetry:
      metrics:
        prometheus:
          disable: true
        sinks:
          - type: OpenTelemetry
            openTelemetry:
              host: otel-collector.monitoring.svc.cluster.local
              port: 4317
              protocol: grpc
EOF

更新配置后，重启 Envoy Gateway 以生效：

kubectl rollout restart deployment envoy-gateway -n envoy-gateway-system

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

image
指标可观测性

使用 Prometheus 查看指标

本地暴露 Prometheus：

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

访问 http://localhost:9090 并执行如下查询：

topk(1,envoy_cluster_upstream_cx_connect_ms_sum)
image
Prometheus UI

使用 Grafana 查看指标

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

打开 http://localhost:3000，默认账户密码为 admin/admin。

image
Grafana - Envoy Clusters dashboard

详细配置参考 Proxy Metrics 指南。

日志（Logs）

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

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

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

通过 Loki 查询日志示例：

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

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

 [
   [
     "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 目标，亦支持按需采样、过滤，并可包含安全相关字段用于审计。

image
日志可观测性

日志配置详情参考 Proxy Access Logs 指南。

在 Grafana 中查看日志

  1. 暴露 Grafana：
kubectl port-forward -n monitoring svc/grafana 3000:80

  1. 打开浏览器访问 http://localhost:3000，首次登录使用 admin/admin。

  2. 点击左侧导航栏的齿轮图标 → Data sources，确保 Loki 数据源配置正确，地址为 http://loki:3100。

  3. 下载并导入日志仪表盘：envoy-gateway-logs-dashboard.json

  4. 打开 Envoy Gateway Logs 仪表盘，即可查询和过滤日志数据：

image
Envoy Gateway Logs dashboard

追踪（Traces）

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

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

启用追踪：

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

使用 Tempo 验证追踪数据

暴露 Tempo：

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

查询 trace 概览：

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

示例输出：

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

查询指定 trace：

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

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

详细参考 Proxy Tracing 指南。

在 Grafana 中查看追踪数据

  1. 在 Grafana 左侧导航栏点击 Data sources，确认已配置名为 tempo 的 Tempo 数据源，地址为 http://tempo:3100。

  2. 下载并导入追踪仪表盘：envoy-gateway-traces-dashboard.json

  3. 打开 Envoy Gateway Traces 仪表盘，浏览可用的 trace 数据：

image
Envoy Gateway Traces Dashboard

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

image
Trace Spans

总结

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

最后更新于 2025/04/17

Envoy Envoy Gateway 可观测性 OpenTelemetry 指标 日志 追踪