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.
npm install --save @opentelemetry/api npm install --save @opentelemetry/sdk-trace-baseconst{ 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(newBasicTracerProvider());// 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.constspan=trace.getTracer('default').startSpan('foo');// Set a span attributespan.setAttribute('key','value');// We must end the spans so they become available for exporting.span.end();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).
Sampler is used to make decisions on Span sampling.
Samples every trace regardless of upstream sampling decisions.
This is used as a default Sampler
const{ AlwaysOnSampler, BasicTracerProvider,}=require("@opentelemetry/sdk-trace-base");consttracerProvider=newBasicTracerProvider({sampler: newAlwaysOnSampler()});Doesn't sample any trace, regardless of upstream sampling decisions.
const{ AlwaysOffSampler, BasicTracerProvider,}=require("@opentelemetry/sdk-trace-base");consttracerProvider=newBasicTracerProvider({sampler: newAlwaysOffSampler()});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");consttracerProvider=newBasicTracerProvider({// See details of ParentBasedSampler belowsampler: newParentBasedSampler({// Trace ID Ratio Sampler accepts a positional argument// which represents the percentage of traces which should// be sampled.root: newTraceIdRatioBasedSampler(0.5)});});- This is a composite sampler.
ParentBasedhelps distinguished between the following cases:- No parent (root span).
- Remote parent with
sampledflagtrue - Remote parent with
sampledflagfalse - Local parent with
sampledflagtrue - Local parent with
sampledflagfalse
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");consttracerProvider=newBasicTracerProvider({sampler: newParentBasedSampler({// 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: newTraceIdRatioBasedSampler(0.5)})});See examples/basic-tracer-node for an end-to-end example, including exporting created spans.
- 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
Apache 2.0 - See LICENSE for more information.
