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
, andPOST /{id}/stop
operations.
API Base URL
SignalFlow API endpoint URL
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 -X GET "https://stream.{REALM}.signalfx.com/v2/signalflow/connect" \
-H "Content-Type: application/json"
Response Body
Splunk Observability Cloud switched your HTTP connection to WebSocket. The system doesn't return a response body.
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 |
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 |
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 |
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 -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"
}
}'
Request Body
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 |
programArgs | object Example:
Argument values for the SignalFlow program. Use this property only when you use |
Request Examples
{ 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
Computation execution successfully started. SignalFlow continues to issue SSE responses until the computation is complete.
Response Examples
{ code: 0, message: "string"}
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 |
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 -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"
}
}'
Request Body
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 |
programArgs | object Example:
Argument values for the SignalFlow program. Use this property only when you use |
Request Examples
{ 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
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
{ code: 401, message: "You must use your user session"}
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 |
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 |
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 -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"
}
}'
Request Body
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 |
programArgs | object Example:
Argument values for the SignalFlow program. Use this property only when you use |
Request Examples
{ 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
Successfully started the SignalFlow computation. SignalFlow continues to issue SSE responses until the computation is complete.
Response Examples
{ code: 0, message: "string"}
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 -X GET "https://stream.{REALM}.signalfx.com/v2/signalflow/{id}/feedback" \
-H "Content-Type: application/json" \
-H "X-SF-Token: <value>"
Response Body
Successful request for computation feedback. SignalFlow continues to send SSE messages as the computation proceeds.
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 -X POST "https://stream.{REALM}.signalfx.com/v2/signalflow/{id}/stop" \
-H "Content-Type: application/json" \
-H "X-SF-Token: <value>"
Response Body
Successful stop. For this response code, SignalFlow doesn't return a response body.
Response Examples
{ code: 0, message: "string"}