0
# AWS OpenTelemetry X-Ray IdGenerator
1

2
The OpenTelemetry IdGenerator for AWS X-Ray generates trace IDs with its first four bytes set to the start time of the trace followed by a unique identifier consisting of 12 bytes of randomly generated numbers. This enables compatibility with AWS X-Ray service for distributed tracing in cloud environments.
3

4
## Package Information
5

6
- **Package Name**: @opentelemetry/id-generator-aws-xray
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save @opentelemetry/id-generator-aws-xray`
10
- **Peer Dependencies**: `@opentelemetry/api ^1.0.0`
11
- **Dependencies**: `@opentelemetry/sdk-trace-base ^2.0.0`
12

13
## Core Imports
14

15
```typescript
16
import { AWSXRayIdGenerator } from "@opentelemetry/id-generator-aws-xray";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { AWSXRayIdGenerator } = require("@opentelemetry/id-generator-aws-xray");
23
```
24

25
**Additional imports for advanced usage:**
26

27
```typescript
28
import { IdGenerator } from "@opentelemetry/sdk-trace-base";
29
import { INVALID_SPANID, INVALID_TRACEID } from "@opentelemetry/api";
30
```
31

32
## Basic Usage
33

34
```typescript
35
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
36
import { AWSXRayIdGenerator } from "@opentelemetry/id-generator-aws-xray";
37

38
// Configure tracer with AWS X-Ray ID generator
39
const tracerConfig = {
40
  idGenerator: new AWSXRayIdGenerator(),
41
  // other configuration options...
42
};
43

44
const tracerProvider = new NodeTracerProvider(tracerConfig);
45

46
// The ID generator will now create AWS X-Ray compatible trace and span IDs
47
```
48

49
## Architecture
50

51
The AWS X-Ray IdGenerator implements the OpenTelemetry `IdGenerator` interface and provides platform-specific implementations for both Node.js and browser environments:
52

53
- **Cross-platform Support**: Automatic platform detection with optimized implementations
54
- **AWS X-Ray Format Compliance**: Trace IDs follow AWS X-Ray's timestamp + random format
55
- **OpenTelemetry Integration**: Implements the standard `IdGenerator` interface
56
- **Unique ID Generation**: Ensures generated IDs are never all zeros or invalid
57

58
## Capabilities
59

60
### AWSXRayIdGenerator Class
61

62
Main class that implements AWS X-Ray compatible ID generation for OpenTelemetry tracing systems.
63

64
```typescript { .api }
65
/**
66
 * IdGenerator that generates trace IDs conforming to AWS X-Ray format.
67
 * Implements the OpenTelemetry IdGenerator interface.
68
 */
69
class AWSXRayIdGenerator implements IdGenerator {
70
  constructor();
71
  generateTraceId(): string;
72
  generateSpanId(): string;
73
}
74
```
75

76
**Usage Example:**
77

78
```typescript
79
import { AWSXRayIdGenerator } from "@opentelemetry/id-generator-aws-xray";
80

81
const idGenerator = new AWSXRayIdGenerator();
82

83
// Generate AWS X-Ray compatible trace ID
84
const traceId = idGenerator.generateTraceId();
85
console.log(traceId); // e.g., "58406520a006649127e371903a2de979"
86

87
// Generate span ID
88
const spanId = idGenerator.generateSpanId();
89
console.log(spanId); // e.g., "6e3b4749a8b7e2f3"
90
```
91

92
### Trace ID Generation
93

94
Generates a random 16-byte trace ID formatted as a 32-character lowercase hexadecimal string. The first 4 bytes correspond to the current time in Unix epoch seconds (AWS X-Ray format requirement).
95

96
```typescript { .api }
97
/**
98
 * Returns a random 16-byte trace ID formatted/encoded as a 32 lowercase hex
99
 * characters corresponding to 128 bits. The first 4 bytes correspond to the current
100
 * time, in seconds, as per X-Ray trace ID format.
101
 * @returns 32-character hexadecimal trace ID string
102
 */
103
generateTraceId(): string;
104
```
105

106
**Trace ID Format Details:**
107

108
- **Total Length**: 32 hexadecimal characters (128 bits)
109
- **Timestamp**: First 8 hex characters represent Unix epoch time in seconds
110
- **Random Part**: Last 24 hex characters are randomly generated unique identifier
111
- **Example**: `58406520a006649127e371903a2de979`
112
  - `58406520` = timestamp (1480615200 seconds = Dec 1, 2016 10:00 AM PST)
113
  - `a006649127e371903a2de979` = random 24-character identifier
114

115
### Span ID Generation
116

117
Generates a random 8-byte span ID formatted as a 16-character lowercase hexadecimal string. Includes validation to ensure the ID is never all zeros.
118

119
```typescript { .api }
120
/**
121
 * Returns a random 8-byte span ID formatted/encoded as a 16 lowercase hex
122
 * characters corresponding to 64 bits.
123
 * @returns 16-character hexadecimal span ID string
124
 */
125
generateSpanId(): string;
126
```
127

128
**Span ID Details:**
129

130
- **Total Length**: 16 hexadecimal characters (64 bits)
131
- **Validation**: Automatically handles edge case of all-zero random generation
132
- **Fallback**: Uses `0000000000000001` if random generation produces all zeros
133
- **Example**: `6e3b4749a8b7e2f3`
134

135
## Types
136

137
```typescript { .api }
138
/**
139
 * OpenTelemetry IdGenerator interface implemented by AWSXRayIdGenerator
140
 * Import from: @opentelemetry/sdk-trace-base
141
 */
142
interface IdGenerator {
143
  generateTraceId(): string;
144
  generateSpanId(): string;
145
}
146
```
147

148
## Constants
149

150
Relevant OpenTelemetry constants used with ID validation:
151

152
```typescript { .api }
153
/**
154
 * Constants from @opentelemetry/api for ID validation
155
 */
156
const INVALID_SPANID: string;   // "0000000000000000" - invalid span ID
157
const INVALID_TRACEID: string;  // "00000000000000000000000000000000" - invalid trace ID
158
```
159

160
## Platform Support
161

162
- **Node.js**: Requires Node.js ^18.19.0 || >=20.6.0
163
- **Browser**: Compatible with modern browsers supporting ES modules
164
- **TypeScript**: Full TypeScript support with type definitions included
165
- **Module Formats**: Supports both CommonJS and ES modules