Add external propagation context support and export SENTRY_API_VERSION

Author: andreiborza

packages/core/src/api.ts

@@ -3,7 +3,7 @@ import type { DsnComponents, DsnLike } from './types-hoist/dsn';
 importtype{SdkInfo}from'./types-hoist/sdkinfo';
 import{dsnToString,makeDsn}from'./utils/dsn';
 
-constSENTRY_API_VERSION='7';
+exportconstSENTRY_API_VERSION='7';
 
 /** Returns the prefix to construct Sentry ingestion API endpoints. */
 functiongetBaseApiEndpoint(dsn: DsnComponents): string{

packages/core/src/currentScopes.ts

@@ -5,6 +5,31 @@ import { Scope } from './scope';
 importtype{TraceContext}from'./types-hoist/context';
 import{generateSpanId}from'./utils/propagationContext';
 
+let_externalPropagationContextProvider: (()=>{traceId: string;spanId: string}|undefined)|undefined;
+
+/**
+ * Register an external propagation context provider function.
+ * When registered, trace context will be read from the external source (e.g. OpenTelemetry)
+ * instead of from the Sentry scope's propagation context.
+ */
+exportfunctionregisterExternalPropagationContext(fn: ()=>{traceId: string;spanId: string}|undefined): void{
+_externalPropagationContextProvider=fn;
+}
+
+/**
+ * Get the external propagation context, if a provider has been registered.
+ */
+exportfunctiongetExternalPropagationContext(): {traceId: string;spanId: string}|undefined{
+return_externalPropagationContextProvider?.();
+}
+
+/**
+ * Check if an external propagation context provider has been registered.
+ */
+exportfunctionhasExternalPropagationContext(): boolean{
+return_externalPropagationContextProvider!==undefined;
+}
+
 /**
  * Get the currently active scope.
  */
@@ -125,6 +150,11 @@ export function getClient<C extends Client>(): C | undefined {
  * Get a trace context for the given scope.
  */
 exportfunctiongetTraceContextFromScope(scope: Scope): TraceContext{
+constexternalContext=getExternalPropagationContext();
+if(externalContext){
+return{trace_id: externalContext.traceId,span_id: externalContext.spanId};
+}
+
 constpropagationContext=scope.getPropagationContext();
 
 const{ traceId, parentSpanId, propagationSpanId }=propagationContext;

packages/core/src/index.ts

@@ -41,6 +41,9 @@ export {
 withIsolationScope,
 getClient,
 getTraceContextFromScope,
+registerExternalPropagationContext,
+getExternalPropagationContext,
+hasExternalPropagationContext,
 }from'./currentScopes';
 export{getDefaultCurrentScope,getDefaultIsolationScope}from'./defaultScopes';
 export{setAsyncContextStrategy}from'./asyncContext';
@@ -49,7 +52,7 @@ export { makeSession, closeSession, updateSession } from './session';
 export{Scope}from'./scope';
 exporttype{CaptureContext,ScopeContext,ScopeData}from'./scope';
 export{notifyEventProcessors}from'./eventProcessors';
-export{getEnvelopeEndpointWithUrlEncodedAuth,getReportDialogEndpoint}from'./api';
+export{getEnvelopeEndpointWithUrlEncodedAuth,getReportDialogEndpoint,SENTRY_API_VERSION}from'./api';
 export{Client}from'./client';
 export{ServerRuntimeClient}from'./server-runtime-client';
 export{initAndBind,setCurrentClient}from'./sdk';

packages/core/src/utils/traceData.ts

@@ -1,7 +1,7 @@
 import{getAsyncContextStrategy}from'../asyncContext';
 import{getMainCarrier}from'../carrier';
 importtype{Client}from'../client';
-import{getClient,getCurrentScope}from'../currentScopes';
+import{getClient,getCurrentScope,hasExternalPropagationContext}from'../currentScopes';
 import{isEnabled}from'../exports';
 importtype{Scope}from'../scope';
 import{getDynamicSamplingContextFromScope,getDynamicSamplingContextFromSpan}from'../tracing';
@@ -20,6 +20,10 @@ import { generateSentryTraceHeader, generateTraceparentHeader, TRACEPARENT_REGEX
  * This function also applies some validation to the generated sentry-trace and baggage values to ensure that
  * only valid strings are returned.
  *
+ * When an external propagation context is registered (e.g. via the OTLP integration) and there is no active
+ * Sentry span, this function returns an empty object to defer outgoing request propagation to the external
+ * propagator (e.g. an OpenTelemetry propagator).
+ *
  * If (@param options.propagateTraceparent) is `true`, the function will also generate a `traceparent` value,
  * following the W3C traceparent header format.
  *
@@ -42,6 +46,13 @@ export function getTraceData(
 
 constscope=options.scope||getCurrentScope();
 constspan=options.span||getActiveSpan();
+
+// When no active span and external propagation context is registered (e.g. OTLP integration),
+// return empty to let the OTel propagator handle outgoing request propagation.
+if(!span&&hasExternalPropagationContext()){
+return{};
+}
+
 constsentryTrace=span ? spanToTraceHeader(span) : scopeToTraceHeader(scope);
 constdsc=span ? getDynamicSamplingContextFromSpan(span) : getDynamicSamplingContextFromScope(client,scope);
 constbaggage=dynamicSamplingContextToSentryBaggageHeader(dsc);

packages/core/test/lib/currentScopes.test.ts

@@ -0,0 +1,86 @@
+import{afterEach,describe,expect,it}from'vitest';
+import{
+getExternalPropagationContext,
+getTraceContextFromScope,
+hasExternalPropagationContext,
+registerExternalPropagationContext,
+}from'../../src/currentScopes';
+import{Scope}from'../../src/scope';
+
+describe('External Propagation Context',()=>{
+afterEach(()=>{
+// Reset by registering a provider that returns undefined
+registerExternalPropagationContext(()=>undefined);
+});
+
+describe('registerExternalPropagationContext',()=>{
+it('registers a provider function',()=>{
+registerExternalPropagationContext(()=>({
+traceId: 'abc123',
+spanId: 'def456',
+}));
+
+expect(hasExternalPropagationContext()).toBe(true);
+});
+});
+
+describe('getExternalPropagationContext',()=>{
+it('returns undefined when provider returns undefined',()=>{
+registerExternalPropagationContext(()=>undefined);
+expect(getExternalPropagationContext()).toBeUndefined();
+});
+
+it('returns trace context from provider',()=>{
+registerExternalPropagationContext(()=>({
+traceId: '12345678901234567890123456789012',
+spanId: '1234567890123456',
+}));
+
+constresult=getExternalPropagationContext();
+expect(result).toEqual({
+traceId: '12345678901234567890123456789012',
+spanId: '1234567890123456',
+});
+});
+});
+
+describe('hasExternalPropagationContext',()=>{
+it('returns true after registration',()=>{
+registerExternalPropagationContext(()=>undefined);
+expect(hasExternalPropagationContext()).toBe(true);
+});
+});
+
+describe('getTraceContextFromScope with external propagation context',()=>{
+it('uses external propagation context when available',()=>{
+registerExternalPropagationContext(()=>({
+traceId: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1',
+spanId: 'bbbbbbbbbbbbbb01',
+}));
+
+constscope=newScope();
+scope.setPropagationContext({
+traceId: 'cccccccccccccccccccccccccccccc01',
+sampleRand: 0.5,
+});
+
+consttraceContext=getTraceContextFromScope(scope);
+expect(traceContext.trace_id).toBe('aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1');
+expect(traceContext.span_id).toBe('bbbbbbbbbbbbbb01');
+expect(traceContext.parent_span_id).toBeUndefined();
+});
+
+it('falls back to scope propagation context when provider returns undefined',()=>{
+registerExternalPropagationContext(()=>undefined);
+
+constscope=newScope();
+scope.setPropagationContext({
+traceId: 'cccccccccccccccccccccccccccccc01',
+sampleRand: 0.5,
+});
+
+consttraceContext=getTraceContextFromScope(scope);
+expect(traceContext.trace_id).toBe('cccccccccccccccccccccccccccccc01');
+});
+});
+});

packages/core/test/lib/utils/traceData.test.ts

@@ -6,6 +6,7 @@ import {
 getIsolationScope,
 getMainCarrier,
 getTraceData,
+registerExternalPropagationContext,
 Scope,
 SentrySpan,
 setAsyncContextStrategy,
@@ -347,4 +348,47 @@ describe('getTraceData', () => {
 expect(traceData.traceparent).toBeDefined();
 expect(traceData.traceparent).toMatch(/00-12345678901234567890123456789099-[0-9a-f]{16}-00/);
 });
+
+it('returns empty object when no span and external propagation context is registered',()=>{
+setupClient();
+
+registerExternalPropagationContext(()=>({
+traceId: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1',
+spanId: 'bbbbbbbbbbbbbb01',
+}));
+
+consttraceData=getTraceData();
+expect(traceData).toEqual({});
+
+// Clean up
+registerExternalPropagationContext(()=>undefined);
+});
+
+it('still returns trace data from span even when external propagation context is registered',()=>{
+setupClient();
+
+registerExternalPropagationContext(()=>({
+traceId: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1',
+spanId: 'bbbbbbbbbbbbbb01',
+}));
+
+constspan=newSentrySpan({
+traceId: '12345678901234567890123456789012',
+spanId: '1234567890123456',
+sampled: true,
+});
+
+withActiveSpan(span,()=>{
+constdata=getTraceData();
+
+expect(data).toEqual({
+'sentry-trace': '12345678901234567890123456789012-1234567890123456-1',
+baggage:
+'sentry-environment=production,sentry-public_key=123,sentry-trace_id=12345678901234567890123456789012,sentry-sampled=true',
+});
+});
+
+// Clean up
+registerExternalPropagationContext(()=>undefined);
+});
 });