npm package: @mzahor-test-org/open-telemetry
Description: Aspecto auto instrumentation for nodejs applications
Author: Aspecto.io
Latest version: 0.0.52

# Aspecto

Your API is critical for your success and we want to help you protect it.

* [Install](#install)
* [Usage](#usage)
* [Configuration](#configuration)
* [Live Flows](#live-flows)
    * [Connected Mode](#connected-mode)
    * [Isolated Mode](#isolated-mode)
* [FaaS](#faas)
    * [AWS Lambda](#aws-lambda)
    * [Google Cloud Function](#google-cloud-function)

## Install
```sh
npm install @aspecto/opentelemetry
```

## Usage

In the root folder create an `aspecto.json` file with content `{"token" : "-- token goes here --"}`. You can get your token from [here](https://app.aspecto.io/app/integration)

Add this call at the top of your app entry point:

```js
require('@aspecto/opentelemetry')();
```

## Configuration

You can pass the following configuration to the aspecto client:
| Option | Type | Description |
|---|---|---|
|env|string|set environment name manually instead of using `env` environment variable|
|aspectoAuth|UUID|set aspecto token from code instead of using `aspecto.json`|
|packageName|string|set packageName manually instead of reading it from `package.json`|
|packageVersion|string|set packageVersion manually instead of reading it from `package.json`|
|local|boolean|when set to true, enable [live flows](#live-flows)|
|isolate|boolean|when set to true, enable isolated mode for [live flows](#live-flows)|
|liveExporterPort|number|specify port for [live flows](#live-flows)|
|logger|logger interface|logger to be used in this tracing library. common use for debugging `logger: console`|
|customZipkinEndpoint|URL|Send all traces to additional Zipkin server for debug|
|samplingRatio|number|How many of the traces starting in this service should be sampled. set number in range [0.0, 1.0] where `0.0` is no sampling, and `1.0` is sample all.
|exportBatchSize|number|How spans to batch in a single update to the collector. default is 100
|exportBatchTimeout|number|Maximum time in ms for batching spans before sending to collector. default is 1000 (1s)


## Live Flows

Live Flows captures all payloads and traces in your local environment and automatically extract the topology & dependencies between endpoints.
You can activate it using `local: true`, like so:

```js
require('@aspecto/opentelemetry')({
    local: true,
});
```

Live flows can operate in 2 modes:

- Connected
- Isolated

### Connected mode

This is the default mode. It allows you to capture flows from all the microservices that you're running locally (both on the host env and docker) with `local` mode enabled.
Once the process starts it will output the following link:

```
=====================================================================================================================================
|                                                                                                                                   |
| 🕵️‍♀️See the live tracing stream at https://app.aspecto.io/app/live-flows/sessions?instanceId=14243e72-14dc-4255-87af-ef846b247578   |
|                                                                                                                                   |
=====================================================================================================================================
```

You only need to click the link once to see traces from all the microservices, that are running on your environment and have local mode enabled.
Also this link is valid for a limited period of time (couple of days, but it may change in the future).
If you don't see trace from some microservice (or none of them), please click the newly-generated link.

### Isolated mode

In this mode you can only see flows from one microservice. Also, in this case, all the data is being sent directly to the browser.
To activate isolated mode use `isolate` option like so:

```js
require('@aspecto/opentelemetry')({
    local: true,
    isolate: true,
});
```

In isolated mode, the message in the console will look like this (with `port` parameter):

```
===============================================================================================
|                                                                                             |
| 🕵️‍♀️ See the live tracing stream at https://app.aspecto.io/app/live-flows/sessions?port=59778 |
|                                                                                             |
===============================================================================================
```

Note: In case the Live Flows port keep on changing, just add an environment variable `ASPECTO_LIVE_PORT=59778`
In order for live flows to work in isolated mode when running the service inside of the container the port that is used by live flows has to be published (https://docs.docker.com/config/containers/container-networking).

## FaaS

### AWS Lambda

Aspecto supports instrumenting AWS lambdas.  
To do so, set up Aspecto as you'd usually do, and extract the returned `lambda` utility:
```js
const { lambda } = require('@aspecto/opentelemetry')();
```
Next, wrap your function handler definition with the returned utility.

Example:
```js
// Before
module.exports.myCallbackHandler = (event, context, callback) => { ... };
module.exports.myAsyncHandler = async (event, context) => { ... };

// After
module.exports.myCallbackHandler = lambda((event, context, callback) => { ... });
module.exports.myAsyncHandler = lambda(async (event, context) => { ... });
```

Notice: if your lambda is not deployed with a `package.json` file, make sure to provide the `packageName` option when initializing Aspecto.

### Google Cloud Function

Aspecto supports instrumenting GCF with **http trigger**.  
To do so, set up Aspecto as you'd usually do, and extract the `gcf` utility:
```js
const { gcf } = require('@aspecto/opentelemetry')();
```
Next, wrap your function handler definition with the returned utility.
Example:
```js
// Before
exports.myEndpoint = (req, res) => { ... };

// After
exports.myEndpoint = gcf((req, res) => { ... });
```