Storing Data and Metrics in a Time Series Database

If you wish to store data from readsb in a time series database such as InfluxDB or Prometheus, review the information below.
The readsb-protobuf container also contains InfluxData's Telegraf, and can send flight data and readsb metrics to InfluxDB or Prometheus. Telegraf is not started by default. INFLUXDBURL must be set in order to start the built-in Telegraf instance.

InfluxDB Options

These variables control the sending of flight data and readsb metrics to InfluxDB (via a built-in instance of Telegraf).
Variable
Description
Default
INFLUXDBURL
The full HTTP URL for your InfluxDB instance. Required for both InfluxDB v1 and v2.
Unset
INFLUXDBUSERNAME
If using authentication, a username for your InfluxDB instance. If not using authentication, leave unset. Not required for InfluxDB v2.
Unset
INFLUXDBPASSWORD
If using authentication, a password for your InfluxDB instance. If not using authentication, leave unset. Not required for InfluxDB v2.
Unset
INFLUXDB_V2
Set to a non empty value to enable InfluxDB V2 output.
Unset
INFLUXDB_V2_BUCKET
Required if INFLUXDB_V2 is set, bucket must already exist in your InfluxDB v2 instance.
Unset
INFLUXDB_V2_ORG
Required if INFLUXDB_V2 is set.
Unset
INFLUXDB_V2_TOKEN
Required if INFLUXDB_V2 is set.
Unset
INFLUXDB_SKIP_AIRCRAFT
Set to any value to skip publishing aircraft data to InfluxDB to minimize bandwidth and database size.
Unset

InfluxDB Schema

The database readsb will be created if it does not exist.
Within this database are the following measurements:

aircraft Measurement

Tags and fields used for this measurement should match Virtual Radar Server's JSON response ("the new way").
Tag Key
Type
Description
Call
String
The aircraft's callsign.
Gnd
Boolean
True if the aircraft is on the ground.
Icao
String
The ICAO of the aircraft.
Mlat
Boolean
True if the latitude and longitude appear to have been calculated by an MLAT server and were not transmitted by the aircraft.
SpdTyp
Number
The type of speed that Spd represents. Only used with raw feeds. 0/missing = ground speed, 1 = ground speed reversing, 2 = indicated air speed, 3 = true air speed.
Sqk
Number
The squawk as a decimal number (e.g. a squawk of 7654 is passed as 7654, not 4012).
Tisb
Boolean
True if the last message received for the aircraft was from a TIS-B source.
TrkH
Boolean
True if Trak is the aircraft's heading, false if it's the ground track. Default to ground track until told otherwise.
VsiT
Number
0 = vertical speed is barometric, 1 = vertical speed is geometric. Default to barometric until told otherwise.
host
String
The hostname of the container.
Field Key
Type
Description
Alt
float
The altitude in feet at standard pressure.
Cmsgs
float
The count of messages received for the aircraft.
GAlt
float
The altitude adjusted for local air pressure, should be roughly the height above mean sea level.
InHg
float
The air pressure in inches of mercury that was used to calculate the AMSL altitude from the standard pressure altitude.
Lat
float
The aircraft's latitude over the ground.
Long
float
The aircraft's longitude over the ground.
PosTime
float
The time (at UTC in JavaScript ticks) that the position was last reported by the aircraft.
Sig
float
The signal level for the last message received from the aircraft, as reported by the receiver. Not all receivers pass signal levels. The value's units are receiver-dependent.
Spd
float
The ground speed in knots.
TAlt
float
The target altitude, in feet, set on the autopilot / FMS etc.
TTrk
float
The track or heading currently set on the aircraft's autopilot or FMS.
Trak
float
Aircraft's track angle across the ground clockwise from 0° north.
Trt
float
Transponder type - 0=Unknown, 1=Mode-S, 2=ADS-B (unknown version), 3=ADS-B 0, 4=ADS-B 1, 5=ADS-B 2.
Vsi
float
Vertical speed in feet per minute.

autogain Measurement

