Events

To organize time based data in XINA, we employ events, which come in two forms: instants, referring to a single moment in time, and intervals, referring to a range of time. The goal of events is to make it easy to find, compare, and trend data.

Fields

Unlike most XINA Structs database definitions, event databases may include as many custom fields as required, so long as they do not conflict with the required standard fields:

UEID

Universally unique event identifier (UUID). Intended to permanently, globally specify each event. Should be generated at the creation of the event to ensure consistency even if data is reprocessed.

Event ID

Optional numeric reference to an event definition (see below). If not provided, defaults to 0.

Type

Indicates how the event should be viewed and interpreted. The options are defined by XINA.

Level

Indicates how the event should be viewed and interpreted. The options are defined by XINA.

Label

Required plain text description of the event. Limited to to 128 bytes for indexing.

Content

Optional plain text, HTML, or JSON of unlimited length.

Meta

Optional JSON object of arbitrary additional content.

Types

XINA defines a fixed set of standard event types, each with an associated numeric code. The type is stored as the code in the database for performance reasons; for practical purposes most actions can use the type name directly, unless interacting directly with the API.

Standard Types

Code	Name	Ins	Int	Description
`0`	`message`	✓	✓	Basic event, ID optional
`1`	`marker`	✓	✓	Organized event, ID required
`2`	`alert`	✓	✓	Organized event, ID required, level (severity) required
`2000`	`test`		✓	Discrete test period, may not overlap other tests, ID optional
`2001`	`activity`		✓	Discrete activity period, may not overlap other activities, ID optional
`2002`	`phase`		✓	Discrete phase period, may not overlap other phases, ID optional
`2010`	`filter`		✓	Filter state
`3000`	`data`	✓	✓	General purpose data set
`3001`	`spectrum`	✓	✓	General purpose spectrum data

Additional types will be added in the future as needed, with codes based on this chart:

Standard Type Code Ranges

code	ins	int	description
`0-999`	✓	✓	General types for instants and intervals
`1000-1999`	✓		General types for instants only
`2000-2999`		✓	General types for intervals only
`3000-3999`	✓	✓	Data set types for instants and intervals
`4000-4999`	✓		Data set types for instants only
`5000-5999`		✓	Data set types for intervals only

Definitions

As with mnemonics, events may be identified with event definitions. However, unlike mnemonics, not every event requires a definition. The event ID field associates an event with an event definition.

Each event ID is associated with a unique name, describing the definition. These work similarly to mnemonic names for purposes for definition creation. If an event is inserted with an unrecognized name, a new definition will be created for that name and assigned a new event ID.

Streams

For events sourced from telemetry data it is recommended to employ event streams. This feature creates an additional database alongside the event database, tracking each event change as an individual record. Event streams address two primary issues with events sourced from telemetry data.

Cross Archive Intervals

For intervals to span across archives, event streams support open and close operations, which create an initially open interval (with a start time but no end time) and subsequently close the interval (~~add~~setting an end time). Additionally, interval bins can only be generated for cross archive intervals with an event stream database.

Preserving Manual Changes

Telemetry sourced event data may periodically need to be reprocessed, which generates a clean data set in XINA. This will erase any user-applied changes to event records, unless an event stream is used. The extraction process can apply all user changes automatically when processing occurs.

Limitations

Event databases configured with an event stream employ certain restrictions to ensure consistent and predictable outcomes. Change operations (except insert and open) are limited to a single event, and bound to that event UEID. Event start and end times cannot be updated manually, as this would break consistency across other databases.

Data Formats

The data event type indicates a basic data set. This is typically used with the single file per event database structure, in which case the file will contain the data set. For event databases without files, the data is expected to be stored in the content field. This is only recommended for small datasets (less than 1MB).

Files must be either ASCII or UTF-8 encoded. New lines will be interpretted from either \n or \r\n. The conf object may define other customization of the format:

Conf Definition

Key	Value	Default	Description
`delimiter`	`string`	auto detect (`','`, `'\t'`, `';'`)	value delimiter
`quoteChar`	`character`	`"` (double quote character)	value quote character
`ignoreLines`	`number`	`0`	number of lines to skip before the header
`invalid`	`null`, `'NaN'`, `number`	`null`	preferred interpretation of invalid literal
`nan`	`null`, `'NaN'`, `number`	`null`	preferred interpretation of `'Nan'` literal
`pInfinity`	`null`, `'Inf'`, `number`	`null`	preferred interpretation of positive `'Infinity'` literal
`nInfinity`	`null`, `'Inf'`, `number`	`null`	preferred interpretation of negative `'Infinity'` literal
`utc`	`boolean`	`false`	if `true`, interpret all unzoned timestamps as UTC

Starting after the number provided for ignoreLines, the content must include a header for each column, with a name and optional unit in parentheses. Special standard unit names may be used to indicate time types, which will apply different processing to the column:

Unit	Description
`ts`	text timestamp, interpretted in local browser timezone (absent explicit zone)
`ts_utc`	text timestamp, interpretted as UTC timezone (absent explicit zone)
`unix_s`	Unix time in seconds
`unix_ms`	Unix time in milliseconds
`unix_us`	Unix time in microseconds