Learn how to install and manage Wavefront proxies.

In most cases, a Wavefront proxy must be running in your installation before metrics begin streaming to Wavefront from a host or application.

We offer several deployment options. During development, a single proxy is often sufficient for all data sources. In production, place a team of proxies behind a load balancer.

Scripted and Manual Install

You can install a proxy:

  • As part of an integration. Many integrations send data to a Wavefront proxy. You’re prompted to select a proxy that already exists in your enviornment or add a proxy.
  • Explicitly from the UI, discussed below.
  • Explicitly as a package install. Installing a proxy manually gives steps for different use cases, including install on hosts with limited network connectivity.
  • If you install a proxy into a container, you might have to customize your setup.

If you don’t use the Wavefront UI to install the proxy, the installation procedures might require:

  • A Wavefront API URL in the format https://<wavefront_instance>.wavefront.com/api/
  • An API token, which you generate for your instance.

Proxy Host Requirements

  • Internet access - run timeout 3s curl -fIsS <wavefront_api_url> from the host and make sure you get a response and not a timeout.
  • Networking - For metrics, the proxy uses port 2878 by default. If you want to change this default, or if you want to set up ports for histograms or trace data, see Set the Listener Port for Metrics, Histograms, and Traces.
  • Memory - The proxy does not use a lot of CPU, memory, or storage. However, we recommend running the proxy on a host with at least 4GB of free memory.
  • Operating system
    • Linux: We’ve tested the proxy with the following versions.
      • Ubuntu 14.04, 16.04, 18.04
      • CentOS 6.5, 7
      • RHEL 6, 7
      • Debian 7, 8, 9, 10
      • Amazon Linux
    • Mac - MacOS Sierra (10.12) and later
    • Windows - Windows 8 and later

You can also run a proxy in a Docker or Kubernetes container.

Proxy Installation

Many users install a proxy when they set up an integration. For other situation, we support several installation options.

Install a Proxy from the UI

To install and run a proxy on a Linux, Mac, or Windows host, or in a Docker container on a host:

  1. Open the Wavefront application UI.
  2. Select Browse > Proxies.
  3. Select Add > New Proxy at the top of the filter bar.
  4. Click the [Linux | Mac | Windows | Docker ] tab.
  5. (Windows Only) Download the proxy.
  6. Copy the script and run it on your host.
  7. After the proxy contacts the Wavefront service, the proxy name displays under “Checking for new proxies…” and the button label changes to Done.
  8. Click Done and verify that your proxy is listed on the Proxies page. If not, follow the steps in Managing Proxy Services to start the proxy is running.

Install a Proxy on a Kubernetes Container

If you set up the Kubernetes integration, adding a proxy is part of the setup:

  1. Log in to your Wavefront instance.
  2. Click Integrations and click Kubernetes.
  3. Click the Setup tab and follow the instructions to deploy a Wavefront proxy in Kubernetes and deploy Wavefront Collector for Kubernetes.

Depending on your environment, you might have to customize proxy settings for best performance.

Scripted Proxy Installation

In Linux hosts, you can use the Wavefront CLI to install the Wavefront proxy and to perform certain management tasks.

In Mac and Linux hosts, you can select the integration for the host and run only the command that installs the proxy, not the command that installs the Telegraf agent.

Installing a proxy manually gives steps for performing package installs, including installation on hosts with limited network connectivity.

Manage Proxy Services

After installing a proxy, you can start and stop the proxy service, check service status, and view the logs that are generated by the service. See Logging for customizing your proxy, including its log configuration options.

Start and Stop a Proxy

You can start and stop a proxy by running the following commands on the proxy host:

  • Linux

    $ service wavefront-proxy [start | stop | restart]
  • Mac

    $ brew services [start | stop | restart] wfproxy
  • Docker

    $ docker [start | stop ] <proxy_container_id>
  • Windows

    $ cd C:\Program Files (x86)\Wavefront\bin
    $ ./nssm.exe [start | stop] WavefrontProxy

Check Proxy Service Status

To check if the proxy is running, run the following commands on the proxy host:

  • Linux

    $ service wavefront-proxy status

    You can view the proxy log at /var/log/wavefront/wavefront.log.

  • Mac

    $ brew services list

    You can view the proxy log at /usr/local/var/log/wavefront/wavefront.log.

  • Windows

    $ cd C:\Program Files (x86)\Wavefront\bin
    $ ./nssm.exe status WavefrontProxy

    You can view the proxy log at Program Files (x86)\Wavefront\wavefront.log.

  • Docker

    $ docker ps

    To view the proxy log, run docker logs <proxy_container_id>.

Set the Listener Port for Metrics, Histograms, and Traces

The proxy listens on different ports for different kinds of data. These ports are specified in the proxy configuration file.

  • For metrics, you do not need to edit this file if you plan to ingest metrics using the default port (2878).
  • For histogram distributions or trace data, you must edit this file, uncomment the port properties, and restart the proxy. You can optionally set nondefault port numbers.

You set the following properties to configure proxy ports:

  • For metrics, set pushListenerPorts. Required only if you want to change to a port other than 2878.
  • For histograms, set histogramDistListenerPorts for data in histogram format. The recommended port number is 2878 (proxy 4.29 and later) or 40000 (earlier proxy versions). See Histogram Proxy Ports for port numbers for histograms in Wavefront data format.
  • For trace data, set traceListenerPorts. The recommended port number is 30000.

