0
# OpenTelemetry Context
1

2
OpenTelemetry Context provides a context propagation mechanism for carrying scoped values across API boundaries and between threads in Java applications. It enables thread-local storage and propagation of contextual information such as tracing data, baggage, and other cross-cutting concerns in distributed systems.
3

4
## Package Information
5

6
- **Package Name**: io.opentelemetry:opentelemetry-context
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add dependency to your `pom.xml` or `build.gradle`
10

11
Maven:
12
```xml
13
<dependency>
14
    <groupId>io.opentelemetry</groupId>
15
    <artifactId>opentelemetry-context</artifactId>
16
    <version>1.51.0</version>
17
</dependency>
18
```
19

20
Gradle:
21
```gradle
22
implementation 'io.opentelemetry:opentelemetry-context:1.51.0'
23
```
24

25
## Core Imports
26

27
```java
28
import io.opentelemetry.context.Context;
29
import io.opentelemetry.context.ContextKey;
30
import io.opentelemetry.context.Scope;
31
```
32

33
For context propagation:
34
```java
35
import io.opentelemetry.context.propagation.ContextPropagators;
36
import io.opentelemetry.context.propagation.TextMapPropagator;
37
import io.opentelemetry.context.propagation.TextMapGetter;
38
import io.opentelemetry.context.propagation.TextMapSetter;
39
```
40

41
## Basic Usage
42

43
```java
44
import io.opentelemetry.context.Context;
45
import io.opentelemetry.context.ContextKey;
46
import io.opentelemetry.context.Scope;
47

48
// Create a context key
49
private static final ContextKey<String> USER_ID_KEY = ContextKey.named("userId");
50

51
// Store and retrieve values
52
Context context = Context.current().with(USER_ID_KEY, "user123");
53

54
try (Scope scope = context.makeCurrent()) {
55
    // Context is available to all code within this scope
56
    String userId = Context.current().get(USER_ID_KEY);
57
    
58
    // Context automatically propagates to wrapped operations
59
    Runnable task = Context.current().wrap(() -> {
60
        // This code runs with the current context
61
        String contextUserId = Context.current().get(USER_ID_KEY);
62
        System.out.println("User ID: " + contextUserId);
63
    });
64
    
65
    task.run();
66
}
67
// Previous context is automatically restored
68
```
69

70
## Architecture
71

72
The OpenTelemetry Context API is built around several key concepts:
73

74
- **Context**: Immutable containers that store key-value pairs and form a chain of parent-child relationships
75
- **ContextKey**: Type-safe keys for indexing values within contexts, compared by reference equality
76
- **Scope**: AutoCloseable resources that manage context lifecycle with automatic cleanup
77
- **ContextStorage**: Pluggable storage implementations for managing current context (default uses ThreadLocal)
78
- **Context Propagation**: Cross-process context transmission via text map formats
79

80
## Capabilities
81

82
### Core Context Management
83

84
Fundamental context creation, storage, and retrieval operations for managing scoped values within applications.
85

86
```java { .api }
87
// Context static methods
88
static Context current();
89
static Context root();
90

91
// Instance methods
92
<V> V get(ContextKey<V> key);
93
<V> Context with(ContextKey<V> key, V value);
94
Context with(ImplicitContextKeyed value);
95
Scope makeCurrent();
96
```
97

98
[Core Context Management](./core-context.md)
99

100
### Context Keys and Scoping
101

102
Type-safe key creation and scope management for maintaining context boundaries and automatic cleanup.
103

104
```java { .api }
105
// ContextKey creation
106
static <T> ContextKey<T> named(String name);
107

108
// Scope management  
109
interface Scope extends AutoCloseable {
110
    static Scope noop();
111
    void close();
112
}
113
```
114

115
[Context Keys and Scoping](./context-keys-scoping.md)
116

117
### Executor Integration
118

119
Context-aware wrappers for Java executor services that automatically propagate context across asynchronous operations.
120

