@aspecto/opentelemetry-sampler

Aspecto Sampler

Aspecto is an observability platform, powered by OpenTelemetry, that brings R&D teams complete visibility into every interaction, performance issue, and error happening within their distributed services.

If you are looking for a full OpenTelemetry distro, including all instrumentations and features, see @aspecto/opentelemetry

This package exposes an OpenTelemetry Sampler which you can integrate into your own OpenTelemetry installation to apply advance sampling capabilities using Aspecto platform.

Aspecto Sampling

To configure sampling in Aspecto, click here.

Aspecto sampler fetches remote sampling rules that you configure in Aspecto platform and applies them on traces that start in a given service.

It includes the following features:

Remote Configuration

Sampling configuration is fetched from Aspecto platform.

• Configuration is always up-to-date and consistent between all your instances.
• Updates are automatically and immediately pushed to all samplers whenever you make a change.
• Changing configuration does not require writing code, updating dependencies, or deploying artifacts.

Configure in UI

Configure your sampling rules in an easy-to-use UI.

• No need to write code.
• Search capabilities.
• Turn rules on and off in a click.
• Set up temporary rules with timeouts.
• Same UI for multiple languages - configure your rules once and apply them for both NodeJS and Ruby (support for more languages is coming soon)

Rich Sampling Language

Aspecto sampling abstract away the hard parts of the sampling implementation and focus on common use cases, while still allowing advanced configuration for complex scenarios.

• Create specific rules for different workspaces.
• Easily define which service/s and environment/s are affected.
• Add conditions based on span attributes.
• Control the sampling rate, and priority of rules.

Install

npm

npm install @aspecto/opentelemetry-sampler

yarn

yarn add @aspecto/opentelemetry-sampler

Supported node version: >= 14

Usage

Create an instance of AspectoSampler and use it in your TraceProvider

import { AspectoSampler } from '@aspecto/opentelemetry-sampler';

// create an instance of AspectoSampler
const aspectoSampler = new AspectoSampler({
    // aspectoAuth,
    // serviceName,
    // env,
    // requireConfigForTraces,
    // samplingRatio,
});

// Now, you can now use it wherever an OpenTelemetry sampler is acceptable

// NodeTracerProvider
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
const provider = new NodeTracerProvider({
    sampler: aspectoSampler,
});

// NodeSDK
import { NodeSDK } from '@opentelemetry/sdk-node';
const sdk = new NodeSDK({
    traceExporter: // add your trace exporter here
    sampler: aspectoSampler,
});

Configuration

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

• options variable. for example: new AspectoSampler({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

Aspecto auth is required, service name and env are recommended.

Option Name	Environment Variable	Type	Default	Description
disableAspecto	DISABLE_ASPECTO	boolean	false	Disable the sampler and don't apply any sampling logic (sample nothing)
env	NODE_ENV	string	-	Set environment for matching sampling rules
aspectoAuth	ASPECTO_AUTH	UUID	-	Aspecto token for authentication to read sampling configuration
serviceName	OTEL_SERVICE_NAME	string	-	Set service name for matching sampling rules
samplingRatio	ASPECTO_SAMPLING_RATIO	number	1.0	This option is used as a fallback if no specific sampling rule is matched, and before remote sampling rule configuration is fetched. It controls how many of the traces starting in this service should be sampled. Set to number in the range [0.0, 1.0] where 0.0 is no sampling, and 1.0 is sample all.
requireConfigForTraces	ASPECTO_REQUIRE_CONFIG_FOR_TRACES	boolean	false	When true, the Sampler will not trace anything until the remote sampling configuration arrives (a few hundred ms). Can be used to enforce sampling configuration is always applied, with the cost of losing traces generated during service startup.

Getting Help

For any assistance or question, feel free to Contact Us.