Logs

Introduction

Access Token

Access tokens are the secret passwords that gives access to your resources through the APIs. You can create an API token from the Cloud as described in the introduction.
Make sure to keep your tokens secret and to not publish them publicly to prevent any security breach.

API in use

The Cloud API centralizes all your teams, workspaces, devices, applications, logs and telemetries. hub.stereolabs.com/api/v1

List and query logs

List logs stored in the specified workspace identified by workspaceId. Multiple parameters are available to customize the output of this endpoint.

:workspaceId integer

Id of the target workspace.

fields string_list

optional Log's fields that should be returned by the request. This can be used to reduce amount of data retrieved by only selecting the needed fields. ?fields=timestamp,label,payload

Available fields: id, device_id, timestamp, payload, retention, level, label, application_name, deployment_id, reference, reference_list, processed
Payload fields: A field can also be taken from the payload with the following notation ?fields=payload.temperature,payload.humidity

ids integer_list

optional Filter the logs from their Id. ?ids=125,356,542

devices integer_list

optional Filter logs based on the devices that emitted them. ?devices=1,5

labels string_list

optional Filter logs based on their label. ?labels=detections,environment

start
end timestamp

optional Only target the logs published within the specified the time-range. ?start=1567413071229&end=1567419371229
start and end can be used independently. Timestamps can be provided in the following formats:

start=1567419371229 A milliseconds UTC EPOCH UNIX timestamp.
start=2019-09-02T11:21:11,229+02:00 An ISO8601 datetime string. (must be url-encoded)

levels string_list

optional Filter logs based on their level. ?labels=INFO,WARNING,ERROR

application_names string_list

optional Only targets logs produced by applications matching the listed names (url-encoded). ?application_names=webserver,people counter

deployment_ids integer_list

optional Only targets logs produced by applications instances matching the listed deployment ids. ?deployment_ids=434445,684650

processed boolean

optional Only targets logs that have been marked as read true or not false. ?processed=false

sort
sort_direction field_list
string_list

optional Sort the returned logs by the specified key. ?sort=timestamp&sort_direction=DESC
The order can be specified with the sort_direction parameter that can be DESC or ASC whether you are using descending or ascending sorting. If more than one key is given, the next fields will be used when sorting with the previous key reported an equality. ?sort=label,payload.humidity&sort_direction=ASC,DESC

filter_op
filter_field
filter_value string
field
value

optional Filter out logs that doesn't match the specified condition. ?filter_field=payload.temperature&filter_op=gt&filter_value=30
Only return log with a reported temperature over 30° (where temperature is a custom field in the payload)
Available filter operations are:

gt: is greater than
gte: is greater than or equal
lt: is lower than
lte: is lower than of equal
eq: is equal
neq: is different
contains: is containing the value (string)

To avoid type ambiguity when filtering on a payload key, use the filter_value_type parameter and set it to number or string.
To use more than one filter, append from _1 to _10 at the end of each filter_* parameter. ?filter_field_2=payload.humidity&filter_op_2=eq&filter_value_2=95

agg
agg_field
agg_step string
field
timestamp

optional This parameter will change the output format by returning aggregates of logs in time-intervals rather than a log list.
?agg=mean&agg_field=payload.temperature&start=1567413071229&end=1567419371229
Returns the average temperature in a time-range (where payload.temperature is a custom field).
Available aggregations are:

count: Count the number of logs matching the provided parameters
sum: Sum of the values found in the queried logs for the agg_field
avg: Average of the values found in the queried logs for the agg_field
min: Minimum value found in the queried logs for the agg_field
max: Maximum value found in the queried logs for the agg_field

If an agg_step is provided, result will be split in multiple time ranges, starting from start and incrementing by agg_step up to the end.
An additional agg_identifier can be used to split result in groups based on key's value.
?agg=count&agg_identifier=device_id&start=1567413071229&end=1567419371229&agg_step=36000000
Count the number of logs reported by each device in 10 minutes intervals.

per_page
page
after integer
integer_or_field
value

optional Controls the pagination of the returned log list. ?per_page=25
By default, the logs's timestamp is used to sort the returned page, providing the latest logs first.

