Context
In order for OpenTelemetry to work, it must store and propagate important telemetry data. For example, when a request is received and a span is started it must be available to a component which creates its child span. To solve this problem, OpenTelemetry stores the span in the Context. This document describes the OpenTelemetry context API for JavaScript and how it is used.
More information:
Context Manager
The context API depends on a context manager to work. The examples in this document will assume you have already configured a context manager. Typically the context manager is provided by your SDK, however it is possible to register one directly like this:
import * as api from '@opentelemetry/api';
import { AsyncHooksContextManager } from '@opentelemetry/context-async-hooks';
const contextManager = new AsyncHooksContextManager();
contextManager.enable();
api.context.setGlobalContextManager(contextManager);
Root Context
The ROOT_CONTEXT is the empty context. If no context is active, the
ROOT_CONTEXT is active. Active context is explained below
Active Context.
Context Keys
Context entries are key-value pairs. Keys can be created by calling
api.createContextKey(description).
import * as api from '@opentelemetry/api';
const key1 = api.createContextKey('My first key');
const key2 = api.createContextKey('My second key');
Basic Operations
Get Entry
Entries are accessed using the context.getValue(key) method.
import * as api from '@opentelemetry/api';
const key = api.createContextKey('some key');
// ROOT_CONTEXT is the empty context
const ctx = api.ROOT_CONTEXT;
const value = ctx.getValue(key);
Set Entry
Entries are created by using the context.setValue(key, value) method. Setting
a context entry creates a new context with all the entries of the previous
context, but with the new entry. Setting a context entry does not modify the
previous context.
import * as api from '@opentelemetry/api';
const key = api.createContextKey('some key');
const ctx = api.ROOT_CONTEXT;
// add a new entry
const ctx2 = ctx.setValue(key, 'context 2');
// ctx2 contains the new entry
console.log(ctx2.getValue(key)); // "context 2"
// ctx is unchanged
console.log(ctx.getValue(key)); // undefined
Delete Entry
Entries are removed by calling context.deleteValue(key). Deleting a context
entry creates a new context with all the entries of the previous context, but
without the entry identified by the key. Deleting a context entry does not
modify the previous context.
import * as api from '@opentelemetry/api';
const key = api.createContextKey('some key');
const ctx = api.ROOT_CONTEXT;
const ctx2 = ctx.setValue(key, 'context 2');
// remove the entry
const ctx3 = ctx.deleteValue(key);
// ctx3 does not contain the entry
console.log(ctx3.getValue(key)); // undefined
// ctx2 is unchanged
console.log(ctx2.getValue(key)); // "context 2"
// ctx is unchanged
console.log(ctx.getValue(key)); // undefined
Active Context
IMPORTANT: This assumes you have configured a Context Manager. Without one,
api.context.active() will ALWAYS return the ROOT_CONTEXT.
The active context is the context which is returned by api.context.active().
The context object contains entries which allow tracing components which are
tracing a single thread of execution to communicate with each other and ensure
the trace is successfully created. For example, when a span is created it may be
added to the context. Later, when another span is created it may use the span
from the context as its parent span. This is accomplished through the use of
mechanisms like async_hooks or
AsyncLocalStorage
in node, or
zone.js on the
web in order to propagate the context through a single execution. If no context
is active, the ROOT_CONTEXT is returned, which is just the empty context
object.
Get Active Context
The active context is the context which is returned by api.context.active().
import * as api from '@opentelemetry/api';
// Returns the active context
// If no context is active, the ROOT_CONTEXT is returned
const ctx = api.context.active();
Set Active Context
A context can be made active by use of api.context.with(ctx, callback). During
execution of the callback, the context passed to with will be returned by
context.active.
import * as api from '@opentelemetry/api';
const key = api.createContextKey('Key to store a value');
const ctx = api.context.active();
api.context.with(ctx.setValue(key, 'context 2'), async () => {
// "context 2" is active
console.log(api.context.active().getValue(key)); // "context 2"
});
The return value of api.context.with(context, callback) is the return value of
the callback. The callback is always called synchronously.
import * as api from '@opentelemetry/api';
const name = await api.context.with(api.context.active(), async () => {
const row = await db.getSomeValue();
return row['name'];
});
console.log(name); // name returned by the db
Active context executions may be nested.
import * as api from '@opentelemetry/api';
const key = api.createContextKey('Key to store a value');
const ctx = api.context.active();
// No context is active
console.log(api.context.active().getValue(key)); // undefined
api.context.with(ctx.setValue(key, 'context 2'), () => {
// "context 2" is active
console.log(api.context.active().getValue(key)); // "context 2"
api.context.with(ctx.setValue(key, 'context 3'), () => {
// "context 3" is active
console.log(api.context.active().getValue(key)); // "context 3"
});
// "context 2" is active
console.log(api.context.active().getValue(key)); // "context 2"
});
// No context is active
console.log(api.context.active().getValue(key)); // undefined
Example
This more complex example illustrates how the context is not modified, but new context objects are created.
import * as api from '@opentelemetry/api';
const key = api.createContextKey('Key to store a value');
const ctx = api.context.active(); // Returns ROOT_CONTEXT when no context is active
const ctx2 = ctx.setValue(key, 'context 2'); // does not modify ctx
console.log(ctx.getValue(key)); //? undefined
console.log(ctx2.getValue(key)); //? "context 2"
const ret = api.context.with(ctx2, () => {
const ctx3 = api.context.active().setValue(key, 'context 3');
console.log(api.context.active().getValue(key)); //? "context 2"
console.log(ctx.getValue(key)); //? undefined
console.log(ctx2.getValue(key)); //? "context 2"
console.log(ctx3.getValue(key)); //? "context 3"
api.context.with(ctx3, () => {
console.log(api.context.active().getValue(key)); //? "context 3"
});
console.log(api.context.active().getValue(key)); //? "context 2"
return 'return value';
});
// The value returned by the callback is returned to the caller
console.log(ret); //? "return value"