How Envoy 1.15’s New Postgres Plugin Enables Zero‑Config Observability

Design Intent and Rationale

The primary goal of the Postgres filter, described in issue #9107, is to increase network visibility by decoding the PostgreSQL wire protocol inside an Envoy filter, allowing extraction of per‑second query counts, query types, and performance data without installing agents on the database server.

Why a New Approach?

Traditional monitoring tools rely on pull‑based queries, offering coarse‑grained snapshots and requiring additional load, configuration changes, or even database restarts. They also struggle with incremental metrics such as latency percentiles, and may increase Postgres CPU usage.

Plugin Features in Envoy 1.15

The first release adds observability for Postgres by parsing traffic and publishing metrics to any Prometheus‑compatible sink. Exported metrics include upstream/downstream connections, session and transaction counts (encrypted vs. unencrypted), statement types (SELECT, INSERT, UPDATE, DELETE, others), and notification/error message sub‑counters.

Current Limitations

The filter cannot decode SSL‑encrypted traffic, so it only works with plaintext connections. Consequently, users must disable SSL when generating workload for accurate metric collection.

Configuration and Usage

To enable the filter, attach the envoy.filters.network.postgres_proxy typed config to a filter chain that also contains a TCP proxy filter. A minimal YAML snippet is:

filter_chains:
- filters:
  - name: envoy.filters.network.postgres_proxy
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.network.postgres_proxy.v3alpha.PostgresProxy
      stat_prefix: postgres
  - name: envoy.tcp_proxy
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
      stat_prefix: tcp
      cluster: postgres_cluster

Run Envoy with the configuration:

getenvoy run standard:1.15.0 -- -c postgres.yaml

Query the statistics endpoint:

curl -s http://localhost:8000/stats | grep egress_postgres

Generate load with pgbench (SSL must be disabled):

pgbench -i -s10 -d "postgresql://postgres@localhost:54322/postgres?sslmode=disable"
pgbench -c50 -n -T3600 "postgresql://postgres@localhost:54322/postgres?sslmode=disable"

After load, re‑query the stats to see non‑zero counters such as postgres.egress_postgres.messages, sessions_unencrypted, and statement breakdowns.

Prometheus Scraping Example

scrape_configs:
- job_name: 'envoy'
  scrape_interval: 5s
  metrics_path: /stats/prometheus
  static_configs:
  - targets: ['localhost:8000']

Sample PromQL queries illustrate transactions per second, read/write rates, statement rates, and session counts, with accompanying Grafana screenshots (images omitted for brevity).

Practical Use Cases

The plugin enables capacity planning, performance troubleshooting, query error detection, and schema validation by feeding high‑resolution metrics into Grafana dashboards. It has already been integrated into StackGres, an open‑source Kubernetes‑native Postgres platform that proxies all traffic through Envoy.

Future Roadmap

Planned enhancements include SSL termination support (issue #10942) to offload TLS from Postgres, and metadata tagging of protocol packets for advanced routing decisions (issue #11065). Additional features such as aggregated query histograms and per‑query performance tracing are under development.

Acknowledgments

Thanks to Matt Klein for creating Envoy, Dhi Aurrahman for the initial POC, Christoph Pakulski for extensive contributions, and OnGres for sponsoring the open‑source effort.