record_timeseries

swxsoc.db.timeseries.record_timeseries(ts: TimeSeries, ts_name: str = None, instrument_name: str = '') → None[source]

Record a timeseries of measurements to AWS Timestream for viewing on a dashboard like Grafana.

This function requires AWS credentials with permission to write to the AWS Timestream database.

Parameters:

  • ts (TimeSeries) – A timeseries with column data to record. Note that times are assumed to be in UTC.

  • ts_name (str, optional) – The name of the timeseries to record. If None or empty string, defaults to ts.meta[‘name’] or ‘measurement_group’.

  • instrument_name (str, optional) – The instrument name. If not provided or empty, uses ts.meta[‘INSTRUME’].

Returns:

None

Raises:

ValueError – If instrument_name is invalid or not in the configured mission instrument names.

Notes

Records are written in batches of 100 to comply with Timestream API limits. Database and table names are derived from the configured mission name (e.g. hermes_sdc_aws_logs). When the default demo mission is active, swxsoc is used instead so that Timestream resources remain mission-agnostic. Names are automatically prefixed with ‘dev-’ when not in PRODUCTION environment.

NaN values are skipped entirely and not written to Timestream. When a NaN is encountered in the timeseries data, that specific measure value is omitted from the record. The function logs the total count of NaN values skipped across all columns and time points.

Data type inference follows a hierarchical approach to determine the appropriate Timestream type:

  • BOOLEAN: Values of type bool or np.bool_ are stored as BOOLEAN type with lowercase string representation (“true” or “false”) as required by Timestream.

  • DOUBLE: Numeric values (instances of numbers.Number) are stored as DOUBLE type.

  • VARCHAR: All other values default to VARCHAR type for text/string storage.

The boolean check is performed first since bool is a subclass of int in Python. This ensures boolean flags are correctly identified and not mistakenly stored as numeric DOUBLE values.