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 using a fingerprint. This creates a distinction between events and "raw" events.

Fingerprint

The fingerprint is used to uniquely group one or more raw events to a higher order event. The fields used to calculate the fingerprint value are specificed in the fingerprintFields field. For fingerprint determination, the fields used may be considered as one of the following categories:

If a field does not fall within one of the above mentioned categories, it is not used, even if specified, as part of the fingerprint calculation.

Default Fields

These fields are always part of the fingerprint calculation and need not be user-supplied:

Field
tenantId
source.ref
source.type
eventClass
products

Event Fields

These fields, if specified, are used as part of the fingerprint calculation:

Field
source.name
title
status
severity
message

To include one of these fields, prefix the field name with the character '@'. For example, to include title as part of the fingerprint calculation:

{
    ...,
    "fingerprintFields": ["@title"]
}

User Fields

Field
properties.*

To include one of the user property fields, only specify the property name (everything right of the dot). It is not necessary, or correct, to include properties. as part of the field name. For example, to include properties.uid as part of the fingerprint calculation:

{
    ...,
    "fingerprintFields": ["uid"]
}

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.

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, or a TrueSight service sending the event.
properties object Properties for the event.
status string Optional mostly free-form text. The value CLOSED is used to indicate a closed event. As example, good choices may be 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.
eventClass String Type of the event. Used by TrueSight to categorize the event. If not supplied, defaults to UNKNOWN.

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.
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. Including the property app_id (Application ID/Name) will associate the event with an application object in brand:famil. 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.
fingerprint long The fingerprint value calculated from fingerprintFields. Automatically generated value.
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. Used by TrueSight to categorize the event.

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"