InfluxDB Exporter » Dale Ghent

InfluxDB Exporter is a NINA plugin that transmits periodic hardware, guiding, and image metrics to an InfluxDB time-series database. From there, the metrics may be graphed using tools such as Grafana or InfluxDB’s own built-in graphing features. A time-series database is optimized to collect and store temporally-oriented data. This data may be archived indefinitely or ephemerally, depending on the desired use and purpose.

Metrics are provided on the basis of class of equipment and the statistics of each saved image. For equipment, metrics for each class are sent each time N.I.N.A. polls the hardware for its status, which is every two seconds by default. Refer to Options > General > Advanced settings > Device polling interval. This also means that only connected hardware will have statistics transmitted. Certain metrics will also have tags associated with them which can be used in a variety of ways to select and present the data. Tags are kept to a minimum in order to manage cardinality and may be turned on and off on the plugin’s Options screen.

No sequencer instructions are required to operate this plugin as it will always transmit metrics as long as NINA is running and is connected to any relevant equipment. Naturally, a working InfluxDB API key, bucket, and organization are required as well.

Example use of metrics

My system’s Grafana-based dashboard can be found here. It displays live and historic stats from my PlaneWave CDK14-based imaging system. The metrics behind these graphs and displays are sent from NINA via InfluxDB Exporter to an InfluxDB instance. A separate Grafana instance uses that InfluxDB system as a data source to produce the graphs. A few other things are involved, such as MQTT and web API queries for stuff like the Last Target panel. Influx’s Telegraf is used to gather stats on and to monitor the setup’s APC UPS.

Requirements

NINA 3.2 (nightly) and later. The requirement for 3.2 stems from this plugin using the same dependencies that other parts of NINA uses, but different versions of them. This can lead to a conflict that prevents the plugin from loading. NINA 3.2 solves this issue by loading each plugin into its own assembly context.
InfluxDB 2.x or later.
Optional but suggested: Grafana

For small deployments, InfluxDB and Grafana are both available as Docker containers. Refer to their respective sites for installation and administration documentation.

FAQ

What is the scope of this plugin?

For now, InfluxDB Exporter’s mission in life is simple: to get equipment and image metrics from N.I.N.A. into one of the most popular TSDBs available. Statistics concerning the underlying operating system or external systems not directly managed by N.I.N.A. via ASCOM/Alpaca or its own “native” drivers is outside the scope. Collecting metrics from external software or systems should be done using other metric collection systems such as Telegraf and Prometheus.

Will you add an option to convert metrics that contain metric units to imperial?

InfluxDB Exporter should be thought of as a data relay system, not as a presentation system. Conversions to other units should be done with whichever presentation system you choose to use. Grafana, for example, has the concept of data transforms which you can use to transform data from metric units to imperial. Such conversions would be inappropriate to do at InfluxDB Export’s level.

Does this plugin install InfluxDB for me?

No, this plugin does not provide InfluxDB or any higher-level presentation and analysis software; only itself. There are various resources online for running InfluxDB and Grafana on a Raspberry Pi, Docker container, or any Linux/UNIX system. For cloud-based solutions, you can consider InfluxDB Cloud and Grafana Cloud.

List of metrics

The following tables catalog all metrics and tags that are transmitted. There are two types of metrics:

Periodic metrics include all hardware and other measurements that are transmitted at regular intervals. InfluxDB Exporter will transmit measurements for connected hardware with each NINA update interval. By default, this is every 2 seconds for hardware, and every 1 minute for non-hardware data such as astrometric information.
Event metrics are sent when a specific event occurs. These include images, autofocus operations, safety monitor state changes, and other such happenings.

Global tags, applied to all metrics

profile_name: The name of the active N.I.N.A. profile
host_name: The name of the computer

Periodic Metrics

Astrometric

Metric	Definition	Type
`astro_moon_altitude`	Moon’s altitude in degrees	double
`astro_sun_altitude`	Sun’s altitude in degrees	double

Camera

Additional tags:

camera_name: The name of the connected canera device

Metric	Definition	Type
`camera_sensor_temperature`	Sensor temperature in °C	double
`camera_cooler_power`	Cooler power level in percent	double
`camera_battery_level`	Camera battery charge level	integer

Focuser

Additional tags:

focuser_name: The name of the connected focuser device

Metric	Definition	Type
`focuser_temperature`	Focuser’s temperature sensor in °C	double
`focuser_position`	Step number/position reported by focuser	integer

Guider

Additional tags:

guider_name: The name of the connected guiding device

Metric	Definition	Type
`guider_rms_ra_arcsec`	RA RMS in arcseconds	double
`guider_rms_dec_arcsec`	Declination RMS in arcseconds	double
`guider_rms_arcsec`	Comined RMS in arcseconds	double
`guider_rms_ra_pixel`	RA RMS in pixels	double
`guider_rms_dec_pixel`	Declination RMS in pixels	double
`guider_rms_pixel`	Combined RMS in pixels	double
`guider_rms_peak_ra_arcsec`	RA peak RMS in arcseconds	double
`guider_rms_peak_dec_arcsec`	Declination peak RMS in arcseconds	double
`guider_rms_peak_arcsec`	Combined peak RMS in arcseconds	double
`guider_rms_peak_ra_pixel`	RA peak RMS in arcseconds	double
`guider_rms_peak_dec_pixel`	Declination peak RMS in pixels	double
`guider_rms_peak_pixel`	Combined peak RMS in pixels	double

