Install

How to instrument your service using Aspecto

Install the Aspecto SDK for node.js

Aspecto uses OpenTelemetry to collect data.

Install our Node.js library using npm:

$ npm install @aspecto/opentelemetry

Usage

In the root folder create an aspecto.json file with content {"token" : "-- token goes here --"}. Alternatively, you can provide it through ASPECTO_AUTH env param OR aspectoAuthinit option. Obtain your token here.

Add this call at the top of your app entry point, before any other import:

require('@aspecto/opentelemetry')();
// ... other imports ...

Configuration

You can pass a configuration object when initializing Aspecto, like this for example:

require('@aspecto/opentelemetry')({
packageName: 'my-package',
env: 'production',
samplingRatio: 0.1
});

Available configurations are (all optional):

Option

Type

Description

Default

env

string

Set environment name manually

process.env.NODE_ENV

aspectoAuth

UUID

Set Aspecto token from code instead of using aspecto.json

​

packageName

string

Service name

"name" in package.json

packageVersion

string

Service version

"version" is package.json

local

boolean

When set to true, enable live flows​

false

isolate

boolean

When set to true, enable isolated mode for live flows​

false

liveExporterPort

number

Specify port for live flows​

random

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

Rate of traces to be sampled. Between 0 to 1.

Uses parent-based sampling.

1

Live Flows

Live Flows captures all payloads and traces in your local environment and automatically extracts the topology & dependencies between endpoints.

Activate it using {local:true}, like this:

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

Live flows works in two 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) withlocalmode 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 |
| |
=====================================================================================================================================

Click on the link to open the Live Flow, to see traces from all the microservices that are running on your environment that have local mode enabled. The link is valid for a limited period of time (a couple of days, but it may change in the future). If you don't see a trace from some microservice (or none of them), 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:

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: To make sure the port used is consistent between restarts, use the liveExporterPort configuration option.