Envoy 运维调试

---

统计信息分类

Envoy 的主要目标之一是使网络易于理解。 Envoy 会发出大量其配置方式的统计信息。 通常，统计信息分为三类：

• Downstream : Downstream统计信息 与传入的连接/请求有关。 它们由 listeners 、 HTTP connection manager 、 TCP proxy filter 等发出。

• Upstream : Upstream统计信息 与传出的连接/请求有关。 它们由 connection pools 、 router filter 、 TCP proxy filter 等发出。

• Server : Server统计信息 描述了 Envoy Server实例 的工作方式。 诸如 Server的正常运行时间 或 已分配内存量 之类的统计信息在这里列出。

从 v2 API 开始， Envoy 支持自定义的可插拔的 sinks(接收器) . Envoy 包含了一些标准的接收器实现 。 一些接收器还支持带有 tags/dimensions 的统计信息。

统计信息 通过规范的字符串形式进行标识。 可以从这些字符串中动态剥离部分出来以成为 tags(标签) . 用户可以通过 Tag Specifier 配置此行为。

---

统计信息的值类型

Envoy 发出三种类型的值作为统计信息:

• Counters : 只增不减的整数。例如 total requests(总访问数)
• Gauges : 可增可减的整数。例如 currently active requests(当前活跃的请求数)
• Histograms : 按百分比汇总的整数。例如 upstream request time(上游请求时间)

在内部， counters 和 gauges 定期批量写入以提升性能。 Histograms 在接收时即刻写入。

---

命令行选项

Envoy 可以由 JSON配置文件 和 命令行选项 驱动。 下面是 Envoy 支持的命令行选项（节选了部分）:

--admin-address-path <path string>
  (optional) The output file path where the admin address and port will be written.

-l <string>, --log-level <string>
  (optional) The logging level. Non developers(非开发人员) should generally never set this option.   
  See the help text for the available log levels and the default.

--component-log-level <string>
  (optional) The comma separated list(逗号分隔的列表) of logging level per component.   
  Non developers(非开发人员) should generally never set this option.   
  For example, if you want upstream component to run at debug level and connection component to run at trace level,   
  you should pass "upstream:debug,connection:trace"(示例) to this flag.   
  See ALL_LOGGER_IDS in /source/common/common/logger.h for a list of components.

--log-path <path string>
  (optional) The output file path where logs should be written.   
  This file will be re-opened when SIGUSR1 is handled.   
  If this is not set, log to stderr(默认值).

--log-format <format string>
--log-format-escaped

--version
  显示版本号

--mode <string>
  serve/validate , serve 是默认值，如果希望验证配置文件的有效性，使用 --mode validate  

---

Administration interface

Envoy 暴露了一个本地管理界面，该界面可用于 查询和修改 服务器的不同方面：

v3 API reference 配置本地管理界面:

{
  "access_log_path": "...",
  "profile_path": "...",
  "address": "{...}",
  "socket_options": []
}

注意
当前形式的管理界面不仅 允许执行破坏性操作 （例如，关闭服务器），而且还可能 公开私有信息 （例如，统计信息，群集名称，证书信息等）。
因此 仅允许通过安全网络访问管理界面 非常重要。 将访问管理界面的主机仅连接到安全网络也很重要（即，避免CSRF攻击）。 这涉及设置适当的防火墙，或者最好只允许通过本地主机访问管理侦听器。 这可以通过v2配置完成，如下所示：

admin:
  access_log_path: /tmp/admin_access.log
  profile_path: /tmp/envoy.prof
  address:
    socket_address: { address: 127.0.0.1, port_value: 9901 }

将来，其他安全选项将添加到管理界面。
所有变动服务器配置的操作 必须以 HTTP POST 发送。 通过GET请求时返回 HTTP 400（无效请求）响应。

提示:
使用 ?format=json 以json序列化 。
具有默认值的字段不会呈现 。 例如，对于 /clusters?format=json ，当断路器阈值优先级字段的值为DEFAULT优先级时，将忽略该字段，如下所示：

{
 "thresholds": [
  {
   "max_connections": 1,
   "max_pending_requests": 1024,
   "max_requests": 1024,
   "max_retries": 1
  },
  {
   "priority": "HIGH",
   "max_connections": 1,
   "max_pending_requests": 1024,
   "max_requests": 1024,
   "max_retries": 1
  }
 ]
}

---

管理界面的endpoint

• GET /
  呈现 HTML主页，包含指向所有可用选项链接的表

• GET /help
  打印所有可用的选项

• GET /certs
  列出所有加载的TLS证书，包含文件名称、序列号、subject备用名称和过期天数。

