Metadata

The Overlock agent allows you to store metadata about your IoT devices/nodes, so that you can track patterns about problems. The normal use-case for this is to store details of hardware types and versions which will not change very often.

Example

Let's say you have an telemetry device attached to a tractor. You can attach different equipment to the back of this tractor. This means you can have many different attachments and different types of data coming in.

In terms of being able to learn about what causes problems, it's important to know what versions of hardware and software are in use.

In the setup of the Overlock client libraries (python example), we may want to store the versions of the software:

ol.install("monitoring", {
    # Get hardware type
    "attachment": get_tractor_attachment(),

    # Get versions
    "software-version": get_version(),
    "tractor-version": get_hardware_version(),
    "attachment-version": get_tractor_attachment_version(),
})

Now when an error occurs, it will create a metadata object as follows:

{
    "monitoring": { //Metadata is per-process

        // This lists all the info we added from the `install()` method.
        "attachment": {
            "type": "bailer",
            "name": "bail maker 1000"
        },
        "software-version": "1.1.0",
        "tractor-version": "2.0.2",
        "attachment-version": "1000.0.0"

        // Overlock adds some internal info
        "__overlock": {
            "libraries": {
                "python": "1.0.2"
            }
        }
    }
}

This will be shown on the information screen for each issue so that these trends can be tracked. In future this may be available on an API too.

Another important thing to note here is that the metadata stored here will most likely not be only stored in Overlock, the plan is not to store data you don't have anywhere else, but simply to make it a lot easier to refer to it when looking at specific issues.

Restrictions On Metadata

There are only 3 restrictions:

  1. All metadata must be JSON serializable - any complex objects must be taken care of.
  2. Arbitrarily nested objects can be stored in the metadata, however this may make the display of that quite large! for practical reasons, it's suggested not to nest more than 2 levels deep.
  3. No key names at the top level of metadata may start with a __ (double underscore). Keys starting with this pattern are reserved for use internally by the agent.