getContextValue()

Get a value from the trace context by key

Overview

getContextValue() retrieves a value that was previously stored in the trace context. Useful for passing data between spans without function parameters.

Signature

1getContextValue(key: string): any

Basic Usage

1import { RespanTelemetry } from '@respan/tracing';
2
3const respanAi = new RespanTelemetry({
4 apiKey: process.env.RESPAN_API_KEY,
5 appName: 'my-app'
6});
7
8await respanAi.initialize();
9
10await respanAi.withWorkflow(
11 { name: 'user_workflow' },
12 async () => {
13 const client = respanAi.getClient();
14
15 // Set a value in the context
16 client.setContextValue('user_id', 'user-123');
17
18 await respanAi.withTask(
19 { name: 'nested_task' },
20 async () => {
21 // Retrieve the value from context
22 const userId = client.getContextValue('user_id');
23 console.log(`Processing for user: ${userId}`);
24
25 return userId;
26 }
27 );
28
29 return 'complete';
30 }
31);

Sharing Data Across Spans

1await respanAi.withWorkflow(
2 { name: 'order_processing' },
3 async () => {
4 const client = respanAi.getClient();
5
6 // Store order info in context
7 client.setContextValue('order_id', 'ORDER-789');
8 client.setContextValue('customer_id', 'CUST-123');
9
10 await respanAi.withTask(
11 { name: 'validate_order' },
12 async () => {
13 const orderId = client.getContextValue('order_id');
14 return await validateOrder(orderId);
15 }
16 );
17
18 await respanAi.withTask(
19 { name: 'process_payment' },
20 async () => {
21 const orderId = client.getContextValue('order_id');
22 const customerId = client.getContextValue('customer_id');
23 return await processPayment(orderId, customerId);
24 }
25 );
26
27 await respanAi.withTask(
28 { name: 'send_confirmation' },
29 async () => {
30 const customerId = client.getContextValue('customer_id');
31 return await sendEmail(customerId);
32 }
33 );
34
35 return 'order_complete';
36 }
37);

Request Context Propagation

1await respanAi.withWorkflow(
2 { name: 'api_request' },
3 async () => {
4 const client = respanAi.getClient();
5
6 // Store request metadata
7 client.setContextValue('request_id', 'REQ-456');
8 client.setContextValue('user_agent', 'Mozilla/5.0');
9 client.setContextValue('ip_address', '192.168.1.1');
10
11 await respanAi.withTask(
12 { name: 'log_request' },
13 async () => {
14 const requestId = client.getContextValue('request_id');
15 const userAgent = client.getContextValue('user_agent');
16 console.log(`[${requestId}] User-Agent: ${userAgent}`);
17 }
18 );
19
20 await respanAi.withTask(
21 { name: 'process_request' },
22 async () => {
23 const requestId = client.getContextValue('request_id');
24 return await processRequest(requestId);
25 }
26 );
27
28 return 'done';
29 }
30);

Feature Flags

1await respanAi.withWorkflow(
2 { name: 'feature_workflow' },
3 async () => {
4 const client = respanAi.getClient();
5
6 // Store feature flag
7 const newFeatureEnabled = await checkFeatureFlag('new_algorithm');
8 client.setContextValue('new_algorithm_enabled', newFeatureEnabled);
9
10 await respanAi.withTask(
11 { name: 'process_data' },
12 async () => {
13 const useNewAlgorithm = client.getContextValue('new_algorithm_enabled');
14
15 if (useNewAlgorithm) {
16 return await newAlgorithm();
17 } else {
18 return await legacyAlgorithm();
19 }
20 }
21 );
22
23 return 'complete';
24 }
25);

Default Values

1await respanAi.withTask(
2 { name: 'optional_context' },
3 async () => {
4 const client = respanAi.getClient();
5
6 // Get value with fallback
7 const theme = client.getContextValue('theme') || 'default';
8 const locale = client.getContextValue('locale') || 'en-US';
9
10 console.log(`Theme: ${theme}, Locale: ${locale}`);
11
12 return 'done';
13 }
14);

Parameters

key
stringRequired

The key to retrieve from the context

Return Value

Returns the value associated with the key, or undefined if the key doesn’t exist.

Best Practices

  • Use context to share data between spans without passing parameters
  • Store request metadata, user info, or feature flags in context
  • Provide default values when retrieving optional context data
  • Context is scoped to the current trace and its child spans
  • Values must be set with setContextValue() before retrieval
  • Context is useful for cross-cutting concerns like request IDs