管理接口

Envoy 在本地提供了一个管理界面,可以使用这一界面查询或修改服务器的各种数据。

注意

目前管理界面可以进行破坏性操作(例如关闭服务器),也可能暴露私有数据(例如统计数据、集群名称、证书信息等)。将管理界面限制到只能在安全网络之内进行访问是 非常必要 的。同时还要注意,提供管理界面服务的网络接口只接入到安全网络之中(防止 CSRF 攻击等目的)。要实现这些目标,可以进行相应的防火墙设置,或者只允许 localhost 访问。可以使用如下的 v2 配置来完成:

  1. admin:
  2. access_log_path: /tmp/admin_access.log
  3. address:
  4. socket_address: { address: 127.0.0.1, port_value: 9901 }

未来还会在管理界面中加入更多的安全相关的选项。这部分工作的进度在 Github Issue #2763 上进行跟踪。所有的变更操作都应该通过 HTTP POST 方式进行。一段时间之内还是允许 HTTP GET 访问的,但是会有一条 Warning 日志。

GET /

渲染一个 HTML 主页,其中包含指向所有可用选项的链接。

GET /help

以字符表格的形式输出所有可用选项。

GET /certs

列出所有载入的 TLS 认证,包括文件名、序列号以及过期时间。

GET /clusters

列出集群管理器中配置的所有集群。这种信息中包含了已被发现的每个集群中的所有上游主机,以及每个主机的统计信息。如果服务发现出现问题需要除错,这些信息就很有帮助了。

集群管理器信息

version_info:string,最近载入的 CDS 的版本信息字符串。如果 Envoy 没有设置 CDS,则会输出来自于 version_info::static

集群层信息

  • 各优先级的断路器设置。
  • 如果设置了外部检测,则显示相关信息。目前包含了平均成功率以及驱逐阈值的检测器。上一个检测周期中所获取的数据量不足,这些变量的值会被设置为-1
  • added_via_api 标志:如果是静态配置添加的集群,这个项目的值就是 false;如果是使用 CDS API 添加的集群,这个值就会设置为 true

主机统计数据

名称 类型 描述
cx_total Counter 连接总数
cx_active Gauge 活动连接总数
cx_connect_fail Counter 连接失败总数
rq_total Counter 请求总数
rq_timeout Counter 超时请求总数
rq_success Counter 收到非 5xx 响应的请求总数
rq_error Counter 收到 5xx 响应的请求总数
rq_active Gauge 活动请求总数
healthy String 主机健康状态,下面会有讲解
weight Integer 负载均衡权重(0-100)
zone String 服务区域
canary Boolean 本主机是否为金丝雀
success_rate Double 请求成功率(0 - 100)。如果统计周期内没有足够的请求量进行运算,则返回 -1

主机健康状态

  • 如果主机是健康的,那么 healthy 的输出为 healthy
  • 如果主机不健康,则 healthy 返回的是下面几个状态之一:
    • /failed_active_hc主动健康监测失败。
    • /failed_eds_health:EDS 标记该主机不健康。
    • /failed_outlier_check:外部检测失败。

GET /config_dump

用 JSON 序列化格式从多种 Envoy 组件中导出当前的配置。可以延伸阅读 response definition 的内容,来获得更详细的信息。

POST /cpuprofiler

启用或停用 CPU Profiler。编译时需要启用 gperftools。

POST /healthcheck/fail

设置健康状况为失败。需要配合 HTTP 健康检查过滤器来使用。这一功能可以停用一个服务器而无需进行关闭或者重启动操作。这个命令执行之后,不论过滤器如何设置,都会把全局范围内的健康检查设为失败。

POST /healthcheck/ok

POST /healthcheck/fail 的逆向操作。同样需要配合 HTTP 健康检查过滤器来使用。

GET /hot_restart_version

参考 --hot-restart-version

POST /logging

在不同的子组件上启用或者禁用不同级别的日志。一般只会在开发期间使用。

POST /quitquitquit

完全退出服务。

POST /reset_counters

把所有的计数器复位为 0。这在使用 GET /stats 协助调试的时候是很有用的功能。注意这个功能并不会删除任何发送给 statsd 的数据,它只会对 GET /stats 命令的输出造成影响。

GET /server_info

输出关于服务器的信息,内容格式类似:

envoy 267724/RELEASE live 1571 1571 0