Export Data Queued at the Proxy

When you send too much data or if there is a network error, data starts to queue at the Wavefront proxy and create a backlog.

Use the following command to export the data that is queued at the proxy. Once the data is exported, you can make changes to the data, like removing the data that is not required, and send it back to the Wavefront proxy.

/opt/wavefront/wavefront-proxy/proxy-jre/java -jar /opt/wavefront/wavefront-proxy/wavefront-push-agent.jar --f /etc/wavefront/wavefront-proxy/wavefront.conf --exportQueuePorts <ports> --exportQueueOutputFile <outputFileNamePrefix> --exportQueueRetainData false
Parameter Description
exportQueuePorts Comma separated list of ports that listen to the data sent to the proxy. Can be a single port.
exportQueueOutputFile Prefix you want the output files to have. If the prefix is wfproxy, the name of the file is wfproxy.<FILE_NAME>.txt
exportQueueRetainData When set to false, exports the data and removes the data from the backlog. Default is true.
<div markdown="span" class="alert alert-info" role="alert"> Note: Make a backup of the files you export. If you set exportQueueRetainData to false, the exported files are the only copies you have of the backlog.</div>


/opt/wavefront/wavefront-proxy/proxy-jre/java -jar /opt/wavefront/wavefront-proxy/wavefront-push-agent.jar --f /etc/wavefront/wavefront-proxy/wavefront.conf --exportQueuePorts 2878,3000 --exportQueueOutputFile wfproxy --exportQueueRetainData false

The example:

  • Exports the data queued at ports 2878 and 3000.
  • Creates output files that have the prefix wfproxy, such as wfproxy.points.2878.0.txt.
  • Deletes all data that’s currently in the proxy queue.

Test a Proxy

You can test that a proxy is receiving and sending data as follows:

  1. Run the following command:

    echo -e "test.metric 1 source=test_host\n" | nc <wavefront_proxy_address> 2878

    where <wavefront_proxy_address> is the address of your Wavefront proxy.

  2. In the Wavefront UI, select Browse > Metrics.
  3. In the Metrics field, type test.metric.
  4. Click test.metric to display a chart of the metric.

Upgrade a Proxy

Wavefront frequently releases new proxy versions with new features. See Proxy Release Notes.

To upgrade, select Browse > Proxies > Add New Proxy. If an older version of the proxy exists, this process replaces it.

For Linux and Mac OS, can also upgrade a proxy from the command line as follows:

Linux sudo apt-get update && sudo apt-get install wavefront-proxy
Linux (RPM) yum update wavefront-proxy
Mac OS brew update && brew upgrade wfproxy

Uninstall a Proxy

When you upgrade a proxy, we uninstall the older version for you. You can also uninstall a proxy explicitly:

Windows The precise process depends on the version of Windows you're using. You follow the process for uninstalling programs.
  1. Click Start, and then click Control Panel.
  2. Under Programs, click Uninstall a program.
  3. Select Telegraf and click Uninstall at the top.
  4. Select Wavefront Proxy and click Uninstall at the top.
Linux sudo apt-get remove wavefront-proxy sudo apt-get remove telegraf
Linux (RPM) sudo yum remove wavefront-proxy sudo yum remove telegraf
Mac OS bash -c "$(curl -s https://raw.githubusercontent.com/wavefrontHQ/homebrew-wavefront/master/sh/uninstall.sh)"

Proxy Troubleshooting

Error Reason Resolution
You see "java: command not found" in wavefront.log. Java is either not installed, or is not in your path. Install Java using your local package manager, and make sure that your path includes the Java binary.
You see "Cannot fetch daemon configuration from remote server: org.jboss.resteasy.client.exception.ResteasyIOException: IOException" in wavefront.log. You may have an incorrect server URL in your wavefront.conf file; you may have blocked the outgoing connection to that server URL (port 443); or the Wavefront servers may be down. Run curl <wavefrontServerUrl> from the machine running the proxy, where <wavefrontServerUrl> is the full URL (including "https://) provided to you by Wavefront and in your wavefront.conf file.
You see "Cannot post work unit result to Wavefront servers. Will enqueue and retry later." in wavefront.log. You may have an incorrect server URL in your wavefront.conf file; you may have blocked the outgoing connection to that server URL (port 443). Run curl <wavefrontServerUrl> from the machine running the proxy, where <wavefrontServerUrl> is the full URL (including "https://") provided to you by Wavefront and in your wavefront.conf file.
You see "Exception in thread "main" java.lang.UnsupportedClassVersionError: com/sunnylabs/GraphiteValidator : Unsupported major.minor version 51.0" in wavefront.log. You are using Java 1.6 or lower instead of Java 1.7. Upgrade Java to 1.7 through your local package manager.
You see "Exception in thread "Thread-2" java.net.BindException: Address already in use" in wavefront.log. You already have another process listening on port 2878, or may have started two proxies accidentally. Use the ps command to find and delete any existing proxies, and then start the proxy again.
You can't run telnet localhost 2878; the connection is refused. Ensure that you don't have an iptables rule blocking the traffic. Ensure that the proxy is running. Ensure that you are running telnet localhost 2878 on the machine where the proxy is running. Use the ps command to make sure that the proxy is running, and examine your iptables rules to ensure that TCP port 2878 is accessible locally.