Tag Key
Type
Description
host
String
The hostname of the container.
Field Key
Type
Description
autogain_current_value
float
The current gain level as set by autogain.
autogain_max_value
float
The maximum gain level as set by autogain.
autogain_min_value
float
The minimum gain level as set by autogain.
autogain_pct_strong_messages_max
float
The maximum percentage of strong messages.
autogain_pct_strong_messages_min
float
The minimum percentage of strong messages.

polar_range Measurement

Tag Key
Type
Description
bearing
Number
The bearing value is between 00 and 71. Each bearing represents 5° on the compass, with 00 as North.
host
String
The hostname of the container.
Field Key
Type
Description
range
float
The range (in metres) at a specific bearing.

readsb Measurement

Tag Key
Type
Description
host
String
The hostname of the container.
Field keys should be as-per the StatisticEntry message schema from readsb.proto.
Field Key
Type
Description
cpr_airborne
float
Total number of airborne CPR messages received
cpr_global_bad
float
Global positions that were rejected because they were inconsistent
cpr_global_ok
float
Global positions successfully derived
cpr_global_range
float
Global positions that were rejected because they exceeded the receiver max range
cpr_global_skipped
float
Global position attempts skipped because we did not have the right data (e.g. even/odd messages crossed a zone boundary)
cpr_global_speed
float
Global positions that were rejected because they failed the inter-position speed check
cpr_local_aircraft_relative
float
Local positions found relative to a previous aircraft position
cpr_local_ok
float
Local (relative) positions successfully found
cpr_local_range
float
Local positions not used because they exceeded the receiver max range or fell into the ambiguous part of the receiver range
cpr_local_skipped
float
Local (relative) positions not used because we did not have the right data
cpr_local_speed
float
Local positions not used because they failed the inter-position speed check
cpr_surface
float
Total number of surface CPR messages received
cpu_background
float
Milliseconds spent doing network I/O, processing received network messages, and periodic tasks.
cpu_demod
float
Milliseconds spent doing demodulation and decoding in response to data from a SDR dongle.
cpu_reader
float
Milliseconds spent reading sample data over USB from a SDR dongle.
local_accepted
float
The number of valid Mode S messages accepted from a local SDR with N-bit errors corrected.
local_modeac
float
Number of Mode A / C messages decoded.
local_modes
float
Number of Mode S preambles received. This is not the number of valid messages!
local_noise
float
Calculated receiver noise floor level.
local_peak_signal
float
Peak signal power of a successfully received message, in dBFS; always negative.
local_samples_dropped
float
Number of sample blocks dropped before processing. A non-zero value means CPU overload.
local_samples_processed
float
Number of sample blocks processed.
local_signal
float
Mean signal power of successfully received messages, in dBFS; always negative.
local_strong_signals
float
Number of messages received that had a signal power above -3 dBFS.
local_unknown_icao
float
Number of Mode S messages which looked like they might be valid but we didn't recognize the ICAO address and it was one of the message types where we can't be sure it's valid in this case.
max_distance_in_metres
float
Maximum range in metres
max_distance_in_nautical_miles
float
Maximum range in nautical miles
messages
float
Total number of messages accepted by readsb from any source
remote_accepted
float
Number of valid Mode S messages accepted over the network with N-bit errors corrected.
remote_modeac
float
Number of Mode A / C messages received.
remote_modes
float
Number of Mode S messages received.
tracks_mlat_position
float
Tracks consisting of a position derived from MLAT
tracks_new
float
Total tracks (aircraft) created. Each track represents a unique aircraft and persists for up to 5 minutes.
tracks_single_message
float
Tracks consisting of only a single message. These are usually due to message decoding errors that produce a bad aircraft address.
tracks_with_position
float
Tracks consisting of a position.

Prometheus Options

These variables control exposing flight data and readsb metrics to Prometheus (via a built-in instance of Telegraf). The metrics will be available under any path on the chosen port.
Variable
Description
Default
PROMETHEUS_ENABLE
Set to any string to enable Prometheus support
Unset
PROMETHEUSPORT
The port that the Prometheus client will listen on
9274