SignalFlow library for JavaScript

Install the client

To install using npm:

npm install signalflow

Supported Node.js versions

| Version | Node.js | | ------- | --------------- | | 8.x.x | >=12.10.0 <= 20 | | 7.4.x | >=8.0.0 < 18 | | 7.3.1 | >=8.0.0 < 11 |

Usage

Configure the SignalFlow websocket endpoint

The default realm is us0, unless you manually set the websocket endpoint. If you aren't in the us0 realm, you must explicitly add it to the URL endpoint. For example, https://ingest.us1.signalfx.com.

To determine which realm you are in:

1. Log in to the SignalFx web application.
2. In the left-side menu, navigate to Settings, then View Profile.
3. Select the Organizations tab to view your realm.

Example

The following is a complete code example for executing a computation:

var signalflow = require('signalflow');

var wsCallback = function(evt) {
    console.log("Hello, I'm a custom callback: " + evt);
}

var myToken = '[ACCESS_TOKEN]';
var options = {'signalflowEndpoint': 'wss://stream.{REALM}.signalfx.com',
               'apiEndpoint': 'https://api.{REALM}.signalfx.com',
               'webSocketErrorCallback': wsCallback
              };

var client = new signalflow.SignalFlow(myToken, options);

var handle = client.execute({
            program: "data('cpu.utilization').mean().publish()",
            start: Date.now() - 60000,
            stop: Date.now() + 60000,
            resolution: 10000,
            immediate: false});

handle.stream(function(err, data) { console.log(data); });

The options object is an optional map and can contain following fields:

| Field | Type | Description | Default | |--------------------------|----------|---------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------| | signalflowEndpoint | string | Sets the SignalFlow endpoint. | wss://stream.us0.signalfx.com. If you aren't in us0, change the realm. | | apiEndpoint | string | Sets the API endpoint. | https://api.us0.signalfx.com. If you aren't in us0, change the realm. | | webSocketErrorCallback | function | Sets the callback function that is invoked when a WebSocket error occurs. | If a callback function is not set, the WebSocket error is thrown. |

Note: A token created using the REST API is necessary to use this API. API Access tokens intended for ingest are not allowed.

API options

The execute() method accepts the following parameters:

| Parameter | Type | Description | Default | Required | |--------------|--------------------|-----------------------------------------------------------------------------------------------------------------|--------------------------------|----------| | program | string | The signalflow program to be run. | | Yes | | start | int | string | A milliseconds-since-epoch number or a string representing a relative time. For example: -1h. | now | No | | stop | int | string | A milliseconds-since-epoch number or a string representing a relative time. For example: -30m. | infinity | No | | resolution | int | The interval across which to calculate, in 1000 millisecond intervals. | 1000 | No | | maxDelay | int | The maximum time to wait for a datapoint to arrive, in 10000 millisecond intervals. | dynamic | No | | bigNumber | boolean | Sets whether to return all values in data messages as BigNumber objects. Set to true if you require returned values to have precision beyond MAX_SAFE_INTEGER. For more information, see bignumber.js. | false | No | | immediate | boolean | Sets whether to adjust the stop timestamp so that the computation doesn't wait for future data to be available. | | No |

Computation object methods

Calls to execute() return an object that has the following methods:

| Method | Parameters | Description | |-------------------|-------------------------|-----------------------------------------------------------------------| | stream | (function (err, data)) | Accepts a function and calls the function with computation messages when available. Returns multiple types of messages, each of which is detailed below. Following error-first callback conventions, data is returned in the second argument if no errors occurred. | | close | () | Terminates the computation. | | get_known_tsids | () | Gets all known timeseries IDs for the current computation. | | get_metadata | (string) | Gets the metadata message associated with the specific timeseries ID. |

Stream message types

Metadata:

{
  type : "metadata",
  channel : "<CHID>",
  properties : {
    sf_key : [<String>]
    sf_metric: <String>
    ...
  },
  tsId : "<ID>"
}

Data:

{
  type : "data",
  channel : "<CHID>",
  data : [
    {
      tsId : "<ID>",
      value : <Number>
    },
    ...
  ],
  logicalTimestampMs : <Number>
}

Event:

{
  tsId : "<ID>",
  timestampMs: 1461353198000,
  channel: "<CHID>",
  type: "event",
  properties: {
    incidentId: "<ID>",
    "inputValues" : "{\"a\":4}",
    was: "ok",
    is: "anomalous"
  }
}

Use in a web browser

The signalflow client can be built for use in a browser.

1. Run the following commands:

   npm install
   npm run build:browser

   Expected output:

   The output can be found at ./build/signalflow.js

2. Load the client using a script tag:

   <script src="build/signalflow.js" type="text/javascript"></script>

   Once loaded, a global signalfx object is available in the browser. Note that the built file only includes the SignalFlow package.

Browser Usage Example using D3

First ensure your current working directory is the root of the repository clone.

Make the following changes to example/index.html:

replace 'ACCESS_TOKEN' with your own token.
replace 'cpu.utilization' with an appropriate metric as necessary.

Execute the following commands:

$ npm install
$ node example/server.js

Finally, open http://localhost:8888/example/index.html

License

Apache Software License v2 © Splunk