Aspecto

Aspecto enables developers to find, fix and prevent issues before your customers even notice.

• Install
• Usage
• Configuration
• Send Spans Manually
• Add span attributes manually
• Correlate Logs with Traces
• Live Traces
  • Connected Mode
• FaaS
  • AWS Lambda
  • Google Cloud Function

Install

npm install @aspecto/opentelemetry

Usage

In the root folder create an aspecto.json file with the content {"aspectoAuth" : "-- token goes here --"}.

You can get your token from here

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

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

// the rest of your main file requires

See below for more configuration options

Configuration

You can configure the package via one or more of the following:

• options variable. for example: require('@aspecto/opentelemetry')({optionName: optionValue});
  This enables setting config options dynamically.
• Environment variables
• Add aspecto.json configuration file to the root directory, next to service's package.json file

Values are evaluated in the following priority:

1. options object
2. environment variables
3. config file
4. default values

| Option Name | Environment Variable | Type | Default | Description | | --- | --- | --- | --- | --- | | disableAspecto | DISABLE_ASPECTO | boolean | false | disable aspecto | | env | NODE_ENV | string | - | environment name | | aspectoAuth | ASPECTO_AUTH | UUID | - | Aspecto's API key for authentication | | packageName | ASPECTO_PACKAGE_NAME | string | name key in package.json | set packageName manually instead of reading it from package.json. For example: a service that runs in multiple "modes" | | packageVersion | ASPECTO_PACKAGE_VERSION | string | version key in package.json | set packageVersion manually instead of reading it from package.json | | local | - | boolean | false | when set to true, enable live flows | | ciReport | ASPECTO_CI_REPORT | boolean | false | set to true to indicate running the service from CI environment for testing | | logger | - | logger interface | - | logger to be used in this tracing library. common use for debugging logger: console | | writeSystemLogs | - | boolean | false | If true, emit all log messages from Opentelemetry SDK to supplied logger if present, or to console if missing | | samplingRatio | ASPECTO_SAMPLING_RATIO | number | 1.0 | How many of the traces starting in this service should be sampled. set to number in range [0.0, 1.0] where 0.0 is no sampling, and 1.0 is sample all. Specific rules set via aspecto app takes precedence | | waitForSamplingRules | ASPECTO_WAIT_FOR_SAMPLING_RULES | boolean | false | When true, the SDK will not trace anything until remote sampling configuration arrives (few hundreds ms). Can be used to enforce sampling configuration is always applied, with the cost of losing traces generated during service startup. | | collectPayloads | ASPECTO_COLLECT_PAYLOADS | boolean | true | Should aspecto SDK collect payloads of operations | | exportBatchSize | ASPECTO_EXPORT_BATCH_SIZE | number | 100 | How many spans to batch in a single export to the collector | | exportBatchTimeoutMs | ASPECTO_EXPORT_BATCH_TIMEOUT_MS | number | 1000 (1s) | Maximum time in ms for batching spans before sending to collector | | sqsExtractContextPropagationFromPayload | ASPECTO_SQS_EXTRACT_CONTEXT_PROPAGATION_FROM_PAYLOAD | boolean | true | for aws-sdk instrumentation. should be true when the service receiveMessages from SQS which is subscribed to SNS and subscription configured with "Raw message delivery": Disabled. setting to false is a bit more performant as it turns off JSON parse on message payload |

Send Spans Manually

Background

"Span" is the name of the data structure representing an interesting operation in your app.
Aspecto will automatically collect spans for operations created by popular packages that perform IO (such as http, messaging systems, databases, etc).
Manual spans are used if you need to trace an operation in a code you wrote, or when using a package that does not provide an automatic tracing.

Example

To create a Manual Span for a function run, you need to wrap it in a trace call like this:

import { trace } from '@aspecto/opentelemetry'; // ES import
const { trace } = require('@aspecto/opentelemetry'); // CommonJS require

trace(
    // All options are optional
    {
        name: '** optional name for the operation **',
        metadata: {
            'metadata.key.for.the.operation': 'you can attach custom metadata to the operation',
        },
        type: 'Type of Operation',
    },
    () => {
        // your code which you want to trace
    }
);

Add span attributes manually

You can add attributes to your spans for more visibility.
Attributes can be added to a span at any time before the span is finished:

import { setAttribute, setAttributes } from '@aspecto/opentelemetry';

// add a single attribute
const result = setAttribute('foo', 'bar');

// add multiple attributes
const result = setAttributes({ foo: 'bar' });

// result will be true in case of success

(*) All keys will get a prefix of 'aspecto.extra'.

Correlate Logs with Traces

A common use case for the Trace Search tool is to see the related trace while inspecting a log event.
To do this, you must attach an active traceId to your logs.

Example

Use the getContext method, exposed from our package, to attach traceId to your logs:

const { getContext } = require('@aspecto/opentelemetry');

console.log('Something happened!', { traceId: getContext().traceId })});

Live Traces

Live Traces 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:

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

This allows you to capture traces 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-traces/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.

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:

const { lambda } = require('@aspecto/opentelemetry')();

Next, wrap your function handler definition with the returned utility.

Example:

// 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:

const { gcf } = require('@aspecto/opentelemetry')();

Next, wrap your function handler definition with the returned utility. Example:

// Before
exports.myEndpoint = (req, res) => { ... };

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

Test Frameworks

Mocha

To instrument your test with aspecto using mocha version 8.0.0 and above, register mocha plugin as instructed below. In this mode, token (and other configuration) can be set only via aspecto.json config file or environment variables.

With CLI

mocha --require @aspecto/opentelemetry/mocha

With Mocha Config in package.json

  "mocha": {
    "require": [
      "@aspecto/opentelemetry/mocha"
    ]
  }

Config File

{
    "require": [
        "@aspecto/opentelemetry/mocha"
    ]
}