• GET /clusters
  列出所有配置的 cluster manager clusters . 该信息包含所有发现的 upstream主机以及它们的统计信息 。
  该信息有助于 调试服务发现的问题

  • Cluster manager information
    version info 是最新的CDS更新的版本信息字符串。如果 Envoy 没有配置 CDS , 则输出将显示为 version_info::static
  • Cluster wide information
    • circuit breakers 是所有优先级的设置信息
    • 如果安装了 detector ，则包含其异常检测信息。 包含 Currently average success(当前平均成功率) 和 ejection threshold(弹出阈值) 。 这两个信息的值都可能是 -1 ， 如果在最新的 :ref/interval<envoy_v3_api_field_config.cluster.v3.OutlierDetection.interval> 中没有足够的数据计算它们。
    • added_via_api flag : false 表示cluster是通过静态配置的， true 表示cluster是通过 CDS api 添加的
  • Per host 统计信息:
    包含 cx_total(Total Connections) 、 cx_active 、 cx_connect_fail 、 rq_total 、 rq_timeout 、 rq_success 、 rq_error 、 rq_active 、 healthy 、 zone 、 canary 、 success_rate 信息
  • host 健康状态:
    healthy 表示健康， /failed_active_hc 表示 active health check失败， failed_eds_health 表示host被EDS标记为失败， /failed_outlier_check 表示 outlier detection check 失败。

• GET /clusters?format=json

• GET /config_dump
  打印当前从各个Envoy组件加载的配置信息，以JSON格式。
  注意1 ： 配置信息可能包含 TLS证书 。 在打印配置之前，Envoy将尝试从找到的所有证书中 删除 private_key和password字段 。 这依赖于配置是强类型的protobuf消息。 如果您的Envoy配置使用了 废弃的 config字段 （类型为 google.protobuf.Struct ），请更新为建议使用的 typed_config字段 （类型为 google.protobuf.Any ），以确保正确处理了敏感数据。
  注意2 : 打印出来的内容是 v2alpha 版本的内容，因此不保证内容是 stable(稳定的)

• GET /config_dump?include_eds

• GET /config_dump?mask={}

• GET /config_dump?resource={}

• GET /config_dump?resource={}&mask={}
  示例
  /config_dump?resource=dynamic_active_clusters&mask=cluster.name

• GET /contention
  打印Envoy的互斥锁争用统计信息，前提是启用了互斥锁追踪，查看 --enable-mutex-tracing

• POST /cpuprofiler 启用或禁用

• POST /heapprofiler 启用或禁用

• POST /healthcheck/fail 使入站健康检查失败

• POST /healthcheck/ok 使入站健康检查成功

• GET /hot_restart_version 查阅 --hot-restart-version

• GET /init_dump

• GET /init_dump?mask={}

• GET /listeners

• GET /listeners?format=json

• POST /logging
  在特定的记录器或所有记录器上启用/禁用不同的日志记录级别。

  • 要设定所有的logger的级别，使用 level=<desired_level>
  • 要设定特定的logger的级别，使用 <logger_name>=<desired_level>
  • 要列出logger，使用 无参数的方式访问

• GET /memory

• POST /quitquitquit

• POST /reset_counters
  将所有计数器重置为零。 在调试过程中，这与 GET /stats 一起很有用。
  请注意，这不会删除任何发送到statsd的数据。 它仅影响 GET /stats 命令的本地输出。

• POST /drain_listeners
  drain 所有 listeners

  • POST /drain_listeners?inboundonly
    Listener 中的 traffic_direction 用来决定 listener 是 inbound 还是 outbound
  • POST /drain_listeners?graceful
    当 drain listener 时，进入一个 graceful 时间段 。 该行为可以通过配置选项或命令行选项( --drain-time-s 和 --drain-strategy ) 配置

• GET /server_info

• GET /ready
  返回200状态码以及LIVE表示服务器正常，或者503返回码以及错误信息

• GET /stats
  打印所有的统计信息。 此命令对于本地调试非常有用。

  • GET /stats?usedonly
    输出Envoy已更新的统计信息（Counter至少增加一次，Gauge至少改变一次，Histogram至少增加一次）。
  • GET /stats?filter=regex
    /stats?filter=server 将返回包含 server单词 的统计信息。
    使用开始和结束锚定符号 /stats?filter=^server.concurrency$

• GET /stats?format=json

• GET /stats?format=json&usedonly

• GET /stats?format=prometheus
  GET /stats/prometheus
  GET /stats/recentlookups
  POST /stats/recentlookups/enable
  POST /stats/recentlookups/disable
  POST /stats/recentlookups/clear

• GET /runtime

• POST /runtime_modify?key1=value1&key2=value2&keyN=valueN
  添加或修改运行时值。
  要删除先前添加的键，请使用空字符串作为值。
  请注意，删除仅适用于通过此端点添加的覆盖值， 从磁盘加载的值可以通过覆盖进行修改，但不能删除。

• GET /hystrix_event_stream
  该endpoint用于作为 Hystrix dashboard的 stream source 。

• POST /tap
  该Endpoint用于配置活动的Tap会话。 仅当配置了有效的tap extension 并且extension被配置为接受管理配置时，此功能才可用。
  tap的含义应该是 窃听、复制会话

• POST /reopen_logs
  触发重新打开所有访问日志。 行为类似于SIGUSR1处理。