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.

Each

Fields

has

Unlike theirmost ownXINA Structs database definitions, event databases andmay include as many custom fields for:

as

required,
• so typelong (indicatesas howthey do not conflict with the eventrequired shouldstandard befields:
  viewed and interpreted)

• UEID

  (universally

  Universally unique event identifier,identifier (UUID). Intended to permanently, globally specify each event. Should be generated at the creation of the event)

• numeric event ID
• plain text label (up to 128 bytes)
• plain text, HTML, or JSON content
• optional JSON object metadata

The UEID uniquely identifies an event, and is the only way to permanently, globally specify it. It should be applied at the time of creation 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 IDshould isbe optional,viewed and caninterpreted. beThe usedoptions asare needed (when not provided it will be zerodefined by default).XINA.

Its

Label

much

Required fasterplain andtext moredescription reliableof the event. Limited to queryto numbers128 thanbytes for indexing.

Content

Optional plain text, soHTML, thisor isJSON theof bestunlimited waylength.

to

Meta

indicate

Optional eventsJSON havingobject commmonof meaning.arbitrary additional content.

Event 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
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

Event 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.

Event 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.

To fully integrate events into a data pipeline, it is recommended to use event streams. This stores each event change as its own record with an associated time, allowing the processing utilities to correctly interpret accurate content for each event, even when events are being reprocessed.

Event 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