Join the upcoming Developer Hackathon: Splunk Build-a-thon!Register now

SignalFlow latest

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

Requirements

  • You must have an organization access token with the API permission or a session token to use the API.
  • You must have the Splunk Observability Cloud admin or power role to use the POST /execute, POST /preflight, POST /{id}/stop, and POST /{id}/stop operations.
API Base URL
https://stream.{REALM}.signalfx.com/v2/signalflow
Copy to clipboard

SignalFlow API endpoint URL

 
GET
/connect
Copy full endpoint URL to clipboard

Creates a WebSocket connection with which you can send SignalFlow programs to the system. This request returns HTTP response code 101 if it's successful.

After you have a successful connection, you need to authenticate using a WebSocket message. Send the following JSON within 5 seconds after connecting:

{
    "type": "authenticate",
    "token": "AUTH_TOKEN"
}

If the system drops the connection for any reason, connect and authenticate again. After you start a SignalFlow program, a connection drop doesn't stop the program. If you connect and authenticate again and the authentication fails, the system closes the connection and terminates all programs you sent.

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.

Code Examples
cURL
HTTP
curl -X GET "https://stream.{REALM}.signalfx.com/v2/signalflow/connect" \
    -H "Content-Type: application/json"
Copy to clipboard
Response Body
empty

Splunk Observability Cloud switched your HTTP connection to WebSocket. The system doesn't return a response body.

 
POST
/execute
Copy full endpoint URL to clipboard

Executes the SignalFlow program in the request body and synchronously returns the data to awaiting client. Control the computation by specifying query parameters in the request.

Note: Due to the use of scientific notation in the API, the output of SignalFlow API calls doesn't exactly match the output from SignalFlow programs in charts in the UI.

Headers
Name
Description
Content-Type
Required
string

Format of the request body. Either "text/plain" or "application/json".

X-SF-Token
Required
string

Authentication token

Last-Event-ID
string

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

Query Parameters
Name
Description
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

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.

resolution
integer <int32> >= 0

The minimum data resolution you want to use in the computation, in milliseconds. To learn more about data resolution, see the Splunk Infrastructure Monitoring Analytics topic in the user documentation.

start
integer <int64>
Example: 1557531030000

The date and time that the computation should start, in *nix time in milliseconds

stop
integer <int64>
Example: 1557617430000

The date and time that the computation should stop, in *nix time in milliseconds

timezone
string
Default: "UTC"

Specifies which time zone SignalFlow should use as the basis of time-related calculations in calendar window transformation methods.

For a list of supported time zones, see the section Time Zones Supported by Splunk Observability Cloud.

Code Examples
cURL
HTTP
curl -X POST "https://stream.{REALM}.signalfx.com/v2/signalflow/execute" \
    -H "Content-Type: application/json" \
    -H "X-SF-Token: <value>" \
    -H "Last-Event-ID: <value>" \
    -d '{
            "programText": "A = data(\'trans.latency\').mean(over=Args[\'ui.dashboard_window\']).mean().publish(); detect(when(A>threshold(5))).publish(\'detector_name\');",
            "programArgs": {
                "ui.dashboard_window": "10m"
            }
        }'
Copy to clipboard
Request Body
Content Type: application/json

JSON object or string specifying the SignalFlow program to execute. Both "application/json" and "text/plain" media types are accepted.

If you use "text/plain", provide the SignalFlow program as a string. For example, "A = data('trans.latency').mean().publish(); detect(when(A>threshold(5))).publish('detector_name')".

Note: The equivalent WebSocket request message is described in the SignalFlow WebSocket API Request Messages topic in the Developer Guide

Name
Description
programText
Required
string
Example: A = data('trans.latency').mean(over=Args['ui.dashboard_window']).mean().publish(); detect(when(A>threshold(5))).publish('detector_name');

Text string containing a SignalFlow program that has one or more detect().publish() output streams.

programArgs
object
Example:
{
  "ui.dashboard_window": "10m"
}

Argument values for the SignalFlow program. Use this property only when you use Args construct in programText.

