2.0.1 • Published 5 months ago

@opentelemetry/sdk-trace-base v2.0.1

Weekly downloads
-
License
Apache-2.0
Repository
github
Last release
5 months ago

OpenTelemetry Tracing SDK

NPM Published Version Apache License

The tracing module contains the foundation for all tracing SDKs of opentelemetry-js.

Used standalone, this module provides methods for manual instrumentation of code, offering full control over span creation for client-side JavaScript (browser) and Node.js.

It does not provide automated instrumentation of known libraries, context propagation or distributed-context out-of-the-box.

For a TracerProvider that includes default context management and propagation for Node.js, please see @opentelemetry/sdk-trace-node.

For a TracerProvider that includes default context management and propagation for Browser, please see @opentelemetry/sdk-trace-web.

Installation

npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-trace-base

Usage

const { trace } = require('@opentelemetry/api');
const { BasicTracerProvider } = require('@opentelemetry/sdk-trace-base');

// To start a trace, you first need to initialize the Tracer provider.
// NOTE: The default OpenTelemetry tracer provider does not record any tracing information.
//       Registering a working tracer provider allows the API methods to record traces.
trace.setGlobalTracerProvider(new BasicTracerProvider());

// Important: requires a context manager and propagator to be registered manually.
// propagation.setGlobalPropagator(propagator);     // replace `propagator` with your `TextMapPropagator`, for example: `W3CTraceContextPropagator` from `@openetelemetry/core`
// context.setGlobalContextManager(contextManager); // replace `contextManager` with your `ContextManager`: `AsyncLocalStorageContextManager` from `@openetelemetry/async-hooks`

// To create a span in a trace, we used the global singleton tracer to start a new span.
const span = trace.getTracer('default').startSpan('foo');

// Set a span attribute
span.setAttribute('key', 'value');

// We must end the spans so they become available for exporting.
span.end();

Config

Tracing configuration is a merge of user supplied configuration with both the default configuration as specified in config.ts and an environmentally configurable sampling (via OTEL_TRACES_SAMPLER and OTEL_TRACES_SAMPLER_ARG).

Built-in Samplers

Sampler is used to make decisions on Span sampling.

AlwaysOn Sampler

Samples every trace regardless of upstream sampling decisions.

This is used as a default Sampler

const {
  AlwaysOnSampler,
  BasicTracerProvider,
} = require("@opentelemetry/sdk-trace-base");

const tracerProvider = new BasicTracerProvider({
  sampler: new AlwaysOnSampler()
});

AlwaysOff Sampler

Doesn't sample any trace, regardless of upstream sampling decisions.

const {
  AlwaysOffSampler,
  BasicTracerProvider,
} = require("@opentelemetry/sdk-trace-base");

const tracerProvider = new BasicTracerProvider({
  sampler: new AlwaysOffSampler()
});

TraceIdRatioBased Sampler

Samples some percentage of traces, calculated deterministically using the trace ID. Any trace that would be sampled at a given percentage will also be sampled at any higher percentage.

The TraceIDRatioSampler may be used with the ParentBasedSampler to respect the sampled flag of an incoming trace.

const {
  BasicTracerProvider,
  TraceIdRatioBasedSampler,
} = require("@opentelemetry/sdk-trace-base");

const tracerProvider = new BasicTracerProvider({
  // See details of ParentBasedSampler below
  sampler: new ParentBasedSampler({
    // Trace ID Ratio Sampler accepts a positional argument
    // which represents the percentage of traces which should
    // be sampled.
    root: new TraceIdRatioBasedSampler(0.5)
  });
});

ParentBased Sampler

  • This is a composite sampler. ParentBased helps distinguished between the following cases:
    • No parent (root span).
    • Remote parent with sampled flag true
    • Remote parent with sampled flag false
    • Local parent with sampled flag true
    • Local parent with sampled flag false

Required parameters:

  • root(Sampler) - Sampler called for spans with no parent (root spans)

Optional parameters:

  • remoteParentSampled(Sampler) (default: AlwaysOn)
  • remoteParentNotSampled(Sampler) (default: AlwaysOff)
  • localParentSampled(Sampler) (default: AlwaysOn)
  • localParentNotSampled(Sampler) (default: AlwaysOff)
Parentparent.isRemote()parent.isSampled()Invoke sampler
absentn/an/aroot()
presenttruetrueremoteParentSampled()
presenttruefalseremoteParentNotSampled()
presentfalsetruelocalParentSampled()
presentfalsefalselocalParentNotSampled()
const {
  AlwaysOffSampler,
  BasicTracerProvider,
  ParentBasedSampler,
  TraceIdRatioBasedSampler,
} = require("@opentelemetry/sdk-trace-base");

const tracerProvider = new BasicTracerProvider({
  sampler: new ParentBasedSampler({
    // By default, the ParentBasedSampler will respect the parent span's sampling
    // decision. This is configurable by providing a different sampler to use
    // based on the situation. See configuration details above.
    //
    // This will delegate the sampling decision of all root traces (no parent)
    // to the TraceIdRatioBasedSampler.
    // See details of TraceIdRatioBasedSampler above.
    root: new TraceIdRatioBasedSampler(0.5)
  })
});

