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 for asynchronous invocations or distributed-context out-of-the-box.
For automated instrumentation for Node.js, please see
@opentelemetry/sdk-trace-node.
Installation
npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-trace-base
Usage
const opentelemetry = require('@opentelemetry/api');
const { BasicTracerProvider } = require('@opentelemetry/sdk-trace-base');
new BasicTracerProvider().register();
const span = opentelemetry.trace.getTracer('default').startSpan('foo');
span.setAttribute('key', 'value');
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({
sampler: new ParentBasedSampler({
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
)
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({
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.