Riverwatch

A telegraf input plugin for capturing USGS stream data.

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation

About The Project

Riverwatch is a Telegraf exec input plugin that fetches data for a specified list of stream sites from USGS and inserts it into Telegraf's metric database. From there the data can be exported using any of the available Telegraf output plugins to an appropriate storage and/or graphing application. The example above was created using Prometheus and Grafana to create time series plots of various metrics.

I wrote this plugin to monitor conditions on various rivers in my region for various outdoor sports such as kayaking, fishing, etc, and to monitor the general health of my region's rivers.

(back to top)

Built With

This plugin was written under Python 3.11.5 but should work under any stable Python3. Additional module requirements are listed in requirements.txt.

(back to top)

Getting Started

Prerequisites

You will need a working telegraf installation on a host or container with Python3 installed.

Installation

Clone the repo to your telegraf host, change into the repo directory and install the necessary Python modules by running pip install -r requirements.txt.

The plugin has been pre-populated with a list of monitoring sites in the Carolinas, but you can find your own list of sites by going to the USGS National Water Dashboard and browsing the map for sites of interest to you. The site code will be a multi-digit number like "Monitoring location USGS 03508050". Add this number to the "sites" dictionary in riverwatch.py.

Add the following to your telegraf.conf file:

[[inputs.exec]]
commands = ["python3 /path/to/riverwatch/repo/riverwatch.py"]
timeout = "15s"
name_suffix = "_riverwatch"
data_format = "influx"

Restart telegraf and after a couple minutes you should see the _riverwatch metrics showing up in whatever telegraf output endpoints you have configured. In my example using the prometheus_output_plugin the endpoint at :9273/metrics looks like this:

# HELP temperature_riverwatch_value Telegraf collected metric
# TYPE temperature_riverwatch_value untyped
temperature_riverwatch_value{host="rome",siteID="02176930",siteName="Chattooga River At Burrells Ford Nr Pine Mtn"} 2.3
temperature_riverwatch_value{host="rome",siteID="03441000",siteName="Davidson River Near Brevard"} 1.9
temperature_riverwatch_value{host="rome",siteID="03451500",siteName="French Broad River At Asheville"} 2.6
temperature_riverwatch_value{host="rome",siteID="03456991",siteName="Pigeon River Near Canton"} 2.2

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)