Using the API - Understanding snapshotIDs

Introduction

The Instana API is a powerful tool that can be used to query the data stored in the Instana Backend including Metrics, Traces, Rules, Configuration data, etc.  In order to understand how to pull this data, it's key to understand the concepts of the various IDs that are used including (but, not limited to):

  • SnapshotID
  • TraceID
  • SpanID
  • ruleID
  • roleID
  • eventID

This document will describe snapshotIDs which will be used to query Metrics and Configuration data.

Every entity in Instana has a snapshotID.  You can see this by examining the URL when viewing any dashboard - the URL will contain something like &snapshotId=DEF3M_lVQ7GX0A0r62O4GfEd8J where DEF3M_lVQ7GX0A0r62O4GfEd8J is the snapshotID for that entity.

There are two API calls that are useful for querying snaphotIDs:

GET Snapshots:

    {{base}}/api/snapshots?time={{timestampMillis}}&q={{query}}&size={{numberOfResults}}

GET Snapshot:

    {{base}}/api/snapshots/{{snapshotId}}?time={{timestampMillis}}

GET Snapshots

GET Snapshots:

    {{base}}/api/snapshots?time={{timestampMillis}}&q={{query}}&size={{numberOfResults}}

  • q={{query}} - query is the Dynamic Focus Query to pull snapshotIDs for
  • time={{timestampMillis}} - timestampMillis is the UNIX Epoch time in milliseconds for the moment in time you would like to query the data for.  If not specified, current time is used. OPTIONAL
  • size={{numberOfResults}} - numberOFResults allows you to control the amount of data returned. OPTIONAL

With the GET Snapshots API call, you can use Instana's Dynamic Focus Query language to return a set of snapshotIDs matching that query (the q={{query}} argument where {{query}} is the Dynamic Focus Query statement).  This is the same Dynamic Focus Query language you use in the Instana UI and it is often easiest to test the query in the Instana UI and then simply copy/paste it to the API. 

For example:

    {{base}}/api/snapshots?q=entity.selfType:host

would return a list of snapshotIDs representing all of the hosts being monitored by Instana.

GET Snapshot

Get Snapshot:

    {{base}}/api/snapshots/{{snapshotId}}?time={{timestampMillis}}

 

  • {{snapshotID}} - the snapshotID you want to query
  • time={{timestampMillis}} - timestampMillis is the UNIX Epoch time in milliseconds for the moment in time you would like to query the data for.  If not specified, current time is used. OPTIONAL

For example:

    {{base}}/api/snapshots/DEF3M_lVQ7GX0A0r62O4GfEd8J

would return a JSON document describing that snapshotID.  For example:

{
    "id": "DEF3M_-lVQ7GX0A0r62O4GfEd8J",
    "plugin": "host",
    "from": 1532531757000,
    "tags": [],
    "label": "transylvania",
    "entityId": {
        "host": "f2:2c:93:ff:fe:1f:5e:a3",
        "pluginId": "com.instana.forge.infrastructure.os.host.Host",
        "steadyId": "h"
    },
    "data": {
        "cpu.count": 2,
        "interfaces": {
            "eth0": {
                "addresses": [
                    {
                        "subnet": "2b01:7e02:0:0:0:0:0:0",
                        "ip": "2a01:7e01:0:0:f04c:91fe:fe1f:7da3%eth0"
                    },
                    {
                        "subnet": "193.182.162.0",
                        "fqdn": [
                            "li1478-43.members.linuss.com"
                        ],
                        "ip": "139.187.161.43"
                    }
                ],
                "mac": "F2:3E:91:1F:DS:A3"
            },
            "docker0": {
                "addresses": [
                    {
                        "subnet": "172.17.0.0",
                        "ip": "172.17.0.1"
                    }
                ],
                "mac": "02:90:AE:FE:CF:18"
            }
        },
        "hostname": "transylvania",
        "machineId": "9dec9e4e32834cc59a2d5e1c50805ca5",
        "cpu.model": "Intel Xeon E5-2680 v3 @ 2.50GHz",
        "os.arch": "amd64",
        "start": 1525112731000,
        "os.name": "Linux",
        "memory.total": 4130549760,
        "os.version": "4.15.12-x86_64-linode105",
        "tags": []
    }
}

Summary

It's easy to query Configuration/Inventory data for entities using the GET Snapshots and GET Snapshot API calls.  Use the `GET Snapshots` call with the approrpriate Dynamic Focus Query to get the list of snapshotIDs and then use the `GET Snapshot` call to return the JSON document describing that entity.

 

Have more questions? Submit a request

Comments