fix(electron): gate the Electron plugin behind an experimental flag (#9264)

* refactor(electron)!: gate the Electron plugin behind an experimental flag disabled in v7

The Electron integration (plugin + instrumentation) has moved to the
standalone Electron SDK (see DataDog/electron-sdk#152). dd-trace keeps
the plugin and instrumentation in place for backward compatibility, but
gates it behind the existing experimental opt-in mechanism so it is
disabled by default starting in v7, while remaining enabled by default
on earlier majors.

- ElectronPlugin.experimental is now DD_MAJOR >= 7, following the same
  opt-in pattern already used by other experimental plugins (e.g. nats).
- major-overrides.js flips the documented DD_TRACE_ELECTRON_ENABLED
  default to false for majorVersion >= 7, evaluated at runtime against
  the branch's own DD_MAJOR so it stays accurate after backports.
- tracer.js now prefers the Electron exporter over OTLP when both
  OTEL_TRACES_EXPORTER=otlp and experimental.exporter=electron are set,
  so Electron SDK spans keep reaching the IPC bridge instead of being
  silently routed to an OTLP endpoint.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(electron): skip the implicit OTel sampler default for the Electron exporter

config/index.js forced OTel's parentbased_always_on sampler default
(sampleRate=1) whenever OTEL_TRACES_EXPORTER=otlp, without the same
Electron carve-out already present in opentracing/tracer.js's exporter
selection. Electron SDK users with OTEL_* vars set for an unrelated
telemetry pipeline could have dd-trace's sampling policy silently
overridden even though their trace exporter correctly stayed on the
Electron IPC bridge. An explicit OTEL_TRACES_SAMPLER still applies.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: 2 people

packages/datadog-plugin-electron/src/index.js

@@ -1,11 +1,13 @@
 'use strict'
 
+const { DD_MAJOR } = require('../../../version')
 const CompositePlugin = require('../../dd-trace/src/plugins/composite')
 const ElectronIpcPlugin = require('./ipc')
 const ElectronNetPlugin = require('./net')
 
 class ElectronPlugin extends CompositePlugin {
   static id = 'electron'
+  static experimental = DD_MAJOR >= 7
   static get plugins () {
     return {
       net: ElectronNetPlugin,

packages/dd-trace/src/config/index.js

@@ -478,9 +478,13 @@ class Config extends ConfigBase {
 
     // Apply the OTel sampler when the user opted into OTel traces or explicitly set the sampler.
     // OTEL_TRACES_SAMPLER has `default: parentbased_always_on` (per OTel spec), so opt-in users
-    // that don't set the sampler still get parent-based sampling.
+    // that don't set the sampler still get parent-based sampling. Electron exporter spans go over
+    // the Electron SDK's IPC bridge rather than OTLP (see opentracing/tracer.js), so an
+    // OTEL_TRACES_EXPORTER=otlp set for an unrelated telemetry pipeline shouldn't also override
+    // dd-trace's own sampling policy in that case.
     if (!trackedConfigOrigins.has('sampleRate') &&
-        (trackedConfigOrigins.has('OTEL_TRACES_SAMPLER') || this.OTEL_TRACES_EXPORTER === 'otlp')) {
+        (trackedConfigOrigins.has('OTEL_TRACES_SAMPLER') ||
+          (this.OTEL_TRACES_EXPORTER === 'otlp' && this.experimental.exporter !== 'electron'))) {
       setAndTrack(this, 'sampleRate',
         getFromOtelSamplerMap(this.OTEL_TRACES_SAMPLER, this.OTEL_TRACES_SAMPLER_ARG))
     }

packages/dd-trace/src/config/major-overrides.js

@@ -58,6 +58,13 @@ function applyMajorOverrides (supportedConfigurations, majorVersion) {
   delete supportedConfigurations.DD_TRACE_EXPERIMENTAL_RUNTIME_ID_ENABLED
   // eslint-disable-next-line eslint-rules/eslint-env-aliases
   dropAlias(supportedConfigurations.DD_RUNTIME_METRICS_RUNTIME_ID_ENABLED, 'DD_TRACE_EXPERIMENTAL_RUNTIME_ID_ENABLED')
+
+  if (majorVersion >= 7) {
+    // The Electron plugin moved to the Electron SDK and is opt-in (disabled by default) from v7 on,
+    // while remaining enabled by default on earlier majors (see ElectronPlugin.experimental).
+    const electronEntry = supportedConfigurations.DD_TRACE_ELECTRON_ENABLED?.[0]
+    if (electronEntry) electronEntry.default = 'false'
+  }
 }
 
 /**

packages/dd-trace/src/opentracing/tracer.js

@@ -36,8 +36,11 @@ class DatadogTracer {
     // (test_session/test_module/ test_suite/test) belong on the citestcycle
     // endpoint, not on an OTLP traces endpoint — otherwise users with OTEL_*
     // vars set in their environment (e.g. for a separate telemetry integration)
-    // silently lose all test spans.
-    if (config.OTEL_TRACES_EXPORTER === 'otlp' && !config.isCiVisibility) {
+    // silently lose all test spans. The same applies to the Electron exporter:
+    // spans must reach the Electron SDK's IPC bridge, not an OTLP endpoint,
+    // even when OTEL_* vars are set for unrelated telemetry.
+    if (config.OTEL_TRACES_EXPORTER === 'otlp' && !config.isCiVisibility &&
+      config.experimental.exporter !== 'electron') {
       const { createOtlpTraceExporter } = require('../opentelemetry/trace')
       this._exporter = createOtlpTraceExporter(config)
     } else {

packages/dd-trace/test/config/index.spec.js

@@ -766,6 +766,19 @@ describe('Config', () => {
     assert.strictEqual(config.sampleRate, undefined)
   })
 
+  it('should not default OTEL_TRACES_SAMPLER when OTEL_TRACES_EXPORTER is otlp but the exporter is electron', () => {
+    process.env.OTEL_TRACES_EXPORTER = 'otlp'
+    const config = getConfig({ experimental: { exporter: 'electron' } })
+    assert.strictEqual(config.sampleRate, undefined)
+  })
+
+  it('should still respect an explicit OTEL_TRACES_SAMPLER when the exporter is electron', () => {
+    process.env.OTEL_TRACES_EXPORTER = 'otlp'
+    process.env.OTEL_TRACES_SAMPLER = 'always_off'
+    const config = getConfig({ experimental: { exporter: 'electron' } })
+    assert.strictEqual(config.sampleRate, 0)
+  })
+
   it('should keep OTEL_TRACES_EXPORTER=otlp', () => {
     process.env.OTEL_TRACES_EXPORTER = 'otlp'
     const config = getConfig()

packages/dd-trace/test/exporter.spec.js

@@ -9,6 +9,7 @@ const sinon = require('sinon')
 require('./setup/core')
 const AgentExporter = require('../src/exporters/agent')
 const LogExporter = require('../src/exporters/log')
+const ElectronExporter = require('../src/exporters/electron')
 const { DATADOG_MINI_AGENT_PATH } = require('../src/constants')
 
 describe('exporter', () => {
@@ -64,4 +65,10 @@ describe('exporter', () => {
 
     assert.strictEqual(Exporter, LogExporter)
   })
+
+  it('should create an ElectronExporter when configured', () => {
+    const Exporter = require('../src/exporter')('electron')
+
+    assert.strictEqual(Exporter, ElectronExporter)
+  })
 })

packages/dd-trace/test/opentelemetry/traces.spec.js

@@ -748,6 +748,16 @@ describe('OpenTelemetry Traces', () => {
       assert(!(tracer._exporter instanceof OtlpHttpTraceExporter),
         'Exporter should not be the OTLP exporter when OTEL_TRACES_EXPORTER is not otlp')
     })
+
+    it('DatadogTracer prefers the Electron exporter over OTLP when OTEL_TRACES_EXPORTER=otlp', () => {
+      process.env.OTEL_TRACES_EXPORTER = 'otlp'
+      const DatadogTracer = proxyquire.noPreserveCache()('../../src/opentracing/tracer', {})
+      const ElectronExporter = require('../../src/exporters/electron')
+      const config = getConfigFresh({ experimental: { exporter: 'electron' } })
+      const tracer = new DatadogTracer(config)
+      assert(tracer._exporter instanceof ElectronExporter,
+        'Exporter should be the Electron exporter even when OTEL_TRACES_EXPORTER=otlp')
+    })
   })
 
   describe('Configurations', () => {