121
```java { .api }
122
// Static executor wrapping (uses current context)
123
static Executor taskWrapping(Executor executor);
124
static ExecutorService taskWrapping(ExecutorService executorService);
125
static ScheduledExecutorService taskWrapping(ScheduledExecutorService executorService);
126

127
// Instance executor wrapping (uses specific context)
128
Executor wrap(Executor executor);
129
ExecutorService wrap(ExecutorService executor);
130
ScheduledExecutorService wrap(ScheduledExecutorService executor);
131
```
132

133
[Executor Integration](./executor-integration.md)
134

135
### Function Wrapping
136

137
Context propagation utilities for wrapping various Java functional interfaces including runnables, callables, and lambda expressions.
138

139
```java { .api }
140
// Runnable and Callable wrapping
141
Runnable wrap(Runnable runnable);
142
<T> Callable<T> wrap(Callable<T> callable);
143

144
// Functional interface wrapping
145
<T, U> Function<T, U> wrapFunction(Function<T, U> function);
146
<T, U, V> BiFunction<T, U, V> wrapFunction(BiFunction<T, U, V> function);
147
<T> Consumer<T> wrapConsumer(Consumer<T> consumer);
148
<T, U> BiConsumer<T, U> wrapConsumer(BiConsumer<T, U> consumer);
149
<T> Supplier<T> wrapSupplier(Supplier<T> supplier);
150
```
151

152
[Function Wrapping](./function-wrapping.md)
153

154
### Context Propagation
155

156
Cross-process context propagation via configurable text map propagators for distributed tracing and baggage transmission.
157

158
```java { .api }
159
// Context Propagators
160
static ContextPropagators create(TextMapPropagator textPropagator);
161
static ContextPropagators noop();
162
TextMapPropagator getTextMapPropagator();
163

164
// Text Map Propagation
165
static TextMapPropagator composite(TextMapPropagator... propagators);
166
static TextMapPropagator noop();
167
Collection<String> fields();
168
<C> void inject(Context context, C carrier, TextMapSetter<C> setter);
169
<C> Context extract(Context context, C carrier, TextMapGetter<C> getter);
170
```
171

172
[Context Propagation](./context-propagation.md)
173

174
### Storage Customization
175

176
Pluggable context storage implementations with wrapper support for custom context management strategies and debugging.
177

178
```java { .api }
179
// Context Storage
180
static ContextStorage get();
181
static ContextStorage defaultStorage();
182
static void addWrapper(Function<? super ContextStorage, ? extends ContextStorage> wrapper);
183

184
// Storage operations
185
Scope attach(Context toAttach);
186
Context current();
187
Context root();
188
```
189

190
[Storage Customization](./storage-customization.md)
191

192
### Implicit Context Values
193

194
Interface for values that can be automatically stored in context without exposing explicit context keys.
195

196
```java { .api }
197
interface ImplicitContextKeyed {
198
    Scope makeCurrent();
199
    Context storeInContext(Context context);
200
}
201
```
202

203
[Implicit Context Values](./implicit-context-values.md)
204

205
## Types
206

207
```java { .api }
208
// Core interfaces
209
interface Context {
210
    // Methods documented in capabilities above
211
}
212

213
interface ContextKey<T> {
214
    // Marker interface for type-safe context keys
215
}
216

217
interface Scope extends AutoCloseable {
218
    void close();
219
}
220

221
interface ContextStorage {
222
    Scope attach(Context toAttach);
223
    Context current();
224
    Context root();
225
}
226

227
interface ImplicitContextKeyed {
228
    Scope makeCurrent();
229
    Context storeInContext(Context context);
230
}
231

232
// Propagation interfaces
233
interface ContextPropagators {
234
    TextMapPropagator getTextMapPropagator();
235
}
236

237
interface TextMapPropagator {
238
    Collection<String> fields();
239
    <C> void inject(Context context, C carrier, TextMapSetter<C> setter);
240
    <C> Context extract(Context context, C carrier, TextMapGetter<C> getter);
241
}
242

243
interface TextMapGetter<C> {
244
    Iterable<String> keys(C carrier);
245
    String get(C carrier, String key);
246
    default Iterator<String> getAll(@Nullable C carrier, String key);
247
}
248

249
interface TextMapSetter<C> {
250
    void set(C carrier, String key, String value);
251
}
252

253
// Storage Provider
254
interface ContextStorageProvider {
255
    ContextStorage get();
256
}
257
```