Request Examples
Content Type: application/json
Collapse children
Copy to clipboard
{
  programText: "A = data('trans.latency').mean(over=Args['ui.dashboard_window']).mean().publish(); detect(when(A>threshold(5))).publish('detector_name');",
  programArgs: {
    ui.dashboard_window: "10m"
  }
}
Response Body
empty

Computation execution successfully started. SignalFlow continues to issue SSE responses until the computation is complete.

Response Examples
Content Type: application/json
Copy to clipboard
{
  code: 0,
  message: "string"
}
 
POST
/preflight
Copy full endpoint URL to clipboard

Generates a preview of the number of alerts a detector will generate during a specified time period. In the UI, this feature is called Alert Preview.

In the request body, specify the detector you want to preview as plain text or a JSON object containing a SignalFlow program with one or more detect().publish() output streams.

Note: This is an asynchronous request that returns data to your client in the form of Server-Sent Event (SSE) messages. To learn more about these messages, see the SignalFlow Stream Messages Reference topic in the Developer Guide.

Headers
Name
Description
Content-Type
Required
string

Format of the request body. Either "text/plain" or "application/json".

X-SF-Token
Required
string

Authentication token

Query Parameters
Name
Description
start
Required
integer <int64>
Example: 1556839830000

Preview start timestamp, in *nix time in milliseconds

stop
Required
integer <int64>
Example: 1557012630000

Preview stop timestamp, in *nix time in milliseconds

maxDelay
integer <int32> >= 0
Example: 20000

Maximum time that the computation should wait after input data stops arriving, in milliseconds.

Code Examples
cURL
HTTP
curl -X POST "https://stream.{REALM}.signalfx.com/v2/signalflow/preflight" \
    -H "Content-Type: application/json" \
    -H "X-SF-Token: <value>" \
    -d '{
            "programText": "A = data(\'trans.latency\').mean(over=Args[\'ui.dashboard_window\']).mean().publish(); detect(when(A>threshold(5))).publish(\'detector_name\');",
            "programArgs": {
                "ui.dashboard_window": "10m"
            }
        }'
Copy to clipboard
Request Body
Content Type: application/json

JSON object or text string containing a SignalFlow program that has one or more detect().publish() output streams. Both "application/json" and "text/plain" media types are accepted.

If you use "text/plain", provide the SignalFlow program as a string. For example, "A = data('trans.latency').mean().publish(); detect(when(A>threshold(5))).publish('detector_name')".

Name
Description
programText
Required
string
Example: A = data('trans.latency').mean(over=Args['ui.dashboard_window']).mean().publish(); detect(when(A>threshold(5))).publish('detector_name');

Text string containing a SignalFlow program that has one or more detect().publish() output streams.

programArgs
object
Example:
{
  "ui.dashboard_window": "10m"
}

Argument values for the SignalFlow program. Use this property only when you use Args construct in programText.

Request Examples
Content Type: application/json
Collapse children
Copy to clipboard
{
  programText: "A = data('trans.latency').mean(over=Args['ui.dashboard_window']).mean().publish(); detect(when(A>threshold(5))).publish('detector_name');",
  programArgs: {
    ui.dashboard_window: "10m"
  }
}
Response Body
empty

Successful preview start. Splunk Observability Cloud continues to issue SSE return messages until the preview is complete. To learn more about SSE messages, see the SignalFlow Stream Messages Reference topic in the Developer Guide.

Response Examples
Content Type: application/json
Copy to clipboard
{
  code: 401,
  message: "You must use your user session"
}
 
POST
/start
Copy full endpoint URL to clipboard

Starts the SignalFlow program in the request body in the background and returns only running job ID. Control the computation by specifying query parameters in the request.

Note: Due to the use of scientific notation in the API, the output of SignalFlow API calls doesn't exactly match the output from SignalFlow programs in charts in the UI.

Headers
Name
Description
Content-Type
Required
string

Format of the request body. Either "text/plain" or "application/json".

X-SF-Token
Required
string

