# Context

> OpenTelemetry JavaScript Context API Documentation

---

LLMS index: [llms.txt](/llms.txt)

---

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 specification](/docs/specs/otel/context/)
- [Context API reference](https://open-telemetry.github.io/opentelemetry-js/classes/_opentelemetry_api._opentelemetry_api.ContextAPI.html)

## 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:

```typescript
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](#active-context).

## Context Keys

Context entries are key-value pairs. Keys can be created by calling
`api.createContextKey(description)`.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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 = ctx2.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](https://nodejs.org/api/async_hooks.html) or
[AsyncLocalStorage](https://nodejs.org/api/async_context.html#async_context_class_asynclocalstorage)
in node, or
[zone.js](https://github.com/angular/angular/tree/main/packages/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()`.

```typescript
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`.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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"
```