0
# Semantic Convention Stability
1

2
Support for OpenTelemetry semantic convention stability migration, allowing instrumentations to emit stable, old, or both versions of semantic conventions based on configuration.
3

4
## Capabilities
5

6
### SemconvStability Enum
7

8
Enum defining the semantic convention stability options.
9

10
```typescript { .api }
11
/**
12
 * Semantic convention stability options
13
 */
14
enum SemconvStability {
15
  /** Emit only stable semantic conventions */
16
  STABLE = 0x1,
17
  /** Emit only old semantic conventions */
18
  OLD = 0x2,
19
  /** Emit both stable and old semantic conventions */
20
  DUPLICATE = 0x1 | 0x2
21
}
22
```
23

24
**Usage Example:**
25

26
```typescript
27
import { SemconvStability } from "@opentelemetry/instrumentation";
28

29
class HttpInstrumentation extends InstrumentationBase {
30
  private _semconvStability: SemconvStability;
31

32
  constructor(config = {}) {
33
    super("@opentelemetry/instrumentation-http", "1.0.0", config);
34
    
35
    // Configure semconv stability
36
    this._semconvStability = semconvStabilityFromStr(
37
      'http',
38
      process.env.OTEL_SEMCONV_STABILITY_OPT_IN
39
    );
40
  }
41

42
  private _addAttributes(span: Span, request: IncomingMessage) {
43
    // Apply semantic conventions based on stability setting
44
    if (this._semconvStability & SemconvStability.OLD) {
45
      // Old semantic conventions
46
      span.setAttributes({
47
        'http.method': request.method,
48
        'http.url': request.url,
49
        'http.scheme': 'http'
50
      });
51
    }
52

53
    if (this._semconvStability & SemconvStability.STABLE) {
54
      // Stable semantic conventions
55
      span.setAttributes({
56
        'http.request.method': request.method,
57
        'url.full': request.url,
58
        'url.scheme': 'http'
59
      });
60
    }
61
  }
62
}
63
```
64

65
### semconvStabilityFromStr Function
66

67
Parse semantic convention stability configuration from string (typically environment variable).
68

69
```typescript { .api }
70
/**
71
 * Determine appropriate semconv stability for the given namespace
72
 * @param namespace The semantic convention namespace (e.g., 'http', 'database')
73
 * @param str Comma-separated configuration string
74
 * @returns SemconvStability setting for the namespace
75
 */
76
function semconvStabilityFromStr(
77
  namespace: string,
78
  str: string | undefined
79
): SemconvStability;
80
```
81

82
**Usage Examples:**
83

84
```typescript
85
import { semconvStabilityFromStr, SemconvStability } from "@opentelemetry/instrumentation";
86

87
// Parse from environment variable
88
const httpStability = semconvStabilityFromStr(
89
  'http',
90
  process.env.OTEL_SEMCONV_STABILITY_OPT_IN
91
);
92

93
// Example environment variable values and results:
94
// OTEL_SEMCONV_STABILITY_OPT_IN="http" -> SemconvStability.STABLE
95
// OTEL_SEMCONV_STABILITY_OPT_IN="http/dup" -> SemconvStability.DUPLICATE  
96
// OTEL_SEMCONV_STABILITY_OPT_IN="database" -> SemconvStability.OLD (http not mentioned)
97
// OTEL_SEMCONV_STABILITY_OPT_IN="http,database/dup" -> SemconvStability.STABLE (for http)
98

99
// Parse from configuration option
100
const databaseStability = semconvStabilityFromStr(
101
  'database',
102
  config?.semconvStabilityOptIn || process.env.OTEL_SEMCONV_STABILITY_OPT_IN
103
);
104

105
// Multiple namespace support
106
const messagingStability = semconvStabilityFromStr('messaging', 'messaging/dup,http');
107
// Result: SemconvStability.DUPLICATE for messaging
108

109
const k8sStability = semconvStabilityFromStr('k8s', 'http,database,k8s');
110
// Result: SemconvStability.STABLE for k8s
111
```
112

113
### Configuration Patterns
114

115
Common patterns for configuring semantic convention stability in instrumentations.
116

117
**Usage Examples:**
118

119
```typescript
120
// Environment variable based configuration
121
class EnvironmentBasedInstrumentation extends InstrumentationBase {
122
  private _semconvStability: SemconvStability;
123

124
  constructor(config = {}) {
125
    super("@example/instrumentation", "1.0.0", config);
126
    
127
    this._semconvStability = semconvStabilityFromStr(
128
      'http', 
129
      process.env.OTEL_SEMCONV_STABILITY_OPT_IN
130
    );
131
  }
132
}
133

134
// Configuration option based (for browser environments)
135
interface CustomInstrumentationConfig extends InstrumentationConfig {
136
  semconvStabilityOptIn?: string;
137
}
138

139
class ConfigurableInstrumentation extends InstrumentationBase<CustomInstrumentationConfig> {
140
  private _semconvStability: SemconvStability;
141

142
  constructor(config: CustomInstrumentationConfig = {}) {
143
    super("@example/instrumentation", "1.0.0", config);
144
    
145
    this._semconvStability = semconvStabilityFromStr(
146
      'database',
147
      config.semconvStabilityOptIn
148
    );
149
  }
150
}
151

152
// Multi-namespace instrumentation
153
class MultiNamespaceInstrumentation extends InstrumentationBase {
154
  private _httpStability: SemconvStability;
155
  private _databaseStability: SemconvStability;
156

157
  constructor(config = {}) {
158
    super("@example/instrumentation", "1.0.0", config);
159
    
160
    const stabilityConfig = process.env.OTEL_SEMCONV_STABILITY_OPT_IN;
161
    this._httpStability = semconvStabilityFromStr('http', stabilityConfig);
162
    this._databaseStability = semconvStabilityFromStr('database', stabilityConfig);
163
  }
164

165
  private _addHttpAttributes(span: Span, request: any) {
166
    if (this._httpStability & SemconvStability.OLD) {
167
      span.setAttributes({ 'http.method': request.method });
168
    }
169
    if (this._httpStability & SemconvStability.STABLE) {
170
      span.setAttributes({ 'http.request.method': request.method });
171
    }
172
  }
173

174
  private _addDatabaseAttributes(span: Span, query: any) {
175
    if (this._databaseStability & SemconvStability.OLD) {
176
      span.setAttributes({ 'db.statement': query.sql });
177
    }
178
    if (this._databaseStability & SemconvStability.STABLE) {
179
      span.setAttributes({ 'db.query.text': query.sql });
180
    }
181
  }
182
}
183
```
184

