Using device logs

Record device events, and view lifecycle activity in real time

Prerequisites

  • A Xively account
  • Working cURL or other HTTPS client
  • Device Credentials (ID and Secret)
  • Your personal admin credentials (username and password)

Note: This guide will not cover sending logs over HTTP, for that, see Logs.

Anatomy of a log

Log messages must match a specific JSON format. We have built this format to be extremely extensible so you can send whatever log messages you want. This guide will call out the major components that are important, for full descriptions, see Log properties.

{
    "sourceId": "71b9da96-f047-4efe-8aae-39eb989ff6a3",
    "accountId": "3db332e6-265b-44dd-a332-6dce033ddd34",
    "sourceType": "deviceId",
    "code": 4,
    "message": "April 5th Test(MQTT)",
    "details": "could not determine largest block. Platform error 4116",
    "severity": "error",
    "tags": ["selfdiagnostic"],
    "sourceTimestamp": 1459877518000
}
  • sourceId The Blueprint ID of your device, this should be the same as the ID for the credential you plan to send the message with.
  • accountId Your Xively Account ID
  • sourceType The source of the log. Optional. Defaults to "deviceId". code This is a customizable error code. You can use this to group errors of specific types or to communicate a code that your logging is already sending. Example: 400 Note: Optional
  • message This is the short semi-human readable description of the log message. Example: MQTT connection successful. Note: Optional
  • details This can be a longer, deeper explanation of the log such as a stack trace. Note: Optional
  • severity This must be one of the standard syslog levels which are: debug, info, notice, warn, error, alert, critical, emergency. Note: Optional
  • tags You can tag your messages with metadata types in order to make them more searchable later. They should be comma separated in an array. Note: Optional
  • sourceTimestamp Timestamp at which the log occurred in milliseconds since epoch. Example: 1459877518123. Note: Optional

Device lifecycle logs

The following logs are attached to devices automatically:

  • Device defined - the device is created in Xively.
  • Device activated - device password is generated for the first time.
  • Device associated - an association code is used to move the device into a group (organization).
  • Device deleted - the device is deleted (logs can still be queried for deleted devices).
  • Device connected - the device CONNECTs to the message broker.
  • Device disconnected - the device is disconnected from the messaging broker (either with a DISCONNECT or by failing to respond to an MQTT keepalive).

What's Next

How to send a Device Log

Sending a Device Log

Using device logs

Record device events, and view lifecycle activity in real time