Events
Events annotate ranges of time in your data. They help you quickly identify, categorize, and search for relevant subsets of your data.
How events work
Events can be created manually in the app or programmatically via the API. You can use the API to create events on-robot or during post-processing. Events can be accessed in a few locations within the app:
- The visualization playback timeline
- The visualization Events sidebar
- The Events listing and search pages
- An Event details page with a unique URL
Events define a time range for a device. They may also include associated properties. Events that overlap with the time range in visualization will appear above the playback bar.
You can click "Visualize" on in the Events listing to open visualization. This will include data for all recordings associated with that device that overlap with that time range.
Event types
Admins can create event types to define categories of events with structured properties. Each type includes a human-readable name, a color, and an ordered list of typed properties. Types and properties are managed from the Events page.
Properties support several types of values:
- Single-line text
- Multi-line text
- True/False
- Number
- Single-select
- Multi-select
Event types ensure data quality through validation. They also enable better filtering and analytics, and provide visual distinctions between categories of events.
Viewing and editing events
Seek to a point of interest in your data. Under the Events menu in the playback bar, click "Create event", or press Cmd+E. This will create a zero-duration event at the current playback position.
You can adjust event time ranges directly from the playback bar. The event being edited will also be highlighted in time series Plot and State Transitions panels. You can also view a list of all events in the right sidebar's "Events" tab.
Use the current playback position marker and endpoint snapping to precisely align events with other data.
To edit an existing event, click it in the Events sidebar or in the timeline. While editing you can:
- Modify properties
- Adjust start and end times
- Change the event type
- Delete the event
Team and Enterprise users can select an event type from the dropdown. This will display a form for entering the event's properties as defined by organization administrators. Typed events are color-coded, making it easier to distinguish different categories of events.
Search
Search events by device, time range, properties, and type on the Events page:
Use the syntax below to filter properties by keys and values:
| Specific key | Any key | |
|---|---|---|
| Specific value | weather:rain | *:rain |
| Any value | weather:* | |
| Multiple values (all required) | weather:rain weather:fog | |
| Multiple values (1+ required) | weather:rain,fog,"mostly sunny" |
A single word (for example, error) will look for matching keys or values.
Non-alphanumeric characters can be used inside quotes (for example, "/weather/rain":* or "@my.custom.key":"10%").
The dropdown selector within the metadata filter lets you choose whether the filtering applies to events with typed properties, events with untyped metadata or both. Selecting either typed or untyped is a faster query than filtering both kinds of properties.
Event types will also be displayed in the search results when present. Selecting a particular event type from the dropdown will filter the search results to only show events of that type, and display the properties linked to that type in individual columns.
Deleting event types and custom properties
Administrators can delete event types and custom properties when they are no longer needed. These can also be deleted using an API key with the EventTypesDelete or CustomPropertiesDelete capability.
Deletion rules are designed to prevent data loss, or inconsistencies in your organization’s data:
Deleting event types
An event type can be permanently removed by deleting it. It cannot be deleted if there are any events of that type. You must first delete or update those events.
Once deleted, the same event type name can be reused to create a new event type.
Deleting custom properties
A custom property can be permanently removed by deleting it, if it is unused:
- It cannot be deleted if it is linked to an event type.
- It cannot be deleted if an event stores a value for that property.
Once deleted, the same custom property key and label can be reused to create a new custom property.