185
### Migration Helpers
186

187
Utility functions to help with semantic convention migration.
188

189
**Usage Example:**
190

191
```typescript
192
import { SemconvStability, semconvStabilityFromStr } from "@opentelemetry/instrumentation";
193

194
class MigrationAwareInstrumentation extends InstrumentationBase {
195
  private _semconvStability: SemconvStability;
196

197
  constructor(config = {}) {
198
    super("@example/instrumentation", "1.0.0", config);
199
    this._semconvStability = semconvStabilityFromStr(
200
      'http',
201
      process.env.OTEL_SEMCONV_STABILITY_OPT_IN
202
    );
203
  }
204

205
  // Helper to conditionally set attributes based on stability
206
  private _setConditionalAttributes(span: Span, attributes: {
207
    old?: Record<string, any>;
208
    stable?: Record<string, any>;
209
  }) {
210
    if (attributes.old && (this._semconvStability & SemconvStability.OLD)) {
211
      span.setAttributes(attributes.old);
212
    }
213
    
214
    if (attributes.stable && (this._semconvStability & SemconvStability.STABLE)) {
215
      span.setAttributes(attributes.stable);
216
    }
217
  }
218

219
  // Helper to determine if a specific stability mode is enabled
220
  private _isStabilityEnabled(mode: SemconvStability): boolean {
221
    return (this._semconvStability & mode) !== 0;
222
  }
223

224
  private _instrumentHttpRequest(span: Span, request: IncomingMessage) {
225
    // Using helper method
226
    this._setConditionalAttributes(span, {
227
      old: {
228
        'http.method': request.method,
229
        'http.target': request.url,
230
        'http.scheme': 'http'
231
      },
232
      stable: {
233
        'http.request.method': request.method,
234
        'url.path': request.url,
235
        'url.scheme': 'http'
236
      }
237
    });
238

239
    // Direct checking
240
    if (this._isStabilityEnabled(SemconvStability.OLD)) {
241
      span.setAttributes({
242
        'http.user_agent': request.headers['user-agent']
243
      });
244
    }
245

246
    if (this._isStabilityEnabled(SemconvStability.STABLE)) {
247
      span.setAttributes({
248
        'user_agent.original': request.headers['user-agent']
249
      });
250
    }
251

252
    // Duplicate mode handling
253
    if (this._semconvStability === SemconvStability.DUPLICATE) {
254
      this._diag.debug('Emitting both old and stable semantic conventions');
255
    }
256
  }
257

258
  // Configuration validation helper
259
  private _validateSemconvConfig(): void {
260
    const config = process.env.OTEL_SEMCONV_STABILITY_OPT_IN;
261
    if (config) {
262
      this._diag.debug(`Semconv stability configuration: ${config}`);
263
      this._diag.debug(`Parsed stability for http: ${this._semconvStability}`);
264
      
265
      if (this._semconvStability === SemconvStability.OLD) {
266
        this._diag.warn('Using deprecated semantic conventions. Consider migrating to stable conventions.');
267
      }
268
    }
269
  }
270
}
271
```
272

273
### Namespace Support
274

275
Examples of supported namespaces and their semantic convention domains.
276

277
**Usage Examples:**
278

279
```typescript
280
// HTTP semantic conventions
281
const httpStability = semconvStabilityFromStr('http', stabilityConfig);
282
// Covers: http.method -> http.request.method, http.status_code -> http.response.status_code
283

284
// Database semantic conventions  
285
const dbStability = semconvStabilityFromStr('database', stabilityConfig);
286
// Covers: db.statement -> db.query.text, db.type -> db.system
287

288
// Messaging semantic conventions
289
const messagingStability = semconvStabilityFromStr('messaging', stabilityConfig);
290
// Covers: messaging.system -> messaging.destination.name
291

292
// Kubernetes semantic conventions
293
const k8sStability = semconvStabilityFromStr('k8s', stabilityConfig);
294
// Covers: k8s.pod.name -> k8s.pod.uid, k8s.namespace.name
295

296
// Custom namespace support
297
const customStability = semconvStabilityFromStr('custom-domain', stabilityConfig);
298
// Supports any namespace string for custom semantic conventions
299

300
// Multiple namespaces in one configuration
301
// OTEL_SEMCONV_STABILITY_OPT_IN="http/dup,database,messaging/dup,k8s"
302
const multiConfig = "http/dup,database,messaging/dup,k8s";
303
const httpResult = semconvStabilityFromStr('http', multiConfig);        // DUPLICATE
304
const dbResult = semconvStabilityFromStr('database', multiConfig);      // STABLE  
305
const messagingResult = semconvStabilityFromStr('messaging', multiConfig); // DUPLICATE
306
const k8sResult = semconvStabilityFromStr('k8s', multiConfig);          // STABLE
307
const otherResult = semconvStabilityFromStr('other', multiConfig);      // OLD (default)
308
```