Example

See examples/basic-tracer-node for an end-to-end example, including exporting created spans.

Useful links

License

Apache 2.0 - See LICENSE for more information.

@sentry/nodelib-tracingnotnodeagentlog-util-win-otel-final@middleware.io/mw-node-apmsalesforce-opentelemetry@wesjet/utils@chanzuckerberg/edu-platform-observabilitygodspeed-noderenovate@everything-registry/sub-chunk-690@dbos-inc/cloud-clitaskherowrapperopentelemetrysubito-libspectratracksupergraph-demo-opentelemetry@byndyusoft/nest-opentelemetry-configurator@bondsports/telemetry@routr/processor@routr/registry@routr/rtprelay@routr/sdk@routr/simpleauth@routr/simpledata@routr/common@routr/connect@routr/dispatcher@routr/echo@routr/location@routr/pgdata@prisma/extension-optimize@prisma/engine-core@prisma/instrumentation@paychex/instrumentation-document-load@pothos-examples/open-telemetry@prairielearn/opentelemetryiudex-webjohnny-comb-opentelemetry-nodejrf-nestjs-opentelemetryjacksonweber-sampleexpressappkettle-corelangwatchinfrastack-interview-fs-kahdmeetherokuhelios-opentelemetry-sdkhelios-web-sdkhcmprumhcmprumtesthelios-cypress-sdkinstrumentation-document-loadlightstep-opentelemetry-launcher-nodelight-flow-js-sdkmalabimagic-otelllm-report@wevm/alto@wesjet/function.js@wesjetpkg/utils@web3-storage/public-r2-bucket@wundergraph/sdk@worldofgeese/core@twilio/flex-ui@teleflow/application-generic@temporalio/interceptors-opentelemetry@tinybudgie/opentelemetry@tezos-dappetizer/utils@transcend-io/pulumi@tresdoce-nestjs-toolkit/tracing@trigger.dev/core@vtexlab/planner-message-bus@usepreflight/next@usepreflight/trace@unu/observability@uptrace/core@uptrace/node@uptrace/web@vaadin/observability-kit-client@yotamloe/instrumentation-document-load@zalastax/nolb-_opent@zcong/otel-tracingall-backend-commonaliaydin-opentelemetry@zonneplan/open-telemetry-node@zonneplan/open-telemetry-zonneplan@zion-market/utils@zuplo/otelactive-tracerartillery-plugin-publish-metricsaspecto-malabiaspecto-malabi-telemetry-repositoryaspecto-opentelemetry-proto-transformationsappdynamicsapplicationinsightsaperture-sdk@audc/applicationinsights@google-cloud/synthetics-sdk-api@grafana/agent-tracing-web@cisco-telescope/auto-instrumentations-node
2.0.1

5 months ago

2.0.0

7 months ago

1.29.0

11 months ago

1.30.0

10 months ago

1.30.1

9 months ago

2.0.0-rc.1

7 months ago

1.28.0

11 months ago

2.0.0-dev.1

8 months ago

2.0.0-dev.0

8 months ago

1.27.0

12 months ago

1.26.0

1 year ago

1.25.0

1 year ago

1.25.1

1 year ago

1.24.1

1 year ago

1.24.0

1 year ago

1.23.0

2 years ago

1.22.0

2 years ago

1.21.0

2 years ago

1.20.0

2 years ago

1.19.0

2 years ago

1.15.0

2 years ago

1.18.1

2 years ago

1.18.0

2 years ago

1.17.1

2 years ago

1.17.0

2 years ago

1.15.2

2 years ago

1.16.0

2 years ago

1.15.1

2 years ago

1.14.0

2 years ago

1.13.0

2 years ago

1.12.0

3 years ago

1.11.0

3 years ago

1.10.1

3 years ago

1.10.0

3 years ago

1.9.1

3 years ago

1.9.0

3 years ago

1.8.0

3 years ago

1.7.0

3 years ago

1.6.0

3 years ago

1.5.0

3 years ago

1.4.0

3 years ago

1.3.1

3 years ago

1.3.0

3 years ago

1.2.0

3 years ago

1.1.1

4 years ago

1.1.0

4 years ago

1.0.1

4 years ago

1.0.0

4 years ago

0.26.0

4 years ago

0.25.1-alpha.23

4 years ago

0.25.1-alpha.16

4 years ago

0.25.1-alpha.12

4 years ago

0.25.1-alpha.13

4 years ago

0.25.1-alpha.7

4 years ago

0.25.1-alpha.2

4 years ago

0.25.1-alpha.4

4 years ago

0.25.0

4 years ago

0.25.1-alpha.21

4 years ago

0.24.1-alpha.20

4 years ago

0.24.1-alpha.18

4 years ago

0.24.1-alpha.14

4 years ago

0.24.1-alpha.7

4 years ago

0.24.1-alpha.9

4 years ago

0.24.1-alpha.5

4 years ago

0.24.1-alpha.4

4 years ago