DEV Community

Cover image for Using Envoy Proxy’s PostgreSQL & TCP Filters to Collect Yugabyte SQL Statistics
Jimmy Guerrero for YugabyteDB

Posted on • Updated on

Using Envoy Proxy’s PostgreSQL & TCP Filters to Collect Yugabyte SQL Statistics

Note: This is a cross post of my colleague Sid Choundhury's blog that was originally published here.

Layer 7 proxies like NGINX and HAProxy have been popular since the mid-2000s. The term “proxy” refers to their role as an intermediary for the traffic between an application client and an application server. The “layer 7” classification comes from the fact that these proxies take routing decisions based on URLs, IPs, TCP/UDP ports, cookies, or any information present in messages sent over a layer 7 (aka application layer) networking protocol like HTTP and gRPC. Modern applications use these proxies for a variety of needs including load balancing, security, and web acceleration.

What is Envoy Proxy?

Envoy is a layer 7 proxy and communication bus designed for large modern service oriented architectures. Its home page has the following definition:

Originally built at Lyft, Envoy is a high performance C++ distributed proxy designed for single services and applications, as well as a communication bus and “universal data plane” designed for large microservice “service mesh” architectures. Built on the learnings of solutions such as NGINX, HAProxy, hardware load balancers, and cloud load balancers, Envoy runs alongside every application and abstracts the network by providing common features in a platform-agnostic manner. When all service traffic in an infrastructure flows via an Envoy mesh, it becomes easy to visualize problem areas via consistent observability, tune overall performance, and add substrate features in a single place.

As the recently published Dropbox’s migration from NGINX to Envoy highlights, Envoy is rapidly becoming the default proxy for cloud native applications that need higher performance, observability, extensibility, security, building and testing, and last but not least, deep features (such as HTTP/2, gRPC, and egress proxying). It was the third CNCF project to reach the graduated status, following Kubernetes and Prometheus, and has gained widespread adoption in a relatively short period of time.

Why use Envoy’s PostgreSQL filter?

Envoy supports configuration of multiple traffic listeners where each listener is composed of one or more filter chains. An individual filter chain is selected to process the incoming data based on the filter’s match criteria (which includes connection parameters such as destination port/IP, transport protocol name, source port/IP, and more). When a new connection is received on a listener, the matching filter chain is selected and instantiated. The filters then begin processing subsequent events. This generic listener architecture is used to perform the vast majority of different proxy tasks that Envoy is used for including rate limiting, TLS client authentication, HTTP connection management, raw TCP proxy, and more. One such task relevant to database deployments is the ability to instrument the wire protocol of popular databases such as MySQL, MongoDB, Kafka, and Amazon DynamoDB. PostgreSQL was missing from this list but the latest v1.15 release from July 2020 solved that problem by adding a PostgreSQL proxy filter. This filter is based on PostgreSQL frontend/backend protocol version 3.0, which was introduced in PostgreSQL 7.4.

The main goal of the PostgreSQL filter is to capture runtime statistics while remaining completely transparent to the database server. There is no additional monitoring software to deploy or manage in order to collect these vital statistics! As listed in the official docs, the filter currently offers the following features:

  • Decode non SSL traffic, ignore SSL traffic
  • Decode session information
  • Capture transaction information, including commits and rollbacks
  • Expose counters for different types of statements (INSERTs, SELECTs, DELETEs, UPDATEs, etc.)
  • Count frontend, backend, and unknown messages
  • Identify errors and backend responses

YugabyteDB is fully compatible with the PostgreSQL wire protocol and SQL syntax given that its SQL query layer is based on a fork of PostgreSQL 11.2’s query layer. As a result, YugabyteDB is able to leverage the PostgreSQL filter from Envoy without any modifications whatsoever. The rest of this post outlines the instructions to run the most basic YugabyteDB with Envoy setup (including the PostgreSQL & TCP filters) using Docker Compose. Official Envoy sandboxes use the same approach to test out different features and highlight sample configurations.

YugabyteDB with Envoy in action

Install Docker

Ensure that you have docker and docker-compose installed on your local machine. Docker Desktop can be the simplest way to achieve this goal.

Create the “YugabyteDB with Envoy” stack using docker-compose

Create a working directory