Keyset pagination By using page to select the sorting key, and after to specify the position of the page, pagination will return per_page logs starting right after after value. ?per_page=25&page=timestamp&after=1567413071229
Offset pagination By using page as a number, pagination will return per_page logs starting from the most recent one. ?per_page=25&page=1

limit
offset integer
integer

optional Skip some logs (offset) and limits the number of logs returned by the request. ?offset=50&limit=25

logs array

List of logs matching the specified parameters.

/workspaces/:workspaceId/logs

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/logs \
  -G  \
  -d 'labels=storage' \
  -d 'fields=id,device_id,level,timestamp,payload.message' \
  -d 'start=1580201472695' \
  -d 'filter_field=payload.space_left_percent' \
  -d 'filter_op=lt' \
  -d 'filter_value=5' \
  -d 'filter_value_type=number'

HTTP/1.1 200 OK
{
  "logs": [
    {
      "id": "343536",
      "device_id": "67890",
      "level": "WARNING",
      "timestamp": "1580205472695",
      "payload": {
         "message": "Storage space is running low"
      }
    },
    ...
  ]
}

Publish log

Publish a new log from the specified device.

:workspaceId integer

Id of the target workspace.

:deviceNameOrId integer

Id or url-encoded name of the associated device.

label string

A string representing the type of log sent. This field is later used during data consultation to filter relevant logs.

level string

The reported log level in the following list: INFO, WARNING, ERROR.

payload object

The actual log data in a json format. If the payload contains a "message":"" field, this message will be displayed in the interface on the log page.

timestamp timestamp

optional The time at which the log has been generated. Default value is the timestamp at which the request is sent.
Timestamp can be provided in the following formats:

start=1567419371229 A milliseconds UTC EPOCH UNIX timestamp
start=2019-09-02T11:21:11,229+02:00 An ISO8601 datetime string (must be url-encoded)

retention number

optional The retention time of this log in days. If not set, the default value of 1 month (30 days) will be used.

application_name string

optional The name of the application sending the log message. This can be used to identify the application at the origin of the log.

deployment_id integer

optional The deployment id of the application instance sending the log message. This can be used to identify a specific installation and version of an application.

reference
reference_to string
string

optional Can be used to associate logs to a parent one. reference and reference_to CANNOT be used at the same time.

reference: a unique string used as a root reference for yet-to-publish logs
reference_to: the reference string used in a previously-published log

Child-logs with a message in their payload will be displayed as a console output in the parent log on the web interface.

id integer

ID of the created log.

/workspaces/:workspaceId/devices/:deviceNameOrId/logs

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
  -X POST \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/devices/:deviceNameOrId/logs \
  -d '{ 
  "timestamp": 1567416071229, 
  "label": "storage", 
  "level": "WARNING", 
  "payload": { 
    "message":"Storage space is running low",
    "space_left_percent": 4.25
  }
}'

HTTP/1.1 200 OK
{
  "id": "313233"
}

Delete logs

Delete logs matching the parameters.

:workspaceId integer

Id of the target workspace.

ids integer_list

optional Filter the logs from their Id. ?ids=125,356,542

devices integer_list

optional Filter logs based on the devices that emitted them. ?devices=1,5

labels string_list

optional Filter logs based on their label. ?labels=detections,environment

levels string_list

optional Filter logs based on their level. ?levels=INFO,WARNING,ERROR

application_names string_list

optional Only targets logs produced by applications matching the listed names (url-encoded). ?application_names=webserver,people counter

deployment_ids integer_list

optional Only targets logs produced by applications instances matching the listed deployment ids. ?deployment_ids=434445,684650

processed boolean

optional Only targets read logs true or unread ones false. ?processed=true

start
end timestamp

start=1567419371229 A milliseconds UTC EPOCH UNIX timestamp.
start=2019-09-02T11:21:11,229+02:00 An ISO8601 datetime string. (must be url-encoded)

/workspaces/:workspaceId/logs

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
  -X DELETE \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/logs \
  -G  \
  -d 'labels=environment' \
  -d 'levels=ERROR' \
  -d 'start=1580201472695' \
  -d 'end=1580312563849'

HTTP/1.1 200 OK
{}