Package Exports
- @opentelemetry/sdk-trace-base
- @opentelemetry/sdk-trace-base/build/esm/index.js
- @opentelemetry/sdk-trace-base/build/esnext
- @opentelemetry/sdk-trace-base/build/esnext/config
- @opentelemetry/sdk-trace-base/build/esnext/config.js
- @opentelemetry/sdk-trace-base/build/esnext/index.js
- @opentelemetry/sdk-trace-base/build/src/MultiSpanProcessor
- @opentelemetry/sdk-trace-base/build/src/MultiSpanProcessor.js
- @opentelemetry/sdk-trace-base/build/src/enums
- @opentelemetry/sdk-trace-base/build/src/enums.js
- @opentelemetry/sdk-trace-base/build/src/export/BatchSpanProcessorBase
- @opentelemetry/sdk-trace-base/build/src/export/BatchSpanProcessorBase.js
- @opentelemetry/sdk-trace-base/build/src/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@opentelemetry/sdk-trace-base) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
OpenTelemetry Tracing SDK
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
flagtrue
- Remote parent with
sampled
flagfalse
- Local parent with
sampled
flagtrue
- Local parent with
sampled
flagfalse
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
)
Parent | parent.isRemote() | parent.isSampled() | Invoke sampler |
---|---|---|---|
absent | n/a | n/a | root() |
present | true | true | remoteParentSampled() |
present | true | false | remoteParentNotSampled() |
present | false | true | localParentSampled() |
present | false | false | localParentNotSampled() |
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
- For more information on OpenTelemetry, visit: https://opentelemetry.io/
- For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
- For help or feedback on this project, join us in GitHub Discussions
License
Apache 2.0 - See LICENSE for more information.