Administration interface

Envoy exposes a local administration interface that can be used to query and modify different aspects of the server:

• v1 API reference
• v2 API reference

GET /

Print a menu of all available options.

GET /certs

List out all loaded TLS certificates, including file name, serial number, and days until expiration.

GET /clusters

List out all configured cluster manager clusters. This information includes all discovered upstream hosts in each cluster along with per host statistics. This is useful for debugging service discovery issues.

• Cluster manager information

  • version_info string – the version info string of the last loaded CDS update. If envoy does not have CDS setup, the output will read version_info::static.

  Cluster wide information

  • circuit breakers settings for all priority settings.
  • Information about outlier detection if a detector is installed. Currently success rate average, and ejection threshold are presented. Both of these values could be -1 if there was not enough data to calculate them in the last interval.
  • added_via_api flag – false if the cluster was added via static configuration, true if it was added via the CDS api.

  Per host statistics

  Name	Type	Description
  cx_total	Counter	Total connections
  cx_active	Gauge	Total active connections
  cx_connect_fail	Counter	Total connection failures
  rq_total	Counter	Total requests
  rq_timeout	Counter	Total timed out requests
  rq_success	Counter	Total requests with non-5xx responses
  rq_error	Counter	Total requests with 5xx responses
  rq_active	Gauge	Total active requests
  healthy	String	The health status of the host. See below
  weight	Integer	Load balancing weight (1-100)
  zone	String	Service zone
  canary	Boolean	Whether the host is a canary
  success_rate	Double	Request success rate (0-100). -1 if there was not enough request volume in the interval to calculate it

  Host health status

  A host is either healthy or unhealthy because of one or more different failing health states. If the host is healthy the healthy output will be equal to healthy.

  If the host is not healthy, the healthy output will be composed of one or more of the following strings:

  /failed_active_hc: The host has failed an active health check.

  /failed_outlier_check: The host has failed an outlier detection check.

GET /cpuprofiler

Enable or disable the CPU profiler. Requires compiling with gperftools.

GET /healthcheck/fail

Fail inbound health checks. This requires the use of the HTTP health check filter. This is useful for draining a server prior to shutting it down or doing a full restart. Invoking this command will universally fail health check requests regardless of how the filter is configured (pass through, etc.).

GET /healthcheck/ok

Negate the effect of GET /healthcheck/fail. This requires the use of the HTTP health check filter.

GET /hot_restart_version

See --hot-restart-version.

GET /logging

Enable/disable different logging levels on different subcomponents. Generally only used during development.

GET /quitquitquit

Cleanly exit the server.

GET /reset_counters

Reset all counters to zero. This is useful along with GET /stats during debugging. Note that this does not drop any data sent to statsd. It just effects local output of the GET /stats command.

GET /routes?route_config_name=<name>

This endpoint is only available if envoy has HTTP routes configured via RDS. The endpoint dumps all the configured HTTP route tables, or only ones that match the route_config_name query, if a query is specified.

GET /server_info

Outputs information about the running server. Sample output looks like:

envoy 267724/RELEASE live 1571 1571 0

The fields are:

• Process name
• Compiled SHA and build type
• Health check state (live or draining)
• Current hot restart epoch uptime in seconds
• Total uptime in seconds (across all hot restarts)
• Current hot restart epoch

GET /stats

Outputs all statistics on demand. This includes only counters and gauges. Histograms are not output as Envoy currently has no built in histogram support and relies on statsd for aggregation. This command is very useful for local debugging. See here for more information.

• GET /stats?format=json

Outputs /stats in JSON format. This can be used for programmatic access of stats.

• GET /stats?format=prometheus

Outputs /stats in Prometheus v0.0.4 format. This can be used to integrate with a Prometheus server. Currently, only counters and gauges are outputed. Histograms will be outputed in a future update.