Skip to content

Commit

Permalink
Edit README (#3)
Browse files Browse the repository at this point in the history 
* Edit README

* Make changes from Siim feedback

* Make changes that Siim requested

* Change webSocketErrorCallback default description
  • Loading branch information
@pauljwil
pauljwil authored Jul 26, 2024
1 parent 885ffe9 commit ac7c08a
Showing 1 changed file with 68 additions and 50 deletions.
118 changes: 68 additions & 50 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,35 +9,39 @@

# SignalFlow library for JavaScript

## Installation
## Install the client

To install using npm:

```sh
$ npm install signalflow
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` |
| `8.x.x` | `>=12.10.0 <= 20` |
| `7.4.x` | `>=8.0.0 < 18` |
| `7.3.1` | `>=8.0.0 < 11` |

## Usage

### Configuring the Signalflow websocket endpoint
### Configure the SignalFlow websocket endpoint

If the websocket endpoint is not set manually, this library uses the `us0` realm by default.
If you are not in this realm, you will need to explicitly set the
endpoint urls above. To determine if you are in a different realm and need to
explicitly set the endpoints, check your profile page in the SignalFx
web application.
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``.

### Examples
To determine which realm you are in:

Complete code example for executing a computation
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:

```js
var signalflow = require('signalflow');
Expand All @@ -64,38 +68,45 @@ var handle = client.execute({
handle.stream(function(err, data) { console.log(data); });
```

Object `options` is an optional map and may contains following fields:
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. |

- **signalflowEndpoint** - string, `wss://stream.us0.signalfx.com` by default. Override this if you are in a different realm than `us0`.
- **apiEndpoint** - string, `https://api.us0.signalfx.com` by default. Override this if you are in a different realm than `us0`.
- **webSocketErrorCallback** - function, Throws an Error event by default. Override this if you want to handle a websocket error differently.

**Note**: A token created via the REST API is necessary to use this API. API Access tokens intended for ingest are not allowed.
> **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
### API options

Parameters to the execute method are as follows :
The `execute()` method accepts the following parameters:

- **program** (string) - Required field. The signalflow to be run.
- **start** (int | string) - A milliseconds since epoch number or a string representing a relative time : e.g. -1h. Defaults to now.
- **stop** (int | string) - A milliseconds since epoch number or a string representing a relative time : e.g. -30m. Defaults to infinity.
- **resolution** (int) - The interval across which to calculate, in 1000 millisecond intervals. Defaults to 1000.
- **maxDelay** (int) - The maximum time to wait for a datapoint to arrive, in 10000 millisecond intervals. Defaults to dynamic.
- **bigNumber** (boolean) - True if returned values require precision beyond MAX_SAFE_INTEGER. Returns all values in data messages as bignumber objects as per https://www.npmjs.com/package/bignumber.js Defaults to false.
- **immediate** (boolean) - Whether to adjust the stop timestamp so that the computation doesn't wait for future data to be available.
| 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](https://www.npmjs.com/package/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 Objects
### Computation object methods

The returned object from an execute call possesses the following methods:
Calls to `execute()` return an object that has the following methods:

- **stream** (function (err, data)) - accepts a function and will call the function with computation messages when available. It returns multiple types of messages, detailed below. This follows error first callback conventions, so data is returned in the second argument if no errors occurred.
- **close** () - terminates the computation.
- **get_known_tsids** () - gets all known timeseries ID's for the current computation
- **get_metadata** (string) - gets the metadata message associated with the specific timeseries ID.
| 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
### Stream message types

- Metadata
**Metadata:**

```js
{
Expand All @@ -110,7 +121,7 @@ The returned object from an execute call possesses the following methods:
}
```

- Data
**Data:**

```js
{
Expand All @@ -127,7 +138,7 @@ The returned object from an execute call possesses the following methods:
}
```

- Event
**Event:**

```js
{
Expand All @@ -144,24 +155,31 @@ The returned object from an execute call possesses the following methods:
}
```

#### Usage in a Web Browser
### Use in a web browser

The signalflow client can be built for usage in a browser. This is accomplished via the following commands.
The signalflow client can be built for use in a browser.

```
$ npm install
$ npm run build:browser
The output can be found at ./build/signalflow.js
```
1. Run the following commands:

It can then be loaded as usual via a script tag
```
npm install
npm run build:browser
```

```
<script src="build/signalflow.js" type="text/javascript"></script>
```
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, signalfx global will be created(window.signalfx). Note that only the SignalFlow package is included in this built file.
Once loaded, a global ``signalfx`` object is available in the browser. Note that the built file only includes the SignalFlow package.

## License

Apache Software License v2 © [Splunk](https://ww.splunk.com)
Apache Software License v2 © [Splunk](https://www.splunk.com)

0 comments on commit ac7c08a

Please sign in to comment.