Streaming API

Introduction

The streaming API is a WebSocket-based API that allows you to connect to Tentacle and receive data in real time. The API can be used to create custom error pages, draw graphs from returned data, and a lot more.

Host

All endpoints are available on the host stream.gotentacle.com.

Packets

All connections are unidirectional and very similar in how they work: the only difference between connecting to different endpoints is the initial state the client receives upon connection. All endpoints are sent event-packets on updates.

All packets traveling down the wire are encoded as JSON.

Event-packet

Used to transmit the report from a test that just finished running.

{
    "type": "event",
    "event": {
        "context": "200",
        "count": 300,
        "event": "ok",
        "identifier": "32:134",
        "previous_state": "fail",
        "region": "eu",
        "since": "2016-11-15T14:13:00Z",
        "state": "ok",
        "time": 4418,
        "timestamp": "2016-11-21T12:13:28Z",
        "type": "event"
    }
}

Detail-packet

Contains data pertaining to a specific Agent and the test it's running.

{
    "type": "detail",
    "counts":{
        "day":{
            "error": 0,
            "fail": 0,
            "ok": 2824,
            "total": 2824
        },
        "month":{
            "error": 6,
            "fail": 5530,
            "ok": 29982,
            "total": 35518
        },
        "week":{
            "error": 4,
            "fail": 4,
            "ok": 12966,
            "total": 12974
        }
    },
    "events":[
        {
            "context":"200",
            "count":11448,
            "event":"ok",
            "identifier":"9:3",
            "previous_state":"ok",
            "region":"eu",
            "since":"2016-11-15T14:13:00.000000Z",
            "state":"ok",
            "time":5668,
            "timestamp":"2016-11-21T12:23:04.000000Z"
        },
        // ...
    ],
    "percentiles":{
        "day":{
            "50":5773,
            "75":7122,
            "95":10545,
            "99":13213
        },
        "month":{
            "50":5426,
            "75":8319,
            "95":107502,
            "99":173679
        },
        "week":{
            "50":5693,
            "75":7297,
            "95":11283,
            "99":14252
        }
    },
    "states":[
        {
            "context":"200",
            "count":2,
            "event":"ok",
            "identifier":"9:3",
            "previous_state":"unknown",
            "region":"eu",
            "since":"2016-11-15T14:13:00.000000Z",
            "state":"ok",
            "time":4288,
            "timestamp":"2016-11-15T14:13:00.000000Z"
        },
        {
            "context":"200",
            "count":2,
            "event":"ok",
            "identifier":"9:3",
            "previous_state":"fail",
            "region":"eu",
            "since":"2016-11-15T13:03:34.000000Z",
            "state":"ok",
            "time":4019,
            "timestamp":"2016-11-15T13:03:34.000000Z"
        }
    ]
}

State-packet

Contains an overview of all running agents.

{
    "type": "state",
    "agents":[
        {
            "event": "ok",
            "history": [
                4310679,
                130761,
                134259,
                // ....
            ],
            "identifier": "11:5",
            "since": "2016-11-21T12:12:51.000000Z",
            "state": "ok",
            "time": 4310679,
            "timestamp": "2016-11-21T12:13:15.000000Z"
        },
        // ...
    ]
}

Endpoints

Agent list /api/overview

Returns a list of all agents.

Querystring parameters

KeyTypeDescription
api-keyStringYour API key.
accountStringYour account identifier.

Packets

Will receive a State-packet on connection and Event-packets related to the Agent as they occur.

Agent detail /api/detail

Returns a summary for current agent.

Querystring parameters

KeyTypeDescription
api-keyStringYour API key.
accountStringYour account identifier.
idStringAgent identifier.

Packets

Will receive a Detail-packet on connection and Event-packets related to the Agent as they occur.

Examples

All agents overview

The following code will connect to the overview endpoint. A current state will be received on connect and updates will arrive in real-time.

Replace KEY and ACCOUNT with your credentials.

var ws = new WebSocket(
    'wss://stream.gotentacle.com/api/overview/?api-key=KEY&account=ACCOUNT;'
);

ws.onmessage = function(frame) {
    console.log(frame);
};