Skip to content

Latest commit

 

History

History
205 lines (151 loc) · 7.92 KB

README.md

File metadata and controls

205 lines (151 loc) · 7.92 KB
Raw

GitHub release (latest by date) GitHub branch checks state npm node-current

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