mkdir yugabyte-envoy
Enter fullscreen mode Exit fullscreen mode

Create the envoy.yaml

Copy the following contents into a file named envoy.yaml.

  - name: yb_listener
        port_value: 1999
    - filters:
      - name:
          stat_prefix: ysql
      - name: envoy.tcp_proxy
          stat_prefix: tcp_ysql
          cluster: yb_cluster

  - name: yb_cluster
    connect_timeout: 1s
    type: strict_dns
      cluster_name: yb_cluster
      - lb_endpoints:
        - endpoint:
                address: ysql
                port_value: 5433

  access_log_path: "/dev/null"
      port_value: 8001
Enter fullscreen mode Exit fullscreen mode

As we can see above, we have configured an Envoy listener on port 1999 that has a filter chain with two filters, namely PostgreSQL and TCP.

Create the envoy dockerfile

Copy the following contents into a file named Dockerfile-proxy. When built and instantiated, we will have an envoyproxy container that will use the envoy.yaml configuration we created in the previous step.

FROM envoyproxy/envoy-dev:latest

COPY ./envoy.yaml /etc/envoy.yaml
RUN chmod go+r /etc/envoy.yaml
CMD /usr/local/bin/envoy -c /etc/envoy.yaml -l debug
Enter fullscreen mode Exit fullscreen mode

Create the yugabytedb dockerfile

Copy the following contents into a file named Dockerfile-yugabyte. When built and instantiated, we will have a single YugabyteDB container with the PostgreSQL-compatible YSQL API available on port 5433.

FROM yugabytedb/yugabyte:latest

CMD ["/home/yugabyte/bin/yugabyted","start","--daemon=false"]
Enter fullscreen mode Exit fullscreen mode

Create the docker-compose.yaml

Copy the following contents into a file named docker-compose.yaml.

version: "3.7"

      context: .
      dockerfile: Dockerfile-proxy
          - envoy
      - "1999"
      - "8001"
      - "1999:1999"
      - "8001:8001"

      context: .
      dockerfile: Dockerfile-yugabyte
          - ysql
      - "5433"
      - "5433:5433"

    name: envoymesh
Enter fullscreen mode Exit fullscreen mode

Start the docker-compose stack

docker-compose pull
docker-compose up --build -d
docker-compose ps
Enter fullscreen mode Exit fullscreen mode

Output from the ps command is shown below.

Name                      Command                     State                Ports                                              
yugabyte_proxy_1      / /bin ...   Up      ...>1999/tcp,>8001/tcp                                                                    
yugabyte_yugabyte_1   /home/yugabyte/bin/yugabyt ...   Up      ...>5433/tcp, ...
Enter fullscreen mode Exit fullscreen mode

As we can see, two containers have been spun up on a common envoymesh network.

  1. yugabyte_yugabyte_1 is the YugabyteDB container that is ready to interact with PostgreSQL clients on port 5433.

  2. yugabyte_proxy_1 is the Envoy proxy container that is running the PostgreSQL proxy on the 1999 port. Requests to this port get automatically redirected to the port 5433 on the YugabyteDB container.

Connect using ysqlsh via the envoy listener

We are now ready to connect to the YugabyteDB cluster using ysqlsh. However, instead of directly connecting to the 5433 port of the YugabyteDB container, we will connect to the Envoy proxy at the 1999 port.

docker run --rm -it --network envoymesh yugabytedb/yugabyte /home/yugabyte/bin/ysqlsh "sslmode=disable" -h envoy -p 1999
Enter fullscreen mode Exit fullscreen mode

As highlighted in the Envoy docs, the current PostgreSQL filter decodes only non-SSL (aka unencrypted) traffic and ignores any SSL/encrypted traffic. The sslmode=disable option shown above is mandatory for Envoy to treat the PostgreSQL traffic as unencrypted even though the cluster has been set up without any encryption. Since this behavior is reproducible with both PostgreSQL 12 and 11.2 (Yugabyte SQL is based on a fork of this version), this is most likely a bug in the filter implementation.

Run basic YSQL commands

Let’s create a table.

    url VARCHAR(255) NOT NULL,
    name VARCHAR(255) NOT NULL,
    description VARCHAR (255),
      last_update DATE
Enter fullscreen mode Exit fullscreen mode

