Event Management – Best Practices¶

This document provides best practices for querying and creating events or event types in Event Management.

General Remarks¶

• The size of a page should be as small as possible (default page size is 20).
• If real time data about events is not required, set the polling cycle as high as possible.
• If an application uses retry strategy, it should wait for some time after receiving a gateway timeout.
• For the following severities default apps like Insights Hub Monitor or the Insights Hub Web Components show the depending icon. For other severities only the number is displayed.

Severity	Icon	Description
20		Error
30		Warning
40		Information

Filterable Properties for Custom Events¶

Enum¶

If a custom event type field stores only allows a few values, consider using ENUM as type of that field.

{
  "name": "volatileEventType",
  "ttl": 1,
  "fields": [
    {
      "name": "risk",
      "filterable": true,
      "required": true,
      "updatable": true,
      "type": "ENUM",
      "values" : ["LOW", "MEDIUM", "HIGH"]
    }
  ]
}

UUID vs String¶

If a custom event type field stores only UUID values, consider using UUID as type of that field instead of STRING.

{
  "name": "volatileEventType2",
  "ttl": 1,
  "fields": [
    {
      "name": "code",
      "filterable": true,
      "required": true,
      "updatable": false,
      "type": "UUID"
    }
  ]
}

Filtering¶

HTTP GET /events API uses filter parameter to filter custom events list. Please refer to Listing Custom Events for sample.

Filtering by Timestamp¶

When filtering by timestamp the time interval should be as small as possible. For better performance of visualizations, it should not exceed 1 month. If no timestamp is specified for the filter, only events from the last week are retrieved.

{
  "timestamp": {
    "between": "[1970-01-01T07:25:07.166Z,2018-11-05T10:25:07.166Z)"
  }
}

{
  "timestamp": {
    "between": "[2018-11-01T07:25:07.166Z,2018-11-05T10:25:07.166Z)"
  }
}

Filtering by Timestamp (Using Between instead of Before/After)¶

When filtering by timestamp, the time interval should be as small as possible. For better performance of visualizations, it should not exceed 1 month. If Before & After is used, it will be any range in past & future respectively. It should be used judicially when you are aware about these factors mostly in non-performant operations like KPI calculation/scheduled operations. If no timestamp is specified for the filter, only events from the last week are retrieved.

{
  "timestamp": {
    "before": "2023-11-05T10:25:07.166Z"
  }
}

{
  "timestamp": {
    "between": "[2023-11-01T07:25:07.166Z,2023-11-05T10:25:07.166Z)"
  }
}

Filtering by Type ID¶

Provide the typeId for the filter to search among events of a particular event type.

{
  "timestamp": {
    "after": "2018-11-01T07:25:07.166Z"
  }
}

{
  "typeId": "3868feab-9ae6-44a8-9d9e-d20da848afb8",
  "timestamp": {
    "after": "2018-11-01T07:25:07.166Z"
  }
}

Filtering by other Fields¶

Filter by custom fields rather than standard ones, if possible.

{  
  "timestamp":{  
      "between":"[2018-10-01T00:00:00.001Z,2018-10-05T14:53:07.534Z)"
  },
  "entityId":"e7a12da7b60c4402a0a14dce547206ed",
  "acknowledged":false,
  "typeId":"com.siemens.mindsphere.eventmgmt.event.type.MindSphereStandardEvent"
}

{  
  "timestamp":{  
      "between":"[2018-10-01T00:00:00.001Z,2018-10-05T14:53:07.534Z)"
  },
  "entityId":"e7a12da7b60c4402a0a14dce547206ed",
  "acknowledged":false,
  "typeId":"3f690adf-edc8-447f-b1c8-4758aa7924ba",
  "risk": "LOW"
}

Drilldown¶

Sometimes it is faster to do a drilldown, i.e. the filtering is done in multiple steps. For example, the filter expression below filters for a typeId which refers to a custom event type. However, the other filter parameters refer to fields defined in the parent event type. This can make the filtering more expensive.
In such cases it is advised to first replace the typeId by the parent type. Afterwards a drilldown to the for filtering by fields of the custom event type can be done.

{  
  "timestamp":{  
      "between":"[2018-10-01T00:00:00.001Z,2018-10-05T14:53:07.534Z)"
  },
  "entityId":"e7a12da7b60c4402a0a14dce547206ed",
  "acknowledged":false,
  "typeId":"b7f9a843-a530-4159-989e-20645e2b647d"
}

{  
  "timestamp":{  
      "between":"[2018-10-01T00:00:00.001Z,2018-10-05T14:53:07.534Z)"
  },
  "entityId":"e7a12da7b60c4402a0a14dce547206ed",
  "acknowledged":false,
  "typeId":"com.siemens.mindsphere.eventmgmt.event.type.MindSphereStandardEvent"
}

Filtering with PageCache¶

For better performance, set enablePageCache to true along with the filter while retrieving the events. When there are huge number of events satisfying the filter criteria, many subsequent calls are needed for traversing all the pages and retrieving the events. For such cases, we have introduced a new query parameter enablePageCache which can be used as below:

• Set enablePageCache to false for first request. For all subsequent request for different pages, set enablePageCache to true.
• Set enablePageCache to true for all requests if the new events are getting generated less frequently, i.e. having intervals of more than 10 mins.

When this parameter is set to true, total count of events satisfying the filter criteria will be cached for 10 mins and same cached value will be returned in response resulting in near to accurate value. The event information returned will always be the latest.

{  
  enablePageCache : false
}

{  
  enablePageCache : true
}

Sorting¶

For better performance, sort by fields that are present in the filter expression.

{  
  "typeId":"com.siemens.mindsphere.eventmgmt.event.type.MindSphereStandardEvent"
}

{  
  "timestamp":{  
      "between":"[2018-10-01T00:00:00.001Z,2018-11-01T14:53:07.534Z)"
  },
  "typeId":"com.siemens.mindsphere.eventmgmt.event.type.MindSphereStandardEvent"
}

sort: timestamp,desc

'timestamp' field may contain duplicate values. For better performance with pagination add unique value fields in sort parameter like 'id'.

sort: timestamp,id,desc