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
tofalse
for first request. For all subsequent request for different pages, setenablePageCache
totrue
. - Set
enablePageCache
totrue
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
Except where otherwise noted, content on this site is licensed under the Development License Agreement.