Weather Data

Many collected metrics depend on the weather: the power drawn by heating and cooling follows the outdoor temperature, solar generation follows irradiance, and cooling load in a data center rises on hot, humid days. The weather subagent (weather.nsm) brings weather into NetXMS as ordinary DCI values, collected next to the metrics that depend on it. Their history can then be analysed against its cause: shown on the same graph or dashboard, combined in a script DCI, or read by external analytics for trend prediction.

Besides current conditions, the subagent collects hourly forecasts (up to 16 days with Open-Meteo), so the expected weather is known in advance — for example, to estimate tomorrow’s heating demand or solar output.

The data comes from public weather services for configured locations. The agent that loads the subagent only needs outbound HTTPS access to the service; the locations do not have to be anywhere near the agent.

Providers

The subagent supports three weather services. The provider is selected per location, because they differ in coverage and in which variables they report.

Name Service Notes

openmeteo

Open-Meteo

Default. Global coverage, the only provider with direct radiation and ensemble forecasts. The free tier needs no key but is for non-commercial use only; set ApiKey to use a commercial subscription.

metno

MET Norway Locationforecast 2.0

Global coverage, best for Nordic locations. No key, but requires an identifying UserAgent. No solar radiation and no ensemble forecasts. Hourly resolution for roughly the first two days, coarser steps beyond.

brightsky

Bright Sky

DWD open data: observations mainly from Germany, forecasts worldwide but from far fewer stations outside Germany. Only stations within 50 km of the location are used, so a location with none in range gets no data. No key. Reports global (shortwave) radiation but no direct radiation and no ensemble forecasts.

Open-Meteo and MET Norway serve model data, not measurements. Open-Meteo current values come from its 15-minute current-conditions data; MET Norway current values are the hourly forecast entry at or before the current time. The subagent re-selects that entry from the cached forecast on every polling round, so the current values keep moving between forecast downloads, which for MET Norway arrive hourly in the Nordic area and about every 6 hours elsewhere. Open-Meteo current-conditions data is used as long as it is not older than that entry. Bright Sky fills past hours with station measurements once DWD publishes them, where an observing station is in range; otherwise, and for the most recent hour, its values are forecasts.

Coordinates are sent with four decimal places. Open-Meteo and MET Norway map them to a cell of their model grid, so nearby locations can return identical data; Bright Sky uses forecast and observing stations within 50 km.

Data from MET Norway and from DWD (through Bright Sky) is licensed under CC BY 4.0; publishing data derived from it requires attribution to the Norwegian Meteorological Institute or Deutscher Wetterdienst respectively.

Configuration

Loading the Subagent

SubAgent = weather.nsm

Example

SubAgent = weather.nsm

[Weather]
Provider = openmeteo
UserAgent = AcmeMonitoring/1.0 [email protected]
Location = datacenter-hel: 60.1699, 24.9384
Location = datacenter-ams: 52.3676, 4.9041
PollInterval = 900
ForecastDays = 2

[Weather/Location/datacenter-osl]
Latitude = 59.9139
Longitude = 10.7522
Provider = metno

[Weather/Location/datacenter-fra]
Latitude = 50.1109
Longitude = 8.6821
Provider = brightsky

[Weather] Section

Parameter Default Description

Provider

openmeteo

Default provider: used for Location entries, for location blocks without Provider, and for raw coordinate instances. Case-insensitive. An unknown name stops the subagent from loading.

ApiKey

empty

Open-Meteo commercial subscription key. When set, Open-Meteo requests go to the commercial hosts (customer-api.open-meteo.com, customer-ensemble-api.open-meteo.com) and carry the key. Empty means the free tier.

UserAgent

NetXMS Agent/<version>

HTTP User-Agent sent to all providers. MET Norway rejects generic user agents, so set an identifying value with contact information (an application name and an email address or URL) when any location uses metno; without it the subagent logs a warning and MET Norway requests fail.

Location

—

A location in the form name: latitude, longitude, using the default provider. Can be repeated. Malformed entries are skipped with a warning.

PollInterval

900

Seconds between polling rounds over all locations. Minimum 60.

ForecastDays

2

Forecast horizon in days, 1 to 16.

RequestTimeout

30

Timeout for one HTTP request, in seconds.

EnableEnsemble

no

Also fetch ensemble forecasts for Open-Meteo locations (one extra request per location per round). Required for Weather.ForecastEnsemble.

EnsembleModel

icon_seamless

Open-Meteo ensemble model.

[Weather/Location/NAME] Sections

Each section defines one location named NAME. Use this form to select a provider for an individual location.

Parameter Description

Latitude

Latitude in decimal degrees (-90 to 90). Required.

Longitude

Longitude in decimal degrees (-180 to 180). Required.

Provider

Provider for this location. Defaults to the Provider value of the [Weather] section. A location with an unknown provider is skipped with a warning.

Location entries and location sections can be mixed. Location names are case-insensitive; sections are read after the Location entries, so a section replaces a Location entry with the same name.

Locations as Metric Instances

Every metric takes a location as its instance, in one of two forms:

  • a configured location name, for example Weather.Temperature(datacenter-hel)

  • a raw latitude,longitude pair, for example Weather.Temperature(50.1109,8.6821)

