Fetching Telemetry Data¶

At some point, users will want to fetch data which was written to the telemetry database (for an example of this, see the mission application tutorial).

This tutorial will walk the user through the process of communicating with the telemetry database service in order to retrieve a desired set of telemetry information.

Setup¶

Install the Kubos SDK or set up the dependencies required for a local dev environment

If you have not done so already, create a clone of the KubOS source repo:

$ git clone https://github.com/kubos/kubos

If you are using the SDK, update all IP addresses in the tools/local_config.toml file, changing them from 127.0.0.1 to 0.0.0.0, so that they are available to your host machine.

Navigate to the kubos source directory and run the following commands to start the telemetry database service in the background (the services may need to be built first, which will take several minutes to complete):

$ cargo run --bin telemetry-service -- -c tools/local_config.toml &

In order to have something to query, we’ll need to seed the database. We’ll use curl to create some HTTP requests which will add data points to the telemetry database.

Note

The example commands will be referencing the telemetry database service port which is defined in the kubos/tools/local_config.toml file, 8020

From your development environment, run the following:

$ curl 0.0.0.0:8020 -H "Content-Type: application/json" --data "{\"query\":\"mutation {insert(subsystem:\\\"eps\\\",parameter:\\\"voltage\\\",value:\\\"5.0\\\"){success}}\"}"
$ curl 0.0.0.0:8020 -H "Content-Type: application/json" --data "{\"query\":\"mutation {insert(subsystem:\\\"eps\\\",parameter:\\\"voltage\\\",value:\\\"5.0\\\"){success}}\"}"
$ curl 0.0.0.0:8020 -H "Content-Type: application/json" --data "{\"query\":\"mutation {insert(subsystem:\\\"eps\\\",parameter:\\\"current\\\",value:\\\"0.1\\\"){success}}\"}"
$ curl 0.0.0.0:8020 -H "Content-Type: application/json" --data "{\"query\":\"mutation {insert(subsystem:\\\"eps\\\",parameter:\\\"current\\\",value:\\\"0.1\\\"){success}}\"}"
$ curl 0.0.0.0:8020 -H "Content-Type: application/json" --data "{\"query\":\"mutation {insert(subsystem:\\\"gps\\\",parameter:\\\"voltage\\\",value:\\\"3.3\\\"){success}}\"}"

Each of these commands should return the following:

{"data":{"insert":{"success":true}}}

GraphiQL¶

Please navigate to http://0.0.0.0:8020/graphiql in order to communicate with the telemetry service for this tutorial. If you are using the SDK, replace 0.0.0.0 with the IP address you defined for your VM.

More information about the GraphiQL interface can be found here.

Schema¶

The telemetry query can be used to fetch a certain selection of data from the telemetry database. It will return an array of database entries.

The query has the following schema:

query {
    telemetry(timestampGe: Float, timestampLe: Float, subsystem: String, parameter: String, parameters: [String], limit: Integer): [{
        timestamp: Float!
        subsystem: String!
        parameter: String!
        value: String!
    }]
}

Each of the input arguments acts as a filter for the database query:

timestampGe - Return entries with timestamps occurring on or after the given value

timestampLe - Return entries with timestamps occurring on or before the given value

subsystem - Return entries which match the given subsystem name

parameter - (Mutually exlusive with parameters) Return entries which match the given parameter name

parameters - (Mutually exlusive with parameter) Return entries which match any of the given parameter names

limit - Return only the first n entries found

Using the telemetry query without specifying any of the input arguments will result in all entries in the telemetry database being returned.

The query returns an array of entries, each of which has the following response fields:

timestamp - The system time when the entry was recorded, in milliseconds since UNIX epoch

subsystem - The subsystem which generated the entry data

parameter - The specific data point the entry corresponds to

value - The value of the data point

Querying a Specific Subsystem¶

In order to return only telemetry generated by a specific subsystem, we’ll send a query using the subsystem input parameter.

For example, to get only telemetry from our (fake) EPS subsystem, we’ll send the following query:

{
  telemetry(subsystem: "eps") {
    timestamp
    subsystem
    parameter
    value
  }
}

The request should return something like this:

{
  "data": {
    "telemetry": [
      {
        "timestamp": 730.855591753,
        "subsystem": "eps",
        "parameter": "current",
        "value": "0.1"
      },
      {
        "timestamp": 730.21144042,
        "subsystem": "eps",
        "parameter": "current",
        "value": "0.1"
      },
      {
        "timestamp": 721.187618335,
        "subsystem": "eps",
        "parameter": "voltage",
        "value": "5.0"
      },
      {
        "timestamp": 688.450861332,
        "subsystem": "eps",
        "parameter": "voltage",
        "value": "5.0"
      }
    ]
  }
}

Querying a Time Frame¶

If we want to fetch the telemetry from a particular time frame, for example all telemetry occurring between 1pm and 2pm, we’ll use a combination of the timestampGe and timestampLe input arguments.

Note

In order to select a timeframe, it is helpful to know the current system time. This can be found by running the following command on the OBC: date +%s. The command gets the current number of seconds since UNIX epoch, which matches the telemetry timestamp units.

Our request should look like this:

{
  telemetry(timestampGe: 730.0, timestampLe: 731.0) {
    timestamp
    subsystem
    parameter
    value
  }
}

This queries the system for telemetry in a 1 second window between 730 and 731, inclusive. You will need to update the query for your specific timestamp range.

The response should look like this:

{
  "data": {
    "telemetry": [
      {
        "timestamp": 730.855591753,
        "subsystem": "eps",
        "parameter": "current",
        "value": "0.1"
      },
      {
        "timestamp": 730.21144042,
        "subsystem": "eps",
        "parameter": "current",
        "value": "0.1"
      }
    ]
  }
}

Limiting the Results¶

Let’s say we only want to know the most recent voltage reading from our EPS subsystem.

We’ll specify the subsystem and parameter input argument to narrow the filters down to the subsystem and parameter we want. We’ll then also use the limit input argument to tell the telemetry database service to only return the single most-recent entry.

Our request should look like this:

{
  telemetry(subsystem: "eps", parameter: "voltage", limit: 1) {
    timestamp
    subsystem
    parameter
    value
  }
}

The response should look like this:

{
  "data": {
    "telemetry": [
      {
        "timestamp": 1573594014.6698866,
        "subsystem": "eps",
        "parameter": "voltage",
        "value": "5.0"
      }
    ]
  }
}