Mount

Additional tags:

mount_name: The name of the connected mount device

Metric	Definition	Type
`mount_altitude`	Altitude in degrees	double
`mount_azimuth`	Azimuth in degrees	double

Rotator

Additional tags:

rotator_name: The name of the connected rotator device

Metric	Definition	Type
`rotator_mechanical_angle`	Mecanical angle in degrees	double
`rotator_angle`	Sky angle in degrees	double

Switches

Additional tags:

guider_name: The name of the connected guiding device

Metric	Definition	Type
`switch_ro_sw<ID>`	Value of gauge (read-only switch) identified by the appended numeric identifier	double

Each swtich metric is tagged with the human-readable name associated with the switch’s ID.

Weather

Additional tags:

wx_device_name: The name of the connected weather/observing conditions device

Metric	Definition	Type
`wx_cloud_cover`	Cloud cover in percent	double
`wx_dewpoint`	Dewpoint in °C	double
`wx_humidity`	Relative humidity in percent	double
`wx_pressure`	Air pressure in hectopascals	double
`wx_rain_rate`	Rain rate in mm/hour	double
`wx_sky_brightness`	Sky brightness in lux	double
`wx_sky_quality`	Sky quality in magnitudes/arcsecond<sup>2</sup>	double
`wx_sky_temperature`	Sky temperature in °C	double
`wx_star_fwhm`	Measured star FWHM	double
`wx_temperature`	Ambient air temperature in °C	double
`wx_wind_direction`	Wind direction in azimuthal degrees	double
`wx_wind_gust`	Wind gust speed in meters/second	double
`wx_wind_speed`	Wind speed in meters/second	double

Vendor or device-specific periodic metrics

These metrics are specific to certain devices or vendors.

Metric	Definition	Type
`qhy_sensor_air_pressure`	Sensor chamber air pressure (certain QHY camera models)	double
`qhy_sensor_humidity`	Sensor chamber humidity (certain QHY camera models)	double

Event Metrics

The following events are sent to the configured measurement for events, the default name being events. The name of this measurement can be changed under the Plugins > Installed > InfluxDB Exporter > Event Options tab. The event metric contains the following:

Element	Content	Notes
Tag: `name`	Event name	Always present. Required for Grafana Annotations
Field: `text`	Event information	Always present. Required for Grafana Annotations
Field: `title`	Short event description	Some events have this, some do not as it would be redundant
Field: `timeEnd`	Timestamp that records the end of the event	For events when the start and end time are both known. Required for Grafana range annotations. The timestamp of the event itself will be set to the start time of the event

Autofocus

Emitted upon the completion of an autofocus operation.

Tag: autofocus

