OpenWeatherMap

Client Library + Prometheus Exporter

This is a mono-repo for two rust crates:

| Crate | Description | | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | openweathermapclient | A rust library for querying weather readings from OpenWeatherMap's free v2.5 API | | openweathermapexporter | A prometheus exporter to query weather readings for many locations and publis their values in as metrics prometheus exposition format. |

openweathermap_client

docs.rs | crates.io

openweathermap_client is a rust library that provides a client for querying OpenWeatherMap's free version 2.5 weather API.

Features:

• Binds query results into structs derived from OpenWeatherMap's weather-data docs using serde.
• Supports requesting results in OWM's Standard, Metric, or Imperial unit systems.
• Supports requesting that the API translate of city names and weather descriptions into supported languages.
• Cross platform. Tested to confirm it runs on Windows, MacOS, and Linux and on many hardware architectures (will be)
• Queries over https using hyper (some existing exporters don't).
  • Doesn't require openssl to be installed, allowing it to be used on weird architectures, because it uses hyper_rustls.
• Is panic-free.

Usage

See the library docs for example usage. To obtain an OpenWeatherMap API Key, see this section.

openweathermap_exporter

docs.rs | crates.io

The openweathermap_exporter is a prometheus exporter to query weather readings for many locations and publis their values in as metrics prometheus exposition format.

This uses openweathermap_client☝ to query weather from the API.

Installation

Currently, no binaries or container images are being built. The only way to install it (assuming you have rust already installed) is via:

cargo install openweathermap_exporter

Automatic, building of

• release binaries (to be manually installed, cargo binstalled, or packaged)
• cross-platform container images

is in the works as are several other features.

Get An API Key

To obtain an OpenWeatherMap API Key, see this section.

Create A Config File

Create a config file. Start with the the template below (also available in source here ) This file should be named owm_exporter.yaml and placed in the working directory from where you plan to run the exporter or in the user's home (~/ , %USERPROFILE%) directory.

```yaml

listen:

address: 0.0.0.0

port: 9001

owm: api_key: # you've got to provide an api key

units: metric # metric is the default

language: en # en is the default

The exporter doesn't currently warn if the duration of all the calls exceeds the duration

of poll_interval_seconds. It's up to you to reconfigure so that all readings can be read

withing the poll_interval_seconds timeframe. This will probably be updated in a future

release.

pollintervalseconds: 60

maxcallsper_minute: 60

cities: - name: Bangkok countrycode: TH - name: New York, NY countrycode: US

coordinates: - lat: -0.829278 lon: -90.982067 display_name: The Galapagos

locations: - id: 3936456 ```

Run The Exporter

By default the exporter is pretty quiet. It uses env_logger to control the log level.

When first using the exporter, consider running with info or debug level

RUST_LOG=info cargo run

Available log levels are error, warn, info, debug, trace.

Verify Metrics Are Published

All metrics returned by the free v2.5 API will be exported for scraping. At the moment any route will suffice to load the metrics. If you have not changed the default listen options you can test the your running instance with:

curl http://localhost:9001/

Metric Names

Because metric names are encouraged to contain unit names:

A metric name...

• ...should have a suffix describing the unit

openweathermap_exporter metrics all include the unit of the measurement in their name and HELP text. If you change the setting for owm.units in your config file, the names of the metrics and their HELP text will change accordingly.

See Example Of Metric Names to see how they're named and what information is available in the labels.

Example Dashboard

I don't have a generalized dashboard template ready yet. But will share one soon. This is what my weather dashboard looks like:

Example Of Metric Names

This is a scrape using the example template config file.

```rust

HELP owmcloudinesspercent % cloudiness

TYPE owmcloudinesspercent gauge

owmcloudinesspercent{location="New York",q="New York, NY,US",readingid="5128581",readinglat="40.7143",readinglon="-74.006",readingname="New York"} 0 owmcloudinesspercent{location="Lima",id="3936456",readingid="3936456",readinglat="-12.0432",readinglon="-77.0282",readingname="Lima"} 100 owmcloudinesspercent{location="The Galapagos",lat="-0.829278",lon="-0.829278",displayname="The Galapagos",readingid="6295630",readinglat="-0.8293",readinglon="-0.8293",readingname="Globe"} 96 owmcloudinesspercent{location="Bangkok",q="Bangkok,TH",readingid="1609350",readinglat="13.75",readinglon="100.5167",reading_name="Bangkok"} 100

HELP owmtemperaturedegrees_celsius Temperature in °C

TYPE owmtemperaturedegrees_celsius gauge

owmtemperaturedegreescelsius{location="The Galapagos",lat="-0.829278",lon="-0.829278",displayname="The Galapagos",readingid="6295630",readinglat="-0.8293",readinglon="-0.8293",readingname="Globe"} 26.1 owmtemperaturedegreescelsius{location="Lima",id="3936456",readingid="3936456",readinglat="-12.0432",readinglon="-77.0282",readingname="Lima"} 18.28 owmtemperaturedegreescelsius{location="Bangkok",q="Bangkok,TH",readingid="1609350",readinglat="13.75",readinglon="100.5167",readingname="Bangkok"} 27.76 owmtemperaturedegreescelsius{location="New York",q="New York, NY,US",readingid="5128581",readinglat="40.7143",readinglon="-74.006",reading_name="New York"} 16.02

HELP owmhumiditypercent % Humidity

TYPE owmhumiditypercent gauge

owmhumiditypercent{location="Bangkok",q="Bangkok,TH",readingid="1609350",readinglat="13.75",readinglon="100.5167",readingname="Bangkok"} 83 owmhumiditypercent{location="The Galapagos",lat="-0.829278",lon="-0.829278",displayname="The Galapagos",readingid="6295630",readinglat="-0.8293",readinglon="-0.8293",readingname="Globe"} 79 owmhumiditypercent{location="Lima",id="3936456",readingid="3936456",readinglat="-12.0432",readinglon="-77.0282",readingname="Lima"} 76 owmhumiditypercent{location="New York",q="New York, NY,US",readingid="5128581",readinglat="40.7143",readinglon="-74.006",reading_name="New York"} 56

HELP owmtemperaturefeelslikedegrees_celsius Perceived temperature in °C

TYPE owmtemperaturefeelslikedegrees_celsius gauge

owmtemperaturefeelslikedegreescelsius{location="Lima",id="3936456",readingid="3936456",readinglat="-12.0432",readinglon="-77.0282",readingname="Lima"} 18.15 owmtemperaturefeelslikedegreescelsius{location="New York",q="New York, NY,US",readingid="5128581",readinglat="40.7143",readinglon="-74.006",readingname="New York"} 15.14 owmtemperaturefeelslikedegreescelsius{location="Bangkok",q="Bangkok,TH",readingid="1609350",readinglat="13.75",readinglon="100.5167",readingname="Bangkok"} 31.93 owmtemperaturefeelslikedegreescelsius{location="The Galapagos",lat="-0.829278",lon="-0.829278",displayname="The Galapagos",readingid="6295630",readinglat="-0.8293",readinglon="-0.8293",reading_name="Globe"} 26.1

HELP owmwindspeedmetersper_second Wind speed in meters/second

TYPE owmwindspeedmetersper_second gauge

owmwindspeedmeterspersecond{location="New York",q="New York, NY,US",readingid="5128581",readinglat="40.7143",readinglon="-74.006",readingname="New York"} 8.75 owmwindspeedmeterspersecond{location="Bangkok",q="Bangkok,TH",readingid="1609350",readinglat="13.75",readinglon="100.5167",readingname="Bangkok"} 0.08 owmwindspeedmeterspersecond{location="The Galapagos",lat="-0.829278",lon="-0.829278",displayname="The Galapagos",readingid="6295630",readinglat="-0.8293",readinglon="-0.8293",readingname="Globe"} 5.8 owmwindspeedmeterspersecond{location="Lima",id="3936456",readingid="3936456",readinglat="-12.0432",readinglon="-77.0282",reading_name="Lima"} 2.57

HELP owmvisibilitymeters Visibility in meters, 10000 max

TYPE owmvisibilitymeters gauge

owmvisibilitymeters{location="Lima",id="3936456",readingid="3936456",readinglat="-12.0432",readinglon="-77.0282",readingname="Lima"} 10000 owmvisibilitymeters{location="The Galapagos",lat="-0.829278",lon="-0.829278",displayname="The Galapagos",readingid="6295630",readinglat="-0.8293",readinglon="-0.8293",readingname="Globe"} 10000 owmvisibilitymeters{location="New York",q="New York, NY,US",readingid="5128581",readinglat="40.7143",readinglon="-74.006",readingname="New York"} 10000 owmvisibilitymeters{location="Bangkok",q="Bangkok,TH",readingid="1609350",readinglat="13.75",readinglon="100.5167",reading_name="Bangkok"} 3882

HELP owmwinddirection_degrees Wind direction in degrees (0-360)

TYPE owmwinddirection_degrees gauge

owmwinddirectiondegrees{location="The Galapagos",lat="-0.829278",lon="-0.829278",displayname="The Galapagos",readingid="6295630",readinglat="-0.8293",readinglon="-0.8293",readingname="Globe"} 178 owmwinddirectiondegrees{location="New York",q="New York, NY,US",readingid="5128581",readinglat="40.7143",readinglon="-74.006",readingname="New York"} 330 owmwinddirectiondegrees{location="Lima",id="3936456",readingid="3936456",readinglat="-12.0432",readinglon="-77.0282",readingname="Lima"} 250 owmwinddirectiondegrees{location="Bangkok",q="Bangkok,TH",readingid="1609350",readinglat="13.75",readinglon="100.5167",reading_name="Bangkok"} 196

HELP owmtimestampseconds Timestamp of last reading in seconds since UNIX epoch

TYPE owmtimestampseconds gauge

owmtimestampseconds{location="Lima",id="3936456",readingid="3936456",readinglat="-12.0432",readinglon="-77.0282",readingname="Lima"} 1666883173 owmtimestampseconds{location="The Galapagos",lat="-0.829278",lon="-0.829278",displayname="The Galapagos",readingid="6295630",readinglat="-0.8293",readinglon="-0.8293",readingname="Globe"} 1666883459 owmtimestampseconds{location="New York",q="New York, NY,US",readingid="5128581",readinglat="40.7143",readinglon="-74.006",readingname="New York"} 1666883199 owmtimestampseconds{location="Bangkok",q="Bangkok,TH",readingid="1609350",readinglat="13.75",readinglon="100.5167",reading_name="Bangkok"} 1666883178

HELP owmpressurehpa Atmospheric pressure in hPa

TYPE owmpressurehpa gauge

owmpressurehpa{location="The Galapagos",lat="-0.829278",lon="-0.829278",displayname="The Galapagos",readingid="6295630",readinglat="-0.8293",readinglon="-0.8293",readingname="Globe"} 1010 owmpressurehpa{location="Bangkok",q="Bangkok,TH",readingid="1609350",readinglat="13.75",readinglon="100.5167",readingname="Bangkok"} 1011 owmpressurehpa{location="Lima",id="3936456",readingid="3936456",readinglat="-12.0432",readinglon="-77.0282",readingname="Lima"} 990 owmpressurehpa{location="New York",q="New York, NY,US",readingid="5128581",readinglat="40.7143",readinglon="-74.006",reading_name="New York"} 1019

HELP owmwindgustmetersper_second Wind gust speed in meters/second

TYPE owmwindgustmetersper_second gauge

owmwindgustmeterspersecond{location="The Galapagos",lat="-0.829278",lon="-0.829278",displayname="The Galapagos",readingid="6295630",readinglat="-0.8293",readinglon="-0.8293",readingname="Globe"} 5.96 owmwindgustmeterspersecond{location="Bangkok",q="Bangkok,TH",readingid="1609350",readinglat="13.75",readinglon="100.5167",reading_name="Bangkok"} 0.31

HELP owmquerysuccess Whether the most recent query for a location's weather succeeded (0 or 1)

TYPE owmquerysuccess gauge

owmquerysuccess{q="New York, NY,US"} 1 owmquerysuccess{q="Bangkok,TH"} 1 owmquerysuccess{lat="-0.829278",lon="-0.829278",displayname="The Galapagos"} 1 owmquery_success{id="3936456"} 1

HELP owmapicalltimemilliseconds Histogram of successful call times per location in milliseconds

TYPE owmapicalltimemilliseconds summary

owmapicalltimemilliseconds{quantile="0"} 59 owmapicalltimemilliseconds{quantile="0.5"} 58.997791357811785 owmapicalltimemilliseconds{quantile="0.9"} 61.99786870677149 owmapicalltimemilliseconds{quantile="0.95"} 61.99786870677149 owmapicalltimemilliseconds{quantile="0.99"} 61.99786870677149 owmapicalltimemilliseconds{quantile="0.999"} 61.99786870677149 owmapicalltimemilliseconds{quantile="1"} 65 owmapicalltimemillisecondssum 1941 owmapicalltimemillisecondscount 20 ```

Getting An OpenWeatherMap API Key

To obtain an API key, go to https://openweathermap.org/home/sign_in to sign in or create an account. Once logged in, select your user name from the top-right menu bar and then My API Keys. Use the Create key form to create a new key.