Learn how to install and run 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.

You can install a proxy as part of an in-product integration or standalone. This topic describes various methods for installing Wavefront proxies and for managing proxy services.

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.
  • 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
    • Linux
      • Ubuntu 12.04, 14.04, 16.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

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:

  1. Open the Wavefront application UI.
  2. Select Browse > Proxies.
  3. Select Add > New Proxy at the top of the filter bar. The Add a Wavefront Proxy screen displays.
  4. Click the [Linux | Mac | Windows | Docker ] tab.
  5. (Windows Only) Download the proxy.
  6. Copy the script and run it on your host.

    Note On Windows, do not run the installer .exe. Run the script instead.

  7. After the proxy contacts the Wavefront server, the proxy name displays under “Checking for new proxies…” and the button label changes to Done.
  8. Click Done. The Proxies page displays. Verify that your proxy is listed. If not, follow the steps in Managing Proxy Services to make sure the proxy is running.

Installing Proxies on Multiple Linux Hosts

Ansible is an open-source automation engine that automates software provisioning, configuration and management, and application deployment. The Wavefront Ansible role installs and configures the Wavefront proxy, which allows you to automate Wavefront proxy installation on multiple Linux hosts. For details, see the Ansible in-product integration setup instructions.

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.

If a proxy doesn’t start or doesn’t register with Wavefront and you need help, contact Support. Consider checking Proxy Troubleshooting first.

Starting and Stopping a Proxy

Run 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
    

Checking 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.

  • Docker

    $ docker ps
    

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

  • 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.

Testing a Proxy

You can test that a proxy is receiving and sending data by sending it a JSON payload as follows:

  1. In the proxy configuration file, set the JSON listener port to 3878.

    jsonListenerPorts=3878
    
  2. Run the following command:

    curl --header "Content-type: application/json" \
    'http://<wavefront_proxy_address>:3878/?h=test_host&d=now' \
    -d '{"test.metric":{"value":1,"tags":{"key1":"v1","key2":"v2"}}}'
    

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

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

Running a Proxy in a Docker Container

To run a Docker container using the Docker run command, follow the instructions in Installing a Proxy on a Single Host. If you want to use Docker Compose or Kubernetes to run the proxy, set the WAVEFRONT_URL and WAVEFRONT_TOKEN properties, as follows:.

Docker Compose

wavefront:  
    hostname: wavefront-proxy
    container_name: wavefront-proxy
    ports:  
      - "3878:3878"
      - "2878:2878"
      - "4242:4242"
    environment:
      WAVEFRONT_URL: <wavefront_api_url>
      WAVEFRONT_TOKEN: <wavefront_api_token>
    image: wavefronthq/proxy:latest
    restart: always

Kubernetes

apiVersion: v1
kind: ReplicationController
metadata:
  labels:
    app: wavefront-proxy
    name: wavefront-proxy
  name: wavefront-proxy
  namespace: default
spec:
  replicas: 1
  selector:
    app: wavefront-proxy
  template:
    metadata:
      labels:
        app: wavefront-proxy
    spec:  
      containers:
      - name: wavefront-proxy
        image: wavefronthq/proxy:latest
        imagePullPolicy: Always
        env:
        - name: WAVEFRONT_URL
          value: <wavefront_api_url>
        - name: WAVEFRONT_TOKEN
          value: <wavefront_api_token>
        ports:  
        - containerPort: 2878
          protocol: TCP
        - containerPort: 4242
          protocol: TCP

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 kill 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.