Live Objects - complete developer guide

Network metrics (Beta)

Concepts

This service gives you statistics on exchanges between devices and Live Objects. Results are aggregated per bucket (hour, day or week).

For network-metrics, it’s possible to search the aggregated data filtering exchanges regarding their nodeId, direction, timestamp, messageType, groupPath and tags.

For lost messages ratios, it’s possible to search the aggregated data of one device filtering exchanges regarding their timestamp (only coap/dtls uplinks are relevant).

Currently, only LwM2M devices Twin are supported.

API network-metrics

ReST Endpoint

POST /api/v1/network-metrics

with headers:

X-API-Key: <your API key>
Accept: application/json
Content-Type: application/json

Network-metrics filters

Filters are provided in the body of the request.

Field Description

Field	Description
filters.interface.connector	Connector identifier: `lwm2m` for LwM2M devices Twin
filters.interface.nodeId	Optional. Interface unique identifier
filters.direction	Optional. Direction of the exchange: "uplink" : from device to Live Objects "downlink" : from Live Objects to device
filters.messageTypes	Optional. List of message types to filter
filters.groupPath	Optional. Group path to filter, supported filters are → exact match : `/foo`, group and subgroups : `/foo/*`
filters.tags	Optional. List of tags to filter
filters.from	Start date of expected results (inclusive)
filters.to	End date of expected results (inclusive)
timeAggregation.interval	Interval of the aggregated result on the filtered period `hour` : result contains one amount per hour `day` : result contains one amount per day `week` : result contains one amount per week
timeAggregation.timezone	Optional. Timezone applied to the aggregated result on the filtered period. This field matches ISO 8601 UTC offset (e.g. +01:00 or -08:00). UTC timezone is applied by default.
subAggregation.field	Optional. Sub aggregated results on specific field. Supported value is `messageType`

filters.interface.connector

Connector identifier:

lwm2m for LwM2M devices Twin

filters.interface.nodeId

Optional. Interface unique identifier

filters.direction

Optional. Direction of the exchange:

"uplink" : from device to Live Objects
"downlink" : from Live Objects to device

filters.messageTypes

Optional. List of message types to filter

filters.groupPath