Authentication token

Last-Event-ID
string

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

Query Parameters
Name
Description
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.

resolution
integer <int32> >= 0

The minimum data resolution you want to use in the computation, in milliseconds. To learn more about data resolution, see the Splunk Infrastructure Monitoring Analytics topic in the user documentation.

start
integer <int64>
Example: 1557531030000

The date and time that the computation should start, in *nix time in milliseconds

stop
integer <int64>
Example: 1557617430000

The date and time that the computation should stop, in *nix time in milliseconds

timezone
string
Default: "UTC"

Specifies which time zone SignalFlow should use as the basis of time-related calculations in calendar window transformation methods.

For a list of supported time zones, see the section Time Zones Supported by Splunk Observability Cloud.

Code Examples
cURL
HTTP
curl -X POST "https://stream.{REALM}.signalfx.com/v2/signalflow/start" \
    -H "Content-Type: application/json" \
    -H "X-SF-Token: <value>" \
    -H "Last-Event-ID: <value>" \
    -d '{
            "programText": "A = data(\'trans.latency\').mean(over=Args[\'ui.dashboard_window\']).mean().publish(); detect(when(A>threshold(5))).publish(\'detector_name\');",
            "programArgs": {
                "ui.dashboard_window": "10m"
            }
        }'
Copy to clipboard
Request Body
Content Type: application/json

JSON object or string specifying the SignalFlow program to start. "Both "application/json" and "text/plain" media types are accepted.

If you use "text/plain", provide the SignalFlow program as a string. For example, "A = data('trans.latency').mean().publish(); detect(when(A>threshold(5))).publish('detector_name')".

Note: The equivalent WebSocket request message is described in the SignalFlow WebSocket API Request Messages topic in the Developer Guide

Name
Description
programText
Required
string
Example: A = data('trans.latency').mean(over=Args['ui.dashboard_window']).mean().publish(); detect(when(A>threshold(5))).publish('detector_name');

Text string containing a SignalFlow program that has one or more detect().publish() output streams.

programArgs
object
Example:
{
  "ui.dashboard_window": "10m"
}

Argument values for the SignalFlow program. Use this property only when you use Args construct in programText.

Request Examples
Content Type: application/json
Collapse children
Copy to clipboard
{
  programText: "A = data('trans.latency').mean(over=Args['ui.dashboard_window']).mean().publish(); detect(when(A>threshold(5))).publish('detector_name');",
  programArgs: {
    ui.dashboard_window: "10m"
  }
}
Response Body
empty

Successfully started the SignalFlow computation. SignalFlow continues to issue SSE responses until the computation is complete.

Response Examples
Content Type: application/json
Copy to clipboard
{
  code: 0,
  message: "string"
}
 
GET
/{id}id (string): The computation ID returned in the `"handle" property in an SSE message. /feedback
Copy full endpoint URL to clipboard

Retrieves status and feedback messages for a SignalFlow computation

Headers
Name
Description
X-SF-Token
Required
string

Authentication token.

Path Parameters
Name
Description
id
Required
string

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

Code Examples
cURL
HTTP
curl -X GET "https://stream.{REALM}.signalfx.com/v2/signalflow/{id}/feedback" \
    -H "Content-Type: application/json" \
    -H "X-SF-Token: <value>"
Copy to clipboard
Response Body
empty

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

 
POST
/{id}id (string): The computation ID returned in the `"handle" property in an SSE message. SignalFlow stops the computation based on this ID. /stop
Copy full endpoint URL to clipboard

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.

Headers
Name
Description
X-SF-Token
Required
string

Authentication token.

Path Parameters
Name
Description
id
Required
string

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

Code Examples
cURL
HTTP
curl -X POST "https://stream.{REALM}.signalfx.com/v2/signalflow/{id}/stop" \
    -H "Content-Type: application/json" \
    -H "X-SF-Token: <value>"
Copy to clipboard
Response Body
empty

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

Response Examples
Content Type: application/json
Copy to clipboard
{
  code: 0,
  message: "string"
}