In most cases, a Wavefront proxy must be running in your installation before metrics begin streaming to Wavefront from a host or application.
You can install a proxy as part of a built-in integration. Even collector agent integrations, such as the Telegraf integration, install a proxy. But for some custom integrations, you install the proxy yourself. This topic describes methods for installing Wavefront proxies and for managing proxy services.
If you don’t use the Wavefront UI to install the proxy, the installation procedures might require a Wavefront API URL
<wavefront_api_url> in the format
https://<wavefront_instance>.wavefront.com/api/ and an API token. To get an API token, see Generating an API Token.
Note Some installation procedures automatically configure these properties for you.
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 Configuring Proxy Ports for Metrics, Histograms, and Traces.
- Memory - you don’t need a dedicated host for running the Wavefront proxy. 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
- 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)
- Windows - Windows 8 and later
You can also run a proxy in a Docker or Kubernetes container.
If we don’t install a proxy for you as part of integration setup, you can install a proxy explicitly. You can script installation on Linux and Mac OS. You can also run a proxy in a Docker container.
Note: You can use a single proxy to pass input from many collector agents to the Wavefront service. In production, consider using two proxies behind a load balancer. See Proxy Deployment Options.
Installing a Proxy on a Single Host
To install and run a proxy on a Linux, Mac, or Windows host, or in a Docker container on a host:
- Open the Wavefront application UI.
- Select Browse > Proxies.
- Select Add > New Proxy at the top of the filter bar.
- Click the [Linux | Mac | Windows | Docker ] tab.
- (Windows Only) Download the proxy.
Copy the script and run it on your host.
Note On Windows, do not run the installer
.exefile. Run the script instead.
- After the proxy contacts the Wavefront service, the proxy name displays under “Checking for new proxies…” and the button label changes to Done.
- 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.
If you want to run a proxy in a Kubernetes container, log in to Wavefront, click Integrations, click Kubernetes, click the Setup tab, and follow the instructions to deploy a Wavefront proxy in Kubernetes, create a proxy service, and deploy Heapster.
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.
Managing 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 log configuration options.
Starting and Stopping a Proxy
You can start and stop a proxy by running the following commands on the proxy host:
$ service wavefront-proxy [start | stop | restart]
$ brew services [start | stop | restart] wfproxy
$ docker [start | stop ] <proxy_container_id>
$ cd C:\Program Files (x86)\Wavefront\bin $ ./nssm.exe [start | stop] WavefrontProxy
Checking Proxy Service Status
To check if the proxy is running, run the following commands on the proxy host:
$ service wavefront-proxy status
You can view the proxy log at
$ brew services list
You can view the proxy log at
$ 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 ps
To view the proxy log, run
docker logs <proxy_container_id>.
Configuring Proxy Ports 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
pushListenerPort. Required only if you want to change to a port other than 2878.
- For histograms, set
histogramDistListenerPortfor data in histogram format. The recommended port number is 40,000. See Histogram Proxy Ports for port numbers for histograms in Wavefront data format.
- For trace data, set
traceListenerPort. The recommended port number is 30,000.
Note: If you are instrumenting your application with a Wavefront SDK to send data to the proxy, make sure the proxy’s port settings match the port numbers you specify during SDK setup.
Testing a Proxy
You can test that a proxy is receiving and sending data as follows:
Run the following command:
echo -e "test.metric 1 source=test_host\n" | nc <wavefront_proxy_address> 2878
<wavefront_proxy_address>is the address of your Wavefront proxy.
- In the Wavefront UI, select Browse > Metrics.
- In the Metrics field, type
test.metricto display a chart of the metric.
Upgrading a Proxy
Wavefront releases new proxy versions with new features periodically. See Proxy Release Notes
To upgrade the environment, you can select Browse > Proxies > Add New Proxy. If an older version of the proxy exists, this process replaces it.
Note On Windows systems, you might have to uninstall the existing proxy first. Use the uninstall process for Wavefront Proxy on the Windows system you’re using.
For Linux and Mac OS, can also upgrade a proxy from the command line as follows:
|You see "java: command not found" in
||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
||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
|You see "Cannot post work unit result to Wavefront servers. Will enqueue and retry later." in
||You may have an incorrect server URL in your
|You see "Exception in thread "main" java.lang.UnsupportedClassVersionError:
com/sunnylabs/GraphiteValidator : Unsupported major.minor version 51.0" in
||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
||You already have another process listening on port 2878, or may have started two proxies accidentally.||Use the
|You can't run
||Ensure that you don't have an iptables rule blocking the traffic. Ensure that the proxy is running. Ensure that you are running