Monitoring Envoy Proxy

Edit online

Instana can help you to collect both infrastructure metrics from Envoy Proxy instances and distributed traces of requests that pass through them.

Envoy logo

After you install the Instana host agent, Envoy Proxy sensor is automatically installed and configured. You can view the metrics that are related to Envoy Proxy in the Instana UI with a custom dashboard widget. You can view these metrics only after you configure the Envoy Proxy sensor as outlined in the Monitoring configuration of Envoy Proxy section.

For Envoy versions earlier than 1.30, you can use Instana's Distributed Tracing feature. To use the Distributed Tracing feature, you must complete the configuration steps in the Distributed Tracing configuration of Envoy Proxy section.

If you are using Envoy 1.30 or later, you must use Envoy OTel tracing support and configure it to connect to the Instana backend. For more information, see Configuring OpenTelemetry data ingestion.

To assist with the configuration of the Envoy OTel configuration, check out the demonstration repository at Envoy Proxy Instana OTel Tracing Demo. This guidance applies only to standalone Envoy deployments. Configure Istio-managed Envoy instances by using Istio OpenTelemetry support.

Supported information

Edit online

Supported operating systems

Edit online

For Envoy Proxy sensor, the supported operating systems are consistent with host agents' requirements, which can be checked in the Supported operating systems section of each host agent, such as Supported operating systems for Linux.

For Envoy Proxy tracing, the following operating systems are supported:

Operating system Architecture Bitness
Debian: 12, 11 x86_64 64 bit
Ubuntu: LTS 24.04, 22.04 x86_64 64 bit

Support for Ubuntu 20.04 is discontinued in CPP sensor 1.12.0 and later.

Support for Amazon (2, 2022, and 2023), CentOS 7, Ubuntu 18.04, and Debian 10 is discontinued in CPP sensor 1.11.0 and later.

Supported Envoy Proxy versions and platforms

Edit online

Envoy Proxy sensor and Envoy Proxy tracing have different version and platform requirements.

  • Envoy Proxy sensor supports metrics and configuration data for Envoy Proxy 1.14.1 and later versions with Linux distributions running on x86_64 architecture.

    Envoy Proxy metrics are available only in custom dashboard widgets.

  • Instana provides Distributed Tracing support for the following Envoy Proxy versions and operating systems with a support policy of 45 days:

    Versions OS ENVOY Tracer version
    1.12.x and 1.13.x Glibc-based Linux, Alpine-based Linux (musl libc) only 1.3.0
    >=1.15.x and <=1.21.1 Glibc-based Linux >= 1.5.0
    1.21.2, 1.21.3 and 1.22.0 Glibc-based Linux >= 1.7.0
    >=1.21.4 and <=1.21.6, >=1.22.0 and <=1.22.6, >=1.23.0 and <=1.23.3, 1.24.0 and 1.24.1 Glibc-based Linux >= 1.8.0
    1.22.7, 1.22.8, 1.23.4, 1.23.5, 1.24.2, 1.24.3, 1.25.1, 1.25.2, >=1.26.0 and <=1.26.2 Glibc-based Linux >= 1.8.1
    >=1.22.9 and <=1.22.11, >=1.23.5 and <=1.23.10, >=1.24.4 and <=1.24.8, >=1.25.3 and <=1.25.7, >=1.26.3 and <=1.26.6, 1.27.0, 1.28.0 Glibc-based Linux >= 1.8.2
    1.23.11, 1.23.12, >=1.24.9 and <=1.24.12, >=1.25.8 and <=1.25.11, 1.27.1 Glibc-based Linux >= 1.8.3
    1.26.7, 1.27.2, 1.27.3, 1.28.1, 1.29.0, 1.29.1 Glibc-based Linux >= 1.9.0
    1.26.8, >=1.27.4 and <=1.27.7, >=1.28.2 and <=1.28.6, >=1.29.2 and <=1.29.8 Glibc-based Linux >= 1.9.1
    >=1.29.9 and <=1.29.12 Glibc-based Linux >= 1.12.0

    Notes:

    • For Distributed Tracing, Envoy Proxy 1.12 and 1.13 are supported only by Envoy Proxy sensor 1.3.0. Envoy Proxy sensor 1.5.0 and later versions support only Envoy Proxy 1.15 to 1.29.x. You are encouraged to upgrade Envoy Proxy if you still use its old versions because no feature development is provided for old Envoy Proxy versions.
    • Support for the propagation of W3C Trace Context headers is available from Envoy Tracer 1.8.0.