Field	Content	Type
`title`	Autofocus complete	string
`text`	Autofocus on filter <filter name>, Postion: <focuser position>, Temperature: <focuser temperature>	string
`autofocus_position`	Focuser position	integer
`autofocus_filter`	Filter used for autofocus	string
`autofocus_temperature	Focuser temperature in Celcius	float

Dome Movements

The following events related to dome activity:

Connected/Disconnected

Tag: dome_connected

Field	Content	Type
`text`	Dome connected	string

Tag: dome_disconnected

Field	Content	Type
`text`	Dome disconnected	string

Dome Homed

Tag: dome_homed

Field	Content	Type
`text`	Dome homed	string

Dome Parked

Tag: dome_parked

Field	Content	Type
`text`	Dome parked	string

Dome Slewed

Tag: dome_slewed_az

Field	Content	Type
`title`	Dome slewed azimuth	string
`text`	Dome slewed azimith to <azimuth>	string

Shutter Opened/Closed

Tag: dome_shutter_opened

Field	Content	Type
`text`	Dome shutter opened	string

Tag: dome_shutter_closed

Field	Content	Type
`text`	Dome shutter closed	string

Filter Wheel

The following events are related to filter wheel activity:

Connected/Disconnected

Tag: fwheel_connected

Field	Content	Type
`text`	Filter Wheel connected	string

Tag: fwheel_disconnected

Field	Content	Type
`text`	Filter Wheel disconnected	string

Filter Changed

Tag: filter_change

Field	Content	Type
`text`	Filter change from <previous filter> to <new filter>	string
`title`	Filter changed	string
`filter_from`	Previous filter name	string
`filter_to`	New filter position name	string

Flat Device

The following events are related to flat device/cover/calibrator activity:

Brightness Change

Connected/Disconnected

Tag: dome_connected

Field	Content	Type
`text`	Dome connected	string

Tag: dome_disconnected

Field	Content	Type
`text`	Dome disconnected	string

Cover Open/Close

Tag: calibrator_opened

Field	Content	Type
`text`	Cover opened	string

Tag: calibrator_closed

Field	Content	Type
`text`	Cover closed	string

Light On/Off

Tag: calibrator_light_toggled

Field	Content	Type
`text`	Calibrator light: On/Off	string
`title`	Calibrator light toggled	string
`calibrator_light_state`	True/False	boolean

Guider

The following events are related to guider activity:

Connected/Discnnected

Tag: guider_connected

Field	Content	Type
`text`	Guider connected	string

Tag: guider_disconnected

Field	Content	Type
`text`	Guider disconnected	string

Dither

Tag: guider_dither

Field	Content	Type
`text`	Dither	string

Image Taken

Each image taken produces an image event that contains statistical information for the associated image. These are produced only for images of type LIGHT. Calibration frames and snapshots are not processed. Statistics must be on for many of these metrics to be sent.

Additional tags:

image_file_name: Name of the image file associated with these metrics.
target_name: Name of the target imaged as defined in the sequencer’s target field. This tag is omitted if no target name is defined.
sequence_title: The title or name of the running sequence
camera_name: Name of the camera
readout_mode: Name of the readout mode the camera is operating under

Field	Definition	Type
`image_eccentricity`	Average star eccentricity (Hocus Focus only)	double
`image_fwhm`	Average star Full Width at Half Maximum (Hocus Focus only)	double
`image_hfr`	Average star HFR	double
`image_hfr_std_deviation`	Standard deviation of measured stars’ HFR	double
`image_mad`	Pixel value mean average deviation	double
`image_max_adu`	Maximum pixel ADU value	integer
`image_max_adu_count`	Number of occurences of max. pixel ADU value	integer
`image_mean`	Pixel mean value	double
`image_median`	Pixel median value	double
`image_min_adu`	Minimum pixel ADU value	integer
`image_min_adu_count`	Number of occurences of min. pixel ADU value	integer
`image_rms_avg_ra_arcsec`	Average guiding RMS of the RA axis during image exposure	double
`image_rms_avg_dec_arcsec`	Average guiding RMS of the declination axis during image exposure	double
`image_rms_avg_arcsec`	Combined average RMS during image exposure	double
`image_rms_peak_ra_arcsec`	Peak guiding RMS of the RA axis during image exposure	double
`image_rms_peak_dec_arcsec`	Peak guiding RMS of the declination axis during image exposure	double
`image_rms_peak_arcsec`	Combined peak RMS during image exposure	double
`image_star_count`	Count of stars in the image	integer
`image_std_deviation`	Pixel value stardard deviation	double

Mount

The following events pertain to mount activity:

Connected/Disconnected

Tag: mount_connected

Field	Content	Type
`text`	Mount connected	string

Tag: mount_disconnected

Field	Content	Type
`text`	Mount disconnected	string

Slew

Tag: mount_slewed

Field	Content	Type
`title`	Mount slewed	string
`text`	Mount slewed to <RA>, <Declination> (<Equatorial System>)	string
`mount_slew_from_ra`	Previous Right Ascension	string
`mount_slew_from_dec`	Previous Declination	string
`mount_slew_to_ra`	New Right Ascension	string
`mount_slew_to_dec`	New Declination	string

Park/Unpark

Tag: mount_parked

Field	Content	Type
`text`	Mount has parked	string

Tag: mount_unparked

Field	Content	Type
`text`	Mount has unparked	string

Homed

Tag: mount_homed

Field	Content	Type
`text`	Mount has homed	string

Rotator

The following events pertain to rotator activity:

Connected/Disconnected

Tag: rotator_connected

Field	Content	Type
`text`	Rotator connected	string

Tag: rotator_disconnected

Field	Content	Type
`text`	Rotator disconnected	string

Moved

Tag: rotator_moved

Field	Content	Type
`title`	Rotator moved	string
`text`	Rotator moved to <angle>°	string
`rotator_moved_from`	Previous angle	float
`rotator_moved_to`	New angle	float

Safety Monitor

The following events pertain to safety monitor device activity.

Connected/Disconnected

Tag: safety_connected

Field	Content	Type
`text`	Safety connected	string

Tag: safety_disconnected

Field	Content	Type
`text`	Safety disconnected	string

Safety State Changed

Tag: safety_safe_state

Field	Content	Type
`title`	Safety state changed	string
`text`	Safety state changed to <new state>	string
`safety_issafe`	True/False	boolean

Safety State Period

Tags: safety_safe_period, safety_unsafe_period

Field	Content	Type
`text`	Safe (or Unsafe) period	string
`timeEnd`	Millisecond UNIX timestamp of previous state’s end time	integer
`_time`	Timestamp for beginning of event set to the saved or first-known start time of the previous event	InfluxDB Date/Time

Weather Source

The following events pertain to weather source/device activity:

Connected/Disconnected

Tag: wx_connected

Field	Content	Type
`text`	Weather source connected	string

Tag: wx_disconnected

Field	Content	Type
`text`	Weather source disconnected	string