Optional. Group path to filter, supported filters are → exact match : /foo, group and subgroups : /foo/*

filters.tags

Optional. List of tags to filter

filters.from

Start date of expected results (inclusive)

filters.to

End date of expected results (inclusive)

timeAggregation.interval

Interval of the aggregated result on the filtered period

hour : result contains one amount per hour
day : result contains one amount per day
week : result contains one amount per week

timeAggregation.timezone

Optional. Timezone applied to the aggregated result on the filtered period.

This field matches ISO 8601 UTC offset (e.g. +01:00 or -08:00).

UTC timezone is applied by default.

subAggregation.field

Optional. Sub aggregated results on specific field. Supported value is messageType

Customer must provide temporal fields ("from", "to" and "interval") which must not lead to the generation of too many buckets :

If the query does not contain a sub aggregation : 1000 buckets max
If the query contains a sub aggregation : 100 buckets max

Network-metrics error case

HTTP Code	Error code	message
400	GENERIC_INVALID_PARAMETER_ERROR	The submitted parameter is invalid. mandatory field is missing "direction" is not known from Live Objects "from" is older than the retention date of network metrics see Network metrics limits maximum number of requested time buckets must be less than 1000 (or 100 if a sub aggregation is requested)
403	FORBIDDEN	Forbidden request

HTTP Code

Error code

message

400

GENERIC_INVALID_PARAMETER_ERROR

The submitted parameter is invalid.

mandatory field is missing
"direction" is not known from Live Objects
"from" is older than the retention date of network metrics see Network metrics limits
maximum number of requested time buckets must be less than 1000 (or 100 if a sub aggregation is requested)

403

FORBIDDEN

Forbidden request

Network-metrics samples

I want to aggregate uplink exchanges of my device from the 02 october 2021 at 12:00:00 to the 03 october 2021 at 12:00:00 aggregated per hour

{
    "filters": {
        "interface": {
            "connector": "lwm2m",
            "nodeId" : "urn:lo:nsid:lwm2m:test12"
        },
        "direction" : "uplink",
        "from" : "2021-10-02T12:00:00Z",
        "to" : "2021-10-03T12:00:00Z"
    },
    "timeAggregation" : {
        "interval" : "hour",
        "timezone" : "+00:00"
    }
}

[
  {
    "timeStart" : "2021-10-02T12:00:00Z",
    "messageCount" : 10
  },
  {
    "timeStart" : "2021-10-02T13:00:00Z",
    "messageCount" : 211
  },
...
...
...
  {
    "timeStart" : "2021-10-03T11:00:00Z",
    "messageCount" : 7
  },
  {
    "timeStart" : "2021-10-03T12:00:00Z",
    "messageCount" : 5
  }
]

I want to aggregate all exchanges of my device from the 01 october 2021 at 00:00:00 to the 31 october 2021 at 23:59:59 aggregated per week

{
    "filters": {
        "interface": {
            "connector": "lwm2m",
            "nodeId" : "urn:lo:nsid:lwm2m:test12"
        },
        "from" : "2021-10-01T00:00:00Z",
        "to" : "2021-10-31T23:59:59Z"
    },
     "timeAggregation" : {
         "interval" : "week"
     }
}

[
  {
    "timeStart" : "2021-09-27T00:00:00Z",
    "messageCount" : 1750
  },
  {
    "timeStart" : "2021-10-04T00:00:00Z",
    "messageCount" : 26110
  },
  {
    "timeStart" : "2021-10-11T00:00:00Z",
    "messageCount" : 25752
  },
  {
    "timeStart" : "2021-10-18T00:00:00Z",
    "messageCount" : 26222
  },
  {
    "timeStart" : "2021-10-25T00:00:00Z",
    "messageCount" : 25862
  }
]

I would like to aggregate all exchanges from my devices in the /france group (or its subgroups) with both the demo and v1 tags, from October 1, 2021 at 00:00:00 to October 2, 2021 at 23:59:59 aggregated per day

{
    "filters": {
        "groupPath" : "/france/*",
        "tags" : ["demo", "v1"],
        "from" : "2021-10-01T00:00:00Z",
        "to" : "2021-10-02T23:59:59Z"
    },
     "timeAggregation" : {
         "interval" : "day"
     }
}

[
  {
    "timeStart" : "2021-10-01T00:00:00Z",
    "messageCount" : 536
  },
  {
    "timeStart" : "2021-10-02T00:00:00Z",
    "messageCount" : 951
  }
]

I want all exchanges of my device from the 05 october 2021 at 00:00:00 to the 08 october 2021 at 23:59:59 aggregated per day and sub aggregated by messageType

{
    "filters": {
        "interface": {
            "connector": "lwm2m",
            "nodeId" : "urn:lo:nsid:lwm2m:test12"
        },
        "from" : "2021-10-05T00:00:00Z",
        "to" : "2021-10-08T23:59:59Z"
    },
     "timeAggregation" : {
         "interval" : "day"
     },
     "subAggregation" : {
        "field" : "messageType"
     }
}

[
  {
    "timeStart" : "2021-10-05T00:00:00Z",
    "subAggregationBuckets": [
        {
            "key": "REGISTER_REQUEST",
            "messageCount": 1
        },
        {
            "key": "UPDATE_REQUEST",
            "messageCount": 25
        }
    ]
  },
  {
    "timeStart" : "2021-10-06T00:00:00Z",
    "subAggregationBuckets": [
        {
            "key": "READ_REQUEST",
            "messageCount": 12
        },
        {
            "key": "READ_RESPONSE",
            "messageCount": 7
        },
        {
            "key": "DEREGISTER_REQUEST",
            "messageCount": 1
        }
    ]
  },
  {
     "timeStart" : "2021-10-08T00:00:00Z",
     "subAggregationBuckets": [
         {
             "key": "REGISTER_REQUEST",
             "messageCount": 1
         },
         {
             "key": "UPDATE_REQUEST",
             "messageCount": 8
         }
     ]
  }
]

API lost messages ratio