TrueSight API Documentation
OverviewAccountActionsAdministration
Alarms v1Alarms v2BatchingDashboards
DatasetsEventsExtended Metrics
GroupsHostgroupsMetersMetricsProduct
PluginsRelaysSourcesSource-TagsSynchronize Data
Tenants
Terms

Events

An event appears as a moment in time on one or more graphs. Events can be color coded with associated text. An event stream can be placed on a dashboard in order to view the list of events. Events sometimes occur in multiples so in order to more clearly understanding the breadth of events these series of multiples are grouped together into a higher order event. This creates a distinction between events and "raw" events. s

Data Types

All returned timestamps are represented as Unix timestamp milliseconds.

QueryResponse

Field Type Description
counts CountResponse Count metadata.
items array of object The results of the query (i.e. RawEvent, Event).

CountResponse

A JSON object that includes the count of documents that matched the query. for example, a query with 63 matches would be:

{
    "counts": {
        "total": 63
    }
}

RawEvent

Size Restrictions

Maximum event payload size, including JSON, is 32KB. Any event payloads larger than this will be rejected.

All properties fields are limited to a maximum of 128 fields each.

Required Fields

Field Type Description
source Source The source of the event. The source is typically the hostname or ip address of the system this event refers to.
title string Description of the event.
fingerprintFields string array The fields of the event used to calculate the event fingerprint. In this field, @title refers to RawEvent.title, @message refers to RawEvent.message, and all other field values come from the properties object. Each field must have a non-null, non-empty field value with a basic type (string, number, or bool).

System Fields

Field Type Description
tenantId UUID The associated tenant id for this event. This will be populated according to the tenantId associated with the apiToken used to create the event
eventId string The id of the Event this raw event was de-duplicated to.
receivedAt timestamp The timestamp the event was received.

Optional Fields

Field Type Description
severity string Optional free-form text. Good default choices are one of INFO, WARN, ERROR, CRITICAL. Default is an empty string.
sender Source Optional information about the sender of the event. This is used to describe a third party event system forwarding this event into TrueSight Pulse, or a TrueSight Pulse service sending the event.
properties object Properties for the event.
status string Optional free-form text. Good choices are one of OPEN, CLOSED, ACKNOWLEDGED, or OK.
tags string array Tags used to provide a classification for events.
message string Additional description of the event.
createdAt timestamp The timestamp the event was created. If not specified, this is set to the time the event is received.

Event

Field Type Description
id string Automatically generated primary key.
tenantId UUID The associated tenant id for this event.
severity string Optional free-form text. Good default choices are one of INFO, WARN, ERROR, CRITICAL. Default is an empty string.
source Source The source of the event. The source is typically the hostname or ip address of the system this event refers to.
sender Source Optional information about the sender of the event. This is used to describe a third party event system forwarding this event into TrueSight Pulse, or a TrueSight Pulse service sending the event.
properties object Properties for the event. One of the property app_id (Application ID/Name) will associate the event with an application object in TrueSight Intelligence. For example, to associate an event with an application named EngageCash, specify app_id=EngageCash as a property.
status string Optional free-form text. Good choices are one of OPEN, CLOSED, ACKNOWLEDGED, or OK. Once an event is CLOSED, further matching RawEvents will result in new Events.
fingerprintFields string array The fields of the event used to calculate the event fingerprint. In this field, @title refers to RawEvent.title, @message refers to RawEvent.message, and all other field values come from the properties object. Each field must have a non-null, non-empty field value with a basic type (string, number, or bool).
tags string array Tags used to provide a classification for events.
title string Description of the event.
message string Additional description of the event.
timesSeen number The number of times an event with this fingerprint has been seen by the system.
firstSeenAt timestamp The first creation time for an event with this fingerprint (RawEvent.createdAt).
lastSeenAt timestamp The last creation time for an event with this fingerprint (RawEvent.createdAt).
lastUpdatedAt timestamp The last time the event was updated (either by changing the state or de-duplicating).
eventClass String Type of the event. This is used by TrueSight Intelligence to categorize the events, and filter the event list in UI. For example, if you are sending events from various social media sources and want to bucket them, use Social as the value for eventClass.

Source

Field Type Required Description
ref string True The reference / identifier for the event source (e.g. ip address, name, database id, meter observation domain id).
type string True The type of event source (e.g. 'host', 'conversation', 'organization').
name string False An optional descriptive name for the event source.
properties object False Used to store additional properties about the event source.

Event Query Parameters

Parameter Description
must FieldQuery - includes events where the field matches one or more of the specified values
mustNot FieldQuery - excludes events where the field matches one or more of the specified values
range RangeQuery - include events where the field falls within in a numeric range
from Start row - used to paginate query results
size Max # of rows to return - - used to paginate query results
sort Format is <fieldName> <dir>, where <fieldName> is a valid field name and <dir> is one of asc or desc. Multiple sort fields can be specified (they will be applied in the order specified in the query parameters).

FieldQuery

Will match if the given value or one of the given values matches that field.

Format:

fieldName:value or fieldName:[value1,value2,...valueN]:

RangeQuery

Will match if the given field falls within the closed range specified by the {low} and {high} values given.

fieldName:[{low} TO {high}]

Querying raw events

RawEvents support the same QueryParameters as Events, but there are some important caveats. RawEvents are not presently stored in a separate index, so any must or mustNot FieldQuery parameters will only be applied to the current rolled up version of the event. For example, if the event status was 'OPEN' and then changed to 'CLOSED', the query must=status:OPEN will not match. For that reason, it is recommended that the 'createdAt' field be used for raw event searches.

Example Queries

Returning all events where title = 'TrueSight Pulse meter 4.2.2-627 started.'

Returning the last 10 events sorted by severity descending, lastSeenAt descending.

Returning all events from source type 'host'

Get all events last seen between 1458162480 and 1458163490

Get all RawEvents created between 1458162480 and 1458163490

Searching

All Event fields support exact match queries. In addition, the following fields can support partial text (but full word) matching

By default, searches on these fields will use partial matching, unless the search term is quoted. As an example, if you have events with the title "Left turn signal engaged" and "Right turn signal engaged", the following example search will still match both events:

must=title:Left turn signal engaged

If that's not what you want, be sure to quote your search terms:

must:title="Left turn signal engaged"

Synthetic fields

The title Event field is also exposed as title.suggest. When querying on this field, the behavior will be to include partial word match results. For example, must=title.suggest:tur would match an event with title "Left turn signal engaged", but must=title:tur would not.