SignalFx Developers Guide

SignalFlow WebSocket API Request Messages

The SignalFlow streaming analytics service provides REST HTTP endpoints and a WebSocket connection. These APIs let you run SignalFlow programs in background jobs and receive asynchronous results in a stream of control, metadata, and computation messages.

Whenever possible, you should use WebSocket, because it offers these advantages:

  • Multiple data streams and computations using a single HTTP connection

  • Encoding protocol that’s more efficient than the one used by the REST API

  • Overall lower latency

The REST endpoints offer the same functionality, and they’re more straightforward to add to your programs, but they require one HTTP connection per stream.

To learn more about the REST API, see the topic SignalFlow API.

The following sections describe the WebSocket request messages. Refer to the topic SignalFlow Stream Messages Reference for the response messages.

Using WebSocket

To send SignalFlow WebSocket API requests, you need a WebSocket connection. You use this connection to send JSON objects called messages to the API. The API asynchronously sends response messages using the same connection.

Connect

To use the WebSocket API to make SignalFlow requests, you first have to connect to SignalFx using the REST API operation GET https://stream.{REALM}.signalfx.com/v2/signalflow/connect. This operation doesn’t have a response body.

If the request succeeds, you can then send an authentication message using WebSocket.

Authenticate

An authenticate message authenticates your connection by sending an org or user access authentication token. You need to send this message within 5 seconds of establishing the WebSocket connection.

You can also send this message with a new user access token to re-authenticate or switch to another organization without reconnecting. If the token is valid, re-authenticating does not affect running jobs. An invalid token causes the server to close the connection.

Syntax

1
2
3
4
{
  "type": "authenticate",
  "token": "<ACCESS_TOKEN>"
}

Properties

Table 1. Authenticate request: message properties
Property Data type Description

type

string

Must be "authenticate"

token

string

Org or user access token

Execute a computation

Start a new SignalFlow computation by sending an execute message. You need to provide a channel name; SignalFlow puts the name into the streaming data messages emitted by the computation. Also provide the SignalFlow program you want to run.

You can also provide the following optional properties:

  • Job start time

  • Job stop time

  • Data resolution

  • maxDelay (the amount of time SignalFlow should wait for incoming data)

  • List of publish() labels to disable

  • List of detect() labels to disable

Syntax

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "type": "execute",
    "channel": "<CHANNEL_NAME>",
    "program": "<SIGNALFLOW_PROGRAM>",
    "start": <JOB_START_TIME>,
    "stop": <JOB_STOP_TIME>,
    "resolution": <DATA_RESOLUTION>,
    "maxDelay": <MAXIMUM_DELAY>,
    "timezone": "<JOB_TIME_ZONE>",
    "immediate": <IMMEDIATE_FLAG>,
    "disabledPublishLabels": ["label",...],
    "disabledDetectLabels": ["label",...]
}

Properties

Table 2. Execute request: message properties
Property Data type Description

type

string

Must be "execute"

channel

string,⇐ 16 ASCII characters

WebSocket channel name

program

string

SignalFlow program you want to run

start

64-bit integer

Date and time, in milliseconds Unix time, when you want to start the execution1

stop

64-bit integer

Date and time, in milliseconds Unix time, when you want to stop the execution1. See the notes for the immediate property.

resolution

32-bit integer

minimum data resolution in milliseconds

maxDelay

32-bit integer

The maximum time that you want the computation to wait after it detects that input data has stopped arriving, in milliseconds. To get the automatic maximum, specify 0. The maximum delay you can specify yourself is 900000, or 15 minutes.

timezone

string

Specifies the time zone SignalFlow should use as the basis of calendar-related transformations in the computation job. For a list of supported time zones, see the section Supported SignalFlow time zones.

immediate

boolean

If true, overrides the value of stop and stops the computation immediately when data stops arriving

disabledPublishLabels

array of string

List of labels associated with the publish() methods you want to disable for this job, in the form of a JSON array of strings

disableDetectLabels

array of string

List of labels associated with the detect() methods you want to disable for this job, in the form of a JSON array of strings

Notes

1The timezone is UTC, regardless of the value of timezone.

Examples

Simple request with output streaming to your client via channel-1:

1
2
3
4
5
{
  "type": "execute",
  "channel": "channel-1",
  "program": "data('demo.trans.latency').mean(by='demo_customer').stream()"
}

Request with optional arguments, streaming to channel-2. The job starts on May 15, 2019 at 7:10 AM UTC and ends on July 15, 2019 at 7:10 AM UTC. The data resolution is 1 minute.

1
2
3
4
5
6
7
8
{
  "type": "execute",
  "channel": "channel-2",
  "program": "data('demo.trans.latency').mean().stream()",
  "start": 1557904200000,
  "stop": 1563174600000,
  "resolution": 60000
}

Detach from a computation

To detach from a computation and stop receiving its output, send a detach message. Include the channel name you specified when you sent the execute request. If the channel is unknown or is no longer receiving data, SignalFx ignores the request.

SignalFlow includes the reason value when it sends a response.

Syntax

1
2
3
4
5
{
  "type": "detach",
  "channel": "<CHANNEL_NAME>",
  "reason": "<REASON_MESSAGE>"
}

Properties

Table 3. Detach request: message properties
Property Data type Description

type

string

Must be "detach"

channel

string,⇐ 16 ASCII characters

WebSocket channel name you specified in the "execute" request message

reason

string

Reason for detaching. This value is inserted in WebSocket "detach" messages you receive from SignalFlow.

Stop a computation

To stop a computation, send a stop request. You can stop a computation even if your client isn’t connected to it. Clients connected to the computation receive an end of stream response message that includes the value of the reason property you put in your request.

The handle property specifies the job handle you receive from SignalFx in the WebSocket response that contains "event": "JOB_START". See WebSocket response messages.

Syntax

1
2
3
4
5
{
  "type": "stop",
  "handle": "<SIGNALFLOW_JOB_HANDLE",
  "reason": "<REASON_MESSAGE>"
}

Properties

Table 4. Stop request: message properties
Property Data type Description

type

string

Must be "stop"

handle

string

Computation job ID

reason

string

Reason for stopping. This value is inserted in WebSocket "stop" messages you receive from SignalFlow.

© Copyright 2019 SignalFx.

Third-party license information