其中的字段包括:

  • 进程名称
  • 编译的 SHA 以及 Build 类型
  • 当前热启动周期的启动时间
  • 总的启动时间(包括所有的热启动周期)
  • 当前的热启动周期

GET /stats

按需输出所有的统计内容。这个命令对于本地调试非常有用。Histograms 能够计算分位数并进行输出,即 P0,P25,P50,P75,P90,P99,P99.9和P100。每个分位数都是一种(区间值,累计值)的形式,区间值代表的是上次刷新以后的数值,累计值代表的是该实例启动以后的总计值。统计概览章节中提供了更多这方面的内容。

GET /stats?format=json

使用 JSON 格式输出 /stats,编程访问统计信息时可以使用这一格式。Counter 和 Gauge 会以(键,值)的形式出现。Histograms 会放在 “histograms” 节点之下,其中包含了 “supported_quantiles” 节点,其中列出了支持的分位数,以及这些分位数的计算结果。只有包含值的 Histograms 才会输出。

如果一个 Histogram 在这一区间没有更新,那么这一区间的所有分位数输出都是空的。

下面是一个输出样例:

  1. {
  2. "histograms": {
  3. "supported_quantiles": [
  4. 0, 25, 50, 75, 90, 95, 99, 99.9, 100
  5. ],
  6. "computed_quantiles": [
  7. {
  8. "name": "cluster.external_auth_cluster.upstream_cx_length_ms",
  9. "values": [
  10. {"interval": 0, "cumulative": 0},
  11. {"interval": 0, "cumulative": 0},
  12. {"interval": 1.0435787, "cumulative": 1.0435787},
  13. {"interval": 1.0941565, "cumulative": 1.0941565},
  14. {"interval": 2.0860023, "cumulative": 2.0860023},
  15. {"interval": 3.0665233, "cumulative": 3.0665233},
  16. {"interval": 6.046609, "cumulative": 6.046609},
  17. {"interval": 229.57333,"cumulative": 229.57333},
  18. {"interval": 260,"cumulative": 260}
  19. ]
  20. },
  21. {
  22. "name": "http.admin.downstream_rq_time",
  23. "values": [
  24. {"interval": null, "cumulative": 0},
  25. {"interval": null, "cumulative": 0},
  26. {"interval": null, "cumulative": 1.0435787},
  27. {"interval": null, "cumulative": 1.0941565},
  28. {"interval": null, "cumulative": 2.0860023},
  29. {"interval": null, "cumulative": 3.0665233},
  30. {"interval": null, "cumulative": 6.046609},
  31. {"interval": null, "cumulative": 229.57333},
  32. {"interval": null, "cumulative": 260}
  33. ]
  34. }
  35. ]
  36. }
  37. }

GET /stats?format=prometheus

或者换个方式 GET /stats/prometheus,使用 Prometheus v0.0.4 格式输出统计数据。这样就可以和 Prometheus 进行集成了。当前只有 Counter 和 Gauge 会进行输出。未来的更新中会输出 Histogram。

GET /runtime

使用 JSON 格式按需输出所有运行时数值。运行时配置一节中,更详细的讲述了这些值的配置和使用。输出内容包括活动的重载后的运行时数值,以及每个键的堆栈。空字符串代表没有值,来自堆栈的最终有效值会用单独的键来做出标识,例如下面的输出:

  1. {
  2. "layers": [
  3. "disk",
  4. "override",
  5. "admin",
  6. ],
  7. "entries": {
  8. "my_key": {
  9. "layer_values": [
  10. "my_disk_value",
  11. "",
  12. ""
  13. ],
  14. "final_value": "my_disk_value"
  15. },
  16. "my_second_key": {
  17. "layer_values": [
  18. "my_second_disk_value",
  19. "my_disk_override_value",
  20. "my_admin_override_value"
  21. ],
  22. "final_value": "my_admin_override_value"
  23. }
  24. }
  25. }

POST /runtime_modify?key1=value1&key2=value2&keyN=valueN

通过提交的参数对运行时数值进行添加或修改。要删除一个之前加入的键,只需要使用一个空值即可。注意这种删除操作,只适用于这一端点中使用重载方式加入的值;从磁盘中载入的值是能通过重载进行修改,无法删除。

注意

使用 /runtime_modify 端点要当心,这一变更是即时生效的。保障管理界面的安全性至关重要。