Now let us insert four rows into the table we created.

INSERT INTO links (url, name)
VALUES('','PostgreSQL Tutorial');

INSERT INTO links (url, name)
VALUES('','O''Reilly Media');

INSERT INTO links (url, name)
VALUES('','YugabyteDB Docs');

INSERT INTO links (url, name)
VALUES('','YugabyteDB Blog') 
Enter fullscreen mode Exit fullscreen mode

We can now run a SELECT statement to get all the rows we inserted.

SELECT * FROM links;
Enter fullscreen mode Exit fullscreen mode

We can also run a SELECT statement to get the count of rows we inserted.

SELECT count(*) FROM links;
Enter fullscreen mode Exit fullscreen mode

Review YSQL statistics collected by Envoy’s filters

Each of the two filters configured provide us with statistics relevant to the data they observe. All these statistics are available on the Envoy stats page http://localhost:8001/stats.

Using the PostgreSQL filter

Since we gave the stats prefix as ysql, we see all the statistics with the overall prefix as postgres.ysql. The ones that we can easily verify based on the queries we executed in the ysqlsh session we created are highlighted with "**".

postgres.ysql.errors: 0
postgres.ysql.errors_error: 0
postgres.ysql.errors_fatal: 0
postgres.ysql.errors_panic: 0
postgres.ysql.errors_unknown: 0
postgres.ysql.messages: 45
postgres.ysql.messages_backend: 37
postgres.ysql.messages_frontend: 8
postgres.ysql.messages_unknown: 0
postgres.ysql.notices: 0
postgres.ysql.notices_debug: 0
postgres.ysql.notices_info: 0
postgres.ysql.notices_log: 0
postgres.ysql.notices_notice: 0
postgres.ysql.notices_unknown: 0
postgres.ysql.notices_warning: 0
**postgres.ysql.sessions: 1**
postgres.ysql.sessions_encrypted: 0
**postgres.ysql.sessions_unencrypted: 1**
**postgres.ysql.statements: 7**
postgres.ysql.statements_delete: 0
**postgres.ysql.statements_insert: 4**
**postgres.ysql.statements_other: 1**
postgres.ysql.statements_parse_error: 2
postgres.ysql.statements_parsed: 5
**postgres.ysql.statements_select: 2**
postgres.ysql.statements_update: 0
**postgres.ysql.transactions: 7**
**postgres.ysql.transactions_commit: 7**
postgres.ysql.transactions_rollback: 0
Enter fullscreen mode Exit fullscreen mode

Using the TCP filter

The TCP statistics relevant to YSQL are available with the tcp.tcp_ysql prefix. As we can see, the statistics are at the network level including bytes transmitted and bytes received.

tcp.tcp_ysql.downstream_cx_no_route: 0
tcp.tcp_ysql.downstream_cx_rx_bytes_buffered: 33
tcp.tcp_ysql.downstream_cx_rx_bytes_total: 693
tcp.tcp_ysql.downstream_cx_total: 1
tcp.tcp_ysql.downstream_cx_tx_bytes_buffered: 0
tcp.tcp_ysql.downstream_cx_tx_bytes_total: 991
tcp.tcp_ysql.downstream_flow_control_paused_reading_total: 0
tcp.tcp_ysql.downstream_flow_control_resumed_reading_total: 0
tcp.tcp_ysql.idle_timeout: 0
tcp.tcp_ysql.upstream_flush_active: 0
tcp.tcp_ysql.upstream_flush_total: 0
Enter fullscreen mode Exit fullscreen mode

Remove all the containers in the stack

We can remove the containers we have previously spun up using the command below.

docker rm -f $(docker ps -aq)
Enter fullscreen mode Exit fullscreen mode


The recently released PostgreSQL filter from Envoy Proxy makes it extremely easy for developers and operations engineers to collect SQL statistics from YSQL, YugabyteDB’s PostgreSQL-compatible fully-relational distributed SQL API. The filter runs inside the Envoy Proxy sidecar container and works by simply sniffing the network traffic in a manner that is completely transparent to the database server. As a result, developers and operations engineers can leverage the integration without deploying and managing any additional software.

We welcome all users to give the integration a try today and provide us feedback via GitHub and Slack.

Top comments (0)