A raw pair needs no configuration and uses the default provider. The subagent starts polling it on the first request, so values become available after the next polling round, up to PollInterval seconds later. A configured name and a raw pair with the same coordinates (to four decimal places) and the same provider share one polled entry.

The subagent polls in the background and answers metric requests from the last successful poll. Until a location has been polled, its weather metrics (all except Weather.Provider) return an error, and a variable that the provider does not report is an error rather than 0: for example, Weather.ShortwaveRadiation on a metno location always fails. An unknown location name is reported as no such instance.

Metrics

Metric Type Description

Weather.Temperature(location)

Float

Air temperature at 2 m, °C

Weather.CloudCover(location)

Float

Total cloud cover, %

Weather.ShortwaveRadiation(location)

Float

Global horizontal (shortwave) irradiance, W/m². Open-Meteo and Bright Sky only

Weather.DirectRadiation(location)

Float

Direct radiation, W/m². Open-Meteo only

Weather.WindSpeed(location)

Float

Wind speed at 10 m, km/h

Weather.RelativeHumidity(location)

Float

Relative humidity at 2 m, %. Bright Sky forecast values carry no humidity, so on a brightsky location this fails while the current value is still a forecast

Weather.Precipitation(location)

Float

Precipitation, mm: over the preceding 15 minutes (Open-Meteo), the next hour (MET Norway) or the previous hour (Bright Sky)

Weather.DataAge(location)

Integer (64-bit)

Seconds since the time of the current values

Weather.Provider(location)

String

Provider serving the location

Values are converted to the units above whatever the provider reports (MET Norway wind speed in m/s, Bright Sky solar energy in kWh/m² per hour).

List

Metric Description

Weather.Locations

Names of the configured locations. Raw coordinate instances are not included.

Tables

Weather.Forecast(location) is the forecast curve over ForecastDays days, hourly except for MET Norway’s coarser steps after about two days. Open-Meteo and Bright Sky return whole days from 00:00 UTC, so the curve also contains the earlier hours of the current day.

Column Type Description

TIME (instance)

Integer (64-bit)

Target time, UNIX timestamp (UTC)

TEMPERATURE

Float

Temperature, °C

CLOUDCOVER

Float

Cloud cover, %

SHORTWAVE

Float

Shortwave radiation, W/m²

DIRECT

Float

Direct radiation, W/m²

WINDSPEED

Float

Wind speed, km/h

HUMIDITY

Float

Relative humidity, %

PRECIPITATION

Float

Precipitation, mm

Cells for variables that the provider does not report are empty. On a brightsky location, HUMIDITY is filled only for past (observed) hours.

Weather.ForecastEnsemble(location) is the hourly spread across the ensemble members of the model set in EnsembleModel. It needs EnableEnsemble = yes and an Open-Meteo location; otherwise it returns an error.

Column Type Description

TIME (instance)

Integer (64-bit)

Target time, UNIX timestamp (UTC)

SOLAR_MIN

Float

Shortwave radiation minimum, W/m²

SOLAR_MEAN

Float

Shortwave radiation mean, W/m²

SOLAR_MAX

Float

Shortwave radiation maximum, W/m²

TEMP_MIN

Float

Temperature minimum, °C

TEMP_MEAN

Float

Temperature mean, °C

TEMP_MAX

Float

Temperature maximum, °C

Collecting Weather Data

Collect weather data for the place where the dependent load is, at the same or a coarser polling interval as the DCIs it will be compared with. On the node whose agent loads the subagent:

  1. Create a DCI with origin Agent and a metric such as Weather.Temperature(datacenter-hel).

  2. To cover all configured locations at once, create the DCI with metric Weather.Temperature({instance}) and, on its instance discovery page, select method Agent List with list Weather.Locations. See Configuring Instance Discovery.

  3. For the forecast curve, create a table DCI with metric Weather.Forecast(datacenter-hel).

The subagent refreshes its data every PollInterval seconds, so a DCI polling interval shorter than that only returns the same value again.

To detect that weather data has stopped updating, add a threshold on Weather.DataAge(location). In normal operation the value stays within one hour plus PollInterval, so with the default PollInterval greater than 7200 (two hours) is a reasonable starting point. Current values keep moving along the cached forecast while downloads fail, so the value starts to grow only when the cached forecast runs out, up to ForecastDays days after the last successful download.

Request Caching

The subagent stores the Expires and Last-Modified headers of each response. A location whose response has not yet expired is not requested again, and a later request is conditional (If-Modified-Since), so an unchanged forecast costs a short "not modified" response. MET Norway’s terms of service require this behaviour. Bright Sky sends neither header, so every polling round requests each brightsky location in full.

Troubleshooting

The subagent logs with debug tag weather.

  • All weather values for a location fail (only Weather.Provider works) — the location has not been polled successfully yet. Check that the agent can reach the provider over HTTPS, and for brightsky that a DWD station is within 50 km of the coordinates. For a raw coordinate instance, wait for the next polling round.

  • MET Norway requests fail — set UserAgent to an identifying value with contact information.

  • One metric fails, the others work — the provider does not report that variable; see the provider table.

  • A configured location is missing from Weather.Locations — its entry was skipped at startup (malformed Location value, missing or invalid Latitude/Longitude, or unknown Provider); the agent log has a warning naming it.