SignalFx Developers Guide

Developer Home

Product Docs

SignalFx

SignalFlow API

API for streaming data to SignalFlow and managing SignalFlow background computations.

Create WebSocket Connection

Creates a WebSocket connection to SignalFlow

get /connect

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://stream.eu0.signalfx.com/v2/signalflow.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://stream.signalfx.com/v2/signalflow, SignalFx interprets the endpoint as pointing to the us0 realm.

https://stream.{REALM}.signalfx.com/v2/signalflow/connect

Creates a WebSocket connection to SignalFlow. After you have a connection, you can start a SignalFlow background job and receive results from it in WebSocket response objects.
NOTE: Only use this request if you're using WebSocket to communicate with SignalFlow. If you're using REST and SSE, you don't need a WebSocket connection.
If you are using WebSocket, you need to authenticate with SignalFlow after you create the connection. Send the following JSON within 5 seconds after connecting:
{ 'type': 'authenticate', 'token': 'AUTH_TOKEN' }
If SignalFlow drops the connection for any reason, re-connect and re-authenticate. Your existing SignalFlow computations aren't affected by a connection drop unless the re-authentication fails. In that case, SignalFlow closes the connection and terminates all jobs.

header Parameters
X-SF-Token
required
string

A valid access token, either an org token (referred to as an Access Token in the web UI) or a session token (referred to as a User API Access Token in the web UI).

Responses

200

Successful connection. The response doesn't contain a response body.

Start SignalFlow Computation

Starts a SignalFlow computation

post /execute

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://stream.eu0.signalfx.com/v2/signalflow.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://stream.signalfx.com/v2/signalflow, SignalFx interprets the endpoint as pointing to the us0 realm.

https://stream.{REALM}.signalfx.com/v2/signalflow/execute

Starts the computation specified by the SignalFlow program in the request body. Control the computation by specifying query parameters in the request.

query Parameters
start
integer <int64>
Example: 1557531030000

The date and time that the computation should start, in Unix time UTC-relative

stop
integer <int64>
Example: 1557617430000

The date and time that the computation should stop, in Unix time UTC-relative.

resolution
integer <int32>

The minimum data resolution you want to use in the computation, in milliseconds. To learn more about data resolution, see the topic [SignalFx Analytics Overview] (https://docs.signalfx.com/en/latest/reference/analytics-docs/intro-analytics.html) in the SignalFx product documentation.

maxDelay
integer <int32> [ 0 .. 900000 ]

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.

immediate
boolean

Flag that controls the stop timestamp. If true, the flag overrides the stop timestamp, and the computation doesn't wait for future incoming data

timezone
string
Default: "UTC"

Specifies which time zone SignalFlow should use as the basis of time-related calculations in the computation job. calendar window transformation methods.
For a list of supported time zones, see the section [Supported SignalFlow time zones] (https://developers.signalfx.com/signalflow_analytics/signalflow_overview.html#_supported_signalflow_time_zones).

header Parameters
Content-Type
required
string

Format of the request payload. The only allowed value is text/plain, indicating that the request payload contains a SignalFlow program.

X-SF-Token
required
string

A valid session access token (referred to as a User API Access Token in the web UI). If you try to use an org token for authentication, you receive a 401 response.

Last-Event-ID
string

ID of the last Server-Sent Event you received. This value lets you resume a computation that's paused.

Request Body schema: text/plain
string

Responses

200

Successful computation start. SignalFlow continues to issue SSE responses until the computation is complete.

401

Unauthorized. You failed to specify a session token in the X-SF-Token header of the request.

Response Schema: application/json
message
string

Always contains "You must use your user session"

code
integer

Always contains 401

Response samples

application/json
Copy
Expand all Collapse all
{
  • "message": "string",
  • "code": 0
}

Test Detector SignalFlow

Tests a SignalFlow detector program

post /preflight

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://stream.eu0.signalfx.com/v2/signalflow.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://stream.signalfx.com/v2/signalflow, SignalFx interprets the endpoint as pointing to the us0 realm.

https://stream.{REALM}.signalfx.com/v2/signalflow/preflight

Tests how many times a detector would have fired and cleared during a specified time period. You specify the detector as a SignalFlow program that calls the detect() function.

query Parameters
start
required
integer <int64>
Example: 1556839830000

The date and time that the test should start, in Unix time UTC-relative

stop
required
integer <int64>
Example: 1557012630000

The date and time that the test should stop, in Unix time UTC-relative

maxDelay
integer <int64>
Example: 20000

The maximum time that you want the test to wait after it detects that input data has stopped arriving, in milliseconds.

header Parameters
Content-Type
required
string

Format of the request payload. The only allowed value is text/plain, indicating that the request payload contains a SignalFlow program.

X-SF-Token
required
string

A valid session access token (referred to as a User API Access Token in the web UI). If you try to use an org token for authentication, you receive a 401 response.

Request Body schema: text/plain
string

Responses

200

Successful test start. SignalFlow continues to issue SSE responses until the test is complete.

401

Unauthorized. You failed to specify an authentication token in the X-SF-Token header of the request.

Response Schema: application/json
message
string

"You must use your user session"

code
integer

401

Response samples

application/json
Copy
Expand all Collapse all
{
  • "message": "string",
  • "code": 0
}

Retrieve Computation Feedback

Retrieves status and feedback messages for a computation

get /{id}/feedback

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://stream.eu0.signalfx.com/v2/signalflow.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://stream.signalfx.com/v2/signalflow, SignalFx interprets the endpoint as pointing to the us0 realm.

https://stream.{REALM}.signalfx.com/v2/signalflow/{id}/feedback

Retrieves status and feedback messages for a SignalFlow computation

path Parameters
id
required
string

The computation ID returned in the `"handle" property in an SSE message.

header Parameters
X-SF-Token
required
string

A valid session access token (referred to as a User API Access Token in the web UI). If you try to use an org token for authentication, you receive a 401 response.

Responses

200

Successful request for computation feedback. SignalFlow continues to send SSE messages as the computation proceeds.

Stop SignalFlow Computation

Stops a SignalFlow computation

post /{id}/stop

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://stream.eu0.signalfx.com/v2/signalflow.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://stream.signalfx.com/v2/signalflow, SignalFx interprets the endpoint as pointing to the us0 realm.

https://stream.{REALM}.signalfx.com/v2/signalflow/{id}/stop

Stops a SignalFlow computation identified by its ID (computation handle). The computation must belong to the same organization as the user whose access token you used to start the computation.

path Parameters
id
required
string

The computation ID returned in the `"handle" property in an SSE message. SignalFlow stops the computation based on this ID.

header Parameters
X-SF-Token
required
string

A valid session token (referred to as a User API Access Token in the web UI). If you try to use an org token for authentication, you receive a 401 response.
The user who owns this token must belong to the same organization as the computation you're trying to stop.

Responses

200

Successful stop. For this response code, SignalFlow doesn't return a response body.

401

Unauthorized. You failed to specify a session token in the X-SF-Token header of the request.

Response Schema: application/json
message
string

"You must use your user session"

code
integer

401

404

SignalFlow was unable to find the specified computation.

Response Schema: application/json
message
any

"message" : "HTTP 404 Not Found"

Response samples

application/json
Copy
Expand all Collapse all
{
  • "message": "string",
  • "code": 0
}

© Copyright 2019 SignalFx.

Third-party license information