feat(opentelemetry): Add SentryTracerProvider

packages/core/src/shared-exports.ts

@@ -103,6 +103,7 @@ export {
   spanToJSON,
   spanToStreamedSpanJSON,
   spanIsSampled,
+  spanIsSentrySpan,
   spanToTraceContext,
   getSpanDescendants,
   getStatusMessage,

packages/core/src/tracing/index.ts

@@ -4,6 +4,10 @@ export {
   getCapturedScopesOnSpan,
   markSpanForOtelSourceInference,
   spanShouldInferOtelSource,
+  markSpanSourceAsExplicit,
+  spanSourceWasExplicitlySet,
+  markSpanAsTracerProviderSpan,
+  spanIsTracerProviderSpan,
 } from './utils';
 export { startIdleSpan, TRACING_DEFAULTS } from './idleSpan';
 export { SentrySpan } from './sentrySpan';
@@ -13,12 +17,14 @@ export { SPAN_STATUS_ERROR, SPAN_STATUS_OK, SPAN_STATUS_UNSET } from './spanstat
 export {
   startSpan,
   startInactiveSpan,
+  _INTERNAL_startInactiveSpan,
   startSpanManual,
   continueTrace,
   withActiveSpan,
   suppressTracing,
   isTracingSuppressed,
   startNewTrace,
+  spanIsIgnored,
   SUPPRESS_TRACING_KEY,
 } from './trace';
 export { bindScopeToEmitter } from './bindScopeToEmitter';

packages/core/src/tracing/sentrySpan.ts

@@ -47,7 +47,7 @@ import { getDynamicSamplingContextFromSpan } from './dynamicSamplingContext';
 import { logSpanEnd } from './logSpans';
 import { timedEventsToMeasurements } from './measurement';
 import { hasSpanStreamingEnabled } from './spans/hasSpanStreamingEnabled';
-import { getCapturedScopesOnSpan, spanShouldInferOtelSource } from './utils';
+import { getCapturedScopesOnSpan, markSpanSourceAsExplicit, spanShouldInferOtelSource } from './utils';
 
 const MAX_SPAN_COUNT = 1000;
 
@@ -144,7 +144,7 @@ export class SentrySpan implements Span {
    * @hidden
    * @internal
    */
-  public recordException(_exception: unknown, _time?: number | undefined): void {
+  public recordException(_exception: unknown, _time?: SpanTimeInput | undefined): void {
     // noop
   }
 
@@ -167,6 +167,12 @@ export class SentrySpan implements Span {
       this._attributes[key] = value;
     }
 
+    // Setting the source on a span branded for OTel-style inference means user code is choosing it
+    // explicitly, so flag it to keep `applyOtelSpanData` from overriding it with an inferred source.
+    if (key === SEMANTIC_ATTRIBUTE_SENTRY_SOURCE && value !== undefined && spanShouldInferOtelSource(this)) {
+      markSpanSourceAsExplicit(this);
+    }
+
     return this;
   }
 

packages/core/src/tracing/trace.ts

@@ -82,7 +82,7 @@ export function startSpan<T>(options: StartSpanOptions, callback: (span: Span) =
       // Ignored root spans still need to be set on scope so that `getActiveSpan()` returns them
       // and descendants are also non-recording. Ignored child spans don't need this because
       // the parent span is already on scope.
-      if (!_isIgnoredSpan(activeSpan) || !parentSpan) {
+      if (!spanIsIgnored(activeSpan) || !parentSpan) {
         _setSpanForScope(scope, activeSpan);
       }
 
@@ -144,7 +144,7 @@ export function startSpanManual<T>(options: StartSpanOptions, callback: (span: S
 
       // We don't set ignored child spans onto the scope because there likely is an active,
       // unignored span on the scope already.
-      if (!_isIgnoredSpan(activeSpan) || !parentSpan) {
+      if (!spanIsIgnored(activeSpan) || !parentSpan) {
         _setSpanForScope(scope, activeSpan);
       }
 
@@ -181,6 +181,20 @@ export function startInactiveSpan(options: StartSpanOptions): Span {
     return acs.startInactiveSpan(options);
   }
 
+  return _startInactiveSpanImpl(options);
+}
+
+/**
+ * Internal version of startInactiveSpan that bypasses the ACS check.
+ * Used by SentryTracerProvider to create spans without triggering recursion
+ * through ACS overrides.
+ * @hidden
+ */
+export function _INTERNAL_startInactiveSpan(options: StartSpanOptions): Span {
+  return _startInactiveSpanImpl(options);
+}
+
+function _startInactiveSpanImpl(options: StartSpanOptions): Span {
   const spanArguments = parseSentrySpanArguments(options);
   const { forceTransaction, parentSpan: customParentSpan } = options;
 
@@ -651,6 +665,11 @@ function _shouldIgnoreStreamedSpan(client: Client | undefined, spanArguments: Se
   );
 }
 
-function _isIgnoredSpan(span: Span): span is SentryNonRecordingSpan {
+/**
+ * Whether a span is an ignored (`ignoreSpans`) placeholder. Such a span must not be set as the active
+ * span when it has a parent, so its children attach to that parent and get re-parented rather than
+ * dropped with it. Shared with the OTel-based provider so both span pipelines apply the same rule.
+ */
+export function spanIsIgnored(span: Span): span is SentryNonRecordingSpan {
   return spanIsNonRecordingSpan(span) && span.dropReason === 'ignored';
 }

packages/core/src/tracing/utils.ts

@@ -12,13 +12,30 @@ const ISOLATION_SCOPE_ON_START_SPAN_FIELD = '_sentryIsolationScope';
 // so the key is shared across duplicated copies of `@sentry/core`.
 const OTEL_SOURCE_INFERENCE_SPAN_FIELD = Symbol.for('sentry.otelSourceInference');
 
+// Brand marking a span (otherwise subject to OTel-style source inference, see above) whose
+// `sentry.source` was explicitly set by user code after creation, so `applyOtelSpanData` stops
+// inferring and respects the chosen source and name. This is what tells a user-set `custom` source
+// apart from the default `custom` that `_startRootSpan` stamps on every root span.
+const OTEL_SOURCE_EXPLICITLY_SET_SPAN_FIELD = Symbol.for('sentry.otelSourceExplicitlySet');
+
+// Brand marking a span created by the `SentryTracerProvider` (i.e. via the OTel tracer) rather than
+// directly through the core span API. Such a span is handed to OTel instrumentations as an OTel span,
+// so it must become immutable after `end()` like a real OTel SDK span (see `SentrySpan.end()`). Spans
+// created directly through core (e.g. the browser SDK) are not branded and stay mutable.
+const TRACER_PROVIDER_SPAN_FIELD = Symbol.for('sentry.tracerProviderSpan');
+
 type SpanWithScopes = Span & {
   [SCOPE_ON_START_SPAN_FIELD]?: Scope;
   [ISOLATION_SCOPE_ON_START_SPAN_FIELD]?: MaybeWeakRef<Scope>;
 };
 
 type SpanWithOtelSourceInference = Span & {
   [OTEL_SOURCE_INFERENCE_SPAN_FIELD]?: boolean;
+  [OTEL_SOURCE_EXPLICITLY_SET_SPAN_FIELD]?: boolean;
+};
+
+type SpanWithTracerProviderBrand = Span & {
+  [TRACER_PROVIDER_SPAN_FIELD]?: boolean;
 };
 
 /** Store the scope & isolation scope for a span, which can the be used when it is finished. */
@@ -57,3 +74,32 @@ export function markSpanForOtelSourceInference(span: Span): void {
 export function spanShouldInferOtelSource(span: Span): boolean {
   return (span as SpanWithOtelSourceInference)[OTEL_SOURCE_INFERENCE_SPAN_FIELD] === true;
 }
+
+/**
+ * Mark that user code explicitly set `sentry.source` on a span subject to OTel-style inference, so
+ * `applyOtelSpanData` keeps that source (and name) instead of overriding it. Set by `SentrySpan`
+ * when `setAttribute` writes the source on an already-branded span (the default `custom` source is
+ * stamped at construction, before the brand, so it doesn't trip this).
+ */
+export function markSpanSourceAsExplicit(span: Span): void {
+  addNonEnumerableProperty(span, OTEL_SOURCE_EXPLICITLY_SET_SPAN_FIELD, true);
+}
+
+/** Whether user code explicitly set `sentry.source` on a span (see {@link markSpanSourceAsExplicit}). */
+export function spanSourceWasExplicitlySet(span: Span): boolean {
+  return (span as SpanWithOtelSourceInference)[OTEL_SOURCE_EXPLICITLY_SET_SPAN_FIELD] === true;
+}
+
+/**
+ * Mark a span as created by the `SentryTracerProvider` (via the OTel tracer). Set by `SentryTracer`
+ * on every span it creates; read by `SentrySpan.end()` to seal the span against further writes once
+ * it has ended, mirroring OTel SDK spans (which are immutable after `end()`).
+ */
+export function markSpanAsTracerProviderSpan(span: Span): void {
+  addNonEnumerableProperty(span, TRACER_PROVIDER_SPAN_FIELD, true);
+}
+
+/** Whether a span was created by the `SentryTracerProvider` (see {@link markSpanAsTracerProviderSpan}). */
+export function spanIsTracerProviderSpan(span: Span): boolean {
+  return (span as SpanWithTracerProviderBrand)[TRACER_PROVIDER_SPAN_FIELD] === true;
+}

packages/core/src/types/span.ts

@@ -319,5 +319,5 @@ export interface Span {
   /**
    * NOT USED IN SENTRY, only added for compliance with OTEL Span interface
    */
-  recordException(exception: unknown, time?: number): void;
+  recordException(exception: unknown, time?: SpanTimeInput): void;
 }

packages/core/src/utils/spanUtils.ts

@@ -299,7 +299,7 @@ export interface OpenTelemetrySdkTraceBaseSpan extends Span {
  * Sadly, due to circular dependency checks we cannot actually import the Span class here and check for instanceof.
  * :( So instead we approximate this by checking if it has the `getSpanJSON` method.
  */
-function spanIsSentrySpan(span: Span): span is SentrySpan {
+export function spanIsSentrySpan(span: Span): span is SentrySpan {
   return typeof (span as SentrySpan).getSpanJSON === 'function';
 }
 

packages/core/test/lib/tracing/sentrySpan.test.ts

@@ -4,7 +4,7 @@ import { setCurrentClient } from '../../../src/sdk';
 import { SEMANTIC_ATTRIBUTE_SENTRY_SOURCE } from '../../../src/semanticAttributes';
 import { SentrySpan } from '../../../src/tracing/sentrySpan';
 import { SPAN_STATUS_ERROR } from '../../../src/tracing/spanstatus';
-import { markSpanForOtelSourceInference } from '../../../src/tracing/utils';
+import { markSpanForOtelSourceInference, spanSourceWasExplicitlySet } from '../../../src/tracing/utils';
 import type { SpanJSON } from '../../../src/types/span';
 import { spanToJSON, TRACE_FLAG_NONE, TRACE_FLAG_SAMPLED } from '../../../src/utils/spanUtils';
 import { timestampInSeconds } from '../../../src/utils/time';
@@ -61,6 +61,36 @@ describe('SentrySpan', () => {
     });
   });
 
+  describe('explicit source', () => {
+    it('flags a source set on a span marked for OTel source inference as explicit', () => {
+      const span = new SentrySpan({ name: 'original name' });
+      markSpanForOtelSourceInference(span);
+      expect(spanSourceWasExplicitlySet(span)).toBe(false);
+
+      span.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'custom');
+
+      expect(spanSourceWasExplicitlySet(span)).toBe(true);
+    });
+
+    it('does not flag the default source set at construction (before the inference brand) as explicit', () => {
+      const span = new SentrySpan({
+        name: 'original name',
+        attributes: { [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'custom' },
+      });
+      markSpanForOtelSourceInference(span);
+
+      expect(spanSourceWasExplicitlySet(span)).toBe(false);
+    });
+
+    it('does not flag a source set on a span that is not marked for OTel source inference', () => {
+      const span = new SentrySpan({ name: 'original name' });
+
+      span.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'custom');
+
+      expect(spanSourceWasExplicitlySet(span)).toBe(false);
+    });
+  });
+
   describe('setters', () => {
     test('setName', () => {
       const span = new SentrySpan({});

packages/opentelemetry/README.md

@@ -85,6 +85,36 @@ function setupSentry() {
 A full setup example can be found in
 [node-experimental](https://github.com/getsentry/sentry-javascript/blob/develop/packages/node-experimental).
 
+## Experimental Sentry Tracer Provider
+
+`SentryTracerProvider` is an experimental minimal OpenTelemetry tracer provider which creates native Sentry spans directly.
+It is useful when code uses the global OpenTelemetry API and you do not need the full OpenTelemetry SDK span processor
+and exporter pipeline.
+
+```js
+import { trace } from '@opentelemetry/api';
+import { SentryTracerProvider } from '@sentry/opentelemetry';
+
+trace.setGlobalTracerProvider(new SentryTracerProvider());
+
+const span = trace.getTracer('example').startSpan('work');
+span.end();
+```
+
+In `@sentry/node`, this provider can be enabled with the experimental option:
+
+```js
+Sentry.init({
+  dsn: 'xxx',
+  _experiments: {
+    useSentryTracerProvider: true,
+  },
+});
+```
+
+When this provider is enabled, additional OpenTelemetry span processors are ignored because Sentry spans are created
+directly. OpenTelemetry logs and metrics are not handled by this provider.
+
 ## Links
 
 - [Official SDK Docs](https://docs.sentry.io/quickstart/)