Supported and unsupported tracing scenarios

Edit online

Review the following scenarios to determine if your Envoy deployment is supported for Instana tracing.

Supported scenarios

Edit online

Instana supports Envoy tracing in the following deployment scenarios:

  • Standalone Envoy deployments: Envoy proxy instances deployed independently (not managed by Istio or other service mesh control planes).

  • Direct deployment on hosts or VMs: Envoy instances running directly on Linux hosts or virtual machines.

  • Containerized standalone Envoy: Envoy running in containers (Docker or Kubernetes pods) as a standalone proxy, not managed by a service mesh control plane.

Unsupported scenarios

Edit online

The following Envoy deployment scenarios are not supported for Instana tracing:

  • Envoy deployed as part of Istio service mesh: Envoy proxy instances that are deployed and managed by Istio are not supported for Instana native tracing. This includes:

    • Envoy sidecars injected by Istio
    • Istio ingress gateways
    • Istio egress gateways
    • Any Envoy instance controlled by the Istio control plane (istiod)

  • Envoy as API gateway in managed services: Envoy instances deployed as part of managed API gateway services where you don't have direct control over the Envoy configuration.

Monitoring configuration of Envoy Proxy

Edit online

To collect Envoy Proxy metrics, Instana uses the admin interface. To enable this admin interface, configure your Envoy Proxy server by using an admin interface address based on the admin interface document. Start the server by using the -c <envoy-config-file-path>.yaml or --config-path <envoy-config-file-path>.yaml command-line argument. For example, -c /etc/envoy/envoy.yaml. Containerized environments and YAML configuration parsing are supported since Envoy Proxy sensor 1.1.0.

Monitoring configuration with Envoy Proxy sensor 1.0.2 or earlier

Edit online

Envoy Proxy sensor 1.0.2 or earlier require the --admin-address-path <path-to-file-envoy-can-write-to> command-line argument additionally. For example, --config-path /etc/envoy/envoy.yaml --admin-address-path /tmp/envoy-admin.address. To make the monitoring work, the Instana agent and Envoy Proxy must run in the same namespace, and the admin IP address 127.0.0.1 must be set. It is encouraged to upgrade the Envoy Proxy sensor.

Viewing metrics

Edit online

After you complete the configuration steps in the Monitoring configuration of Envoy Proxy section, you can view metrics that are related to Envoy Proxy in the Instana UI.

To view the metrics, complete the following steps:

  1. In the sidebar of the Instana UI, select Infrastructure.
  2. Click a specific monitored host.

Then, you can see a host dashboard with all the collected metrics and monitored processes.

Distributed Tracing configuration of Envoy Proxy

Edit online

To use Distributed Tracing of Envoy Proxy, complete the following steps:

  1. Download the Instana binary files for the supported distributions of Envoy Proxy in the Envoy Distributed Tracing binary files page.

  2. After the tracer binary file is downloaded, place it to a location that can be read by Envoy Proxy, such as /opt/envoy/libcxx-libinstana_sensor.so. Then, add a tracing section to the configuration YAML file of Envoy Proxy as follows:

    static_resources:
  listeners:
    - address:
      ...
      filter_chains:
        - filters:
            - name: envoy.filters.network.http_connection_manager
              typed_config:
                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
                ...

  3. Configure the path to the tracer binary file with the library key, and configure your service name with the service key as follows:

                    tracing:
                  provider:
                    name: envoy.tracers.dynamic_ot
                    typed_config:
                      "@type": type.googleapis.com/envoy.config.trace.v3.DynamicOtConfig
                      library: /opt/envoy/libcxx-libinstana_sensor.so
                      config:
                        service: your-service-name

For more information, see the official Envoy Proxy documentation.

For how to use Distributed Tracing, refer to the configuration examples at the envoy-tracing repository page.

Envoy Tracing example

Edit online

Instana provides a public repository to preview the tracing function of Envoy Proxy sensor. For more information, see envoy-tracing.

Troubleshooting

Edit online

Monitoring issue type: envoy_access_metrics_endpoint_failed

To resolve this issue, configure an admin interface as described in the admin interface document.

Monitoring issue type: envoy_missing_configuration_admin_address_path

To resolve this issue, upgrade the Envoy Proxy sensor of the Instana agent to the latest version. Support for containerized environments and YAML configuration parsing is available since version 1.1.0.