instana · aryamohanan · Mar 26, 2026 · Mar 27, 2026 · Mar 27, 2026 · Mar 27, 2026
@@ -36,7 +36,7 @@ const latestRuntime = semver.gte(process.version, '24.0.0');
 
 const logger = serverlessLogger.init();
 coreConfig.init(logger);
-let config = coreConfig.normalize({}, lambdaConfigDefaults);
+let config = coreConfig.normalize({ defaultsOverride: lambdaConfigDefaults });
 let coldStart = true;
 
 // Initialize instrumentations early to allow for require statements after our
@@ -286,7 +286,7 @@ function init(event, arnInfo, _config) {
   //         - late env variables (less likely)
   //         - custom logger
   //         - we always renormalize unconditionally to ensure safety.
-  config = coreConfig.normalize(userConfig, lambdaConfigDefaults);
+  config = coreConfig.normalize({ userConfig, defaultsOverride: lambdaConfigDefaults });
 
   if (!config.tracing.enabled) {
     return false;

@@ -12,7 +12,7 @@ try {
   // Worker threads are not available, so we know that this is the main thread.
 }
 
-const { tracing } = require('@instana/core');
+const { tracing, coreConfig, util } = require('@instana/core');
 const agentConnection = require('../agentConnection');
 const agentOpts = require('../agent/opts');
 const initializedTooLate = require('../util/initializedTooLate');
@@ -130,7 +130,11 @@ function enter(_ctx) {
     }
   }
 
-  tracing.activate(agentOpts.config);
+  const updatedConfig = coreConfig.update({
+    externalConfig: agentOpts.config,
+    source: util.constants.CONFIG_SOURCES.AGENT
+  });
+  tracing.activate(updatedConfig);
 
   if (agentOpts.autoProfile && autoprofile) {
     profiler = autoprofile.start();

@@ -305,7 +305,7 @@ function applyDisableConfiguration(agentResponse) {
   ensureNestedObjectExists(agentOpts.config, ['tracing', 'disable']);
   agentOpts.config.tracing.disable = configNormalizers.disable.normalizeExternalConfig({
     tracing: { disable: disablingConfig }
-  });
+  }).value;
 }
 module.exports = {
   init,

@@ -103,7 +103,7 @@ const instanaSharedMetrics = require('@instana/shared-metrics');
 require('./tracing'); // load additional instrumentations
 
 const log = require('./logger');
-const normalizeCollectorConfig = require('./util/normalizeConfig');
+const normalizeConfig = require('./util/normalizeConfig');
 const experimental = require('./experimental');
 
 // NOTE: Default collector logger && config for cases like `preinit`.
@@ -158,8 +158,11 @@ function init(userConfig = {}) {
     log.init(userConfig);
   }
 
-  config = normalizeCollectorConfig(userConfig);
-  config = instanaNodeJsCore.coreConfig.normalize(config);
+  const finalCollectorConfig = normalizeConfig(userConfig);
+  config = instanaNodeJsCore.coreConfig.normalize({
+    userConfig,
+    finalConfigBase: finalCollectorConfig
+  });
 
   agentConnection = require('./agentConnection');
   const agentOpts = require('./agent/opts');

@@ -29,7 +29,7 @@ export interface CollectorConfig {
     stackTraceLength?: number;
     [key: string]: any;
   };
-  autoProfile?: boolean | string;
+  autoProfile?: boolean;
   reportUnhandledPromiseRejections?: boolean;
   logger?: GenericLogger;
   level?: string | number;

@@ -3,10 +3,11 @@
  * (c) Copyright Instana Inc. and contributors 2019
  */
 
-/* eslint-disable dot-notation */
-
 'use strict';
 
+const util = require('@instana/core/src/config/util');
+const validate = require('@instana/core/src/config/validator');
+
 const defaults = {
   agentHost: '127.0.0.1',
   agentPort: 42699,
@@ -17,43 +18,110 @@ const defaults = {
 
 /**
  * Merges the config that was passed to the init function with environment variables and default values.
- * @param {import('../types/collector').CollectorConfig} config
+ * @param {import('../types/collector').CollectorConfig} userConfig
  * @returns {import('../types/collector').CollectorConfig}
  */
-module.exports = function normalizeConfig(config = {}) {
-  config.agentHost = config.agentHost || process.env.INSTANA_AGENT_HOST || defaults.agentHost;
-  config.agentPort = config.agentPort || parseToPositiveInteger(process.env.INSTANA_AGENT_PORT, defaults.agentPort);
-  config.agentRequestTimeout =
-    config.agentRequestTimeout ||
-    parseToPositiveInteger(process.env.INSTANA_AGENT_REQUEST_TIMEOUT, defaults.agentRequestTimeout);
-
-  config.autoProfile = config.autoProfile || process.env.INSTANA_AUTO_PROFILE || defaults.autoProfile;
-  config.tracing = config.tracing || {};
-
-  if (config.reportUnhandledPromiseRejections == null) {
-    config.reportUnhandledPromiseRejections = false;
-  }
+module.exports = function normalizeConfig(userConfig = {}) {
+  const finalConfig = {};
 
-  if (config.disableCollectorInitEvent == null) {
+  // NOTE: This function only normalizes collector-specific configuration fields.
+  // Other userConfig fields (like serviceName, tracing, etc.) are passed through as-is
+  // and will be normalized later by core/config when this collector config is passed
+  // as extraFinalConfig to core's normalize function.
+  finalConfig.agentHost = normalizeAgentHost(userConfig, defaults);
+  finalConfig.agentPort = normalizeAgentPort(userConfig, defaults);
+  finalConfig.agentRequestTimeout = normalizeAgentRequestTimeout(userConfig, defaults);
+  finalConfig.autoProfile = normalizeAutoProfile(userConfig, defaults);
+  finalConfig.reportUnhandledPromiseRejections = normalizeUnhandledRejections(userConfig);
+  finalConfig.tracing = userConfig.tracing || {};
+
+  if (finalConfig.disableCollectorInitEvent == null) {
     const envValue = process.env.INSTANA_DISABLE_COLLECTOR_INIT_EVENT;
-    config.disableCollectorInitEvent = envValue === 'true' ? true : defaults.disableCollectorInitEvent;
+    finalConfig.disableCollectorInitEvent = envValue === 'true' ? true : defaults.disableCollectorInitEvent;
   }
 
-  return config;
+  return finalConfig;
 };
 
 /**
- * @param {string | number} value
- * @param {number} defaultValue
+ * @param {import('../types/collector').CollectorConfig} userConfig
+ * @param {{ agentHost: string }} defaultConfig
+ * @returns {string}
+ */
+function normalizeAgentHost(userConfig, defaultConfig) {
+  const { value } = util.resolve(
+    {
+      envValue: 'INSTANA_AGENT_HOST',
+      inCodeValue: userConfig.agentHost,
+      defaultValue: defaultConfig.agentHost
+    },
+    [validate.stringValidator]
+  );
+  return value;
+}
+
+/**
+ * @param {import('../types/collector').CollectorConfig} userConfig
+ * @param {{ agentPort: number }} defaultConfig
  * @returns {number}
  */
-function parseToPositiveInteger(value, defaultValue) {
-  if (typeof value !== 'string') {
-    return defaultValue;
-  }
-  value = parseInt(value, 10);
-  if (!isNaN(value)) {
-    return Math.abs(Math.round(value));
-  }
-  return defaultValue;
+function normalizeAgentPort(userConfig, defaultConfig) {
+  const { value } = util.resolve(
+    {
+      envValue: 'INSTANA_AGENT_PORT',
+      inCodeValue: userConfig.agentPort,
+      defaultValue: defaultConfig.agentPort
+    },
+    [validate.numberValidator]
+  );
+  return value;
+}
+
+/**
+ * @param {import('../types/collector').CollectorConfig} userConfig
+ * @param {{ agentRequestTimeout: number }} defaultConfig
+ * @returns {number}
+ */
+function normalizeAgentRequestTimeout(userConfig, defaultConfig) {
+  const { value } = util.resolve(
+    {
+      envValue: 'INSTANA_AGENT_REQUEST_TIMEOUT',
+      inCodeValue: userConfig.agentRequestTimeout,
+      defaultValue: defaultConfig.agentRequestTimeout
+    },
+    [validate.numberValidator]
+  );
+  return value;
+}
+
+/**
+ * @param {import('../types/collector').CollectorConfig} userConfig
+ * @param {{ autoProfile: boolean }} defaultConfig
+ * @returns {boolean}
+ */
+function normalizeAutoProfile(userConfig, defaultConfig) {
+  const { value } = util.resolve(
+    {
+      envValue: 'INSTANA_AUTO_PROFILE',
+      inCodeValue: userConfig.autoProfile,
+      defaultValue: defaultConfig.autoProfile
+    },
+    [validate.booleanValidator]
+  );
+  return value;
+}
+
+/**
+ * @param {import('../types/collector').CollectorConfig} userConfig
+ * @returns {boolean}
+ */
+function normalizeUnhandledRejections(userConfig) {
+  const { value } = util.resolve(
+    {
+      inCodeValue: userConfig.reportUnhandledPromiseRejections,
+      defaultValue: false
+    },
+    [validate.booleanValidator]
+  );
+  return value;
 }
@@ -21,6 +21,7 @@ const {
 } = require('@_local/core/test/test_util');
 const ProcessControls = require('@_local/collector/test/test_util/ProcessControls');
 const globalAgent = require('@_local/collector/test/globalAgent');
+const { AgentStubControls } = require('@_local/collector/test/apps/agentStubControls');
 
 // v3 is considered the legacy version.
 // - It does not support Redis clustering.
@@ -938,9 +939,69 @@ module.exports = function (name, version, isLatest, mode) {
     }
   });
 
+  describe('Config precedence', () => {
+    describe('when both agent config and env var are set, env var takes precedence', () => {
+      const customAgentControls = new AgentStubControls();
+      let controls;
+
+      before(async () => {
+        await customAgentControls.startAgent({
+          ignoreEndpoints: { redis: ['get', 'set'] }
+        });
+
+        controls = new ProcessControls({
+          agentControls: customAgentControls,
+          dirname: __dirname,
+          appName: isLegacyVersion ? 'legacyApp' : 'app',
+          env: {
+            LIBRARY_LATEST: isLatest,
+            LIBRARY_VERSION: version,
+            LIBRARY_NAME: name,
+            REDIS_SETUP_TYPE: mode,
+            INSTANA_IGNORE_ENDPOINTS: 'redis:get;'
+          }
+        });
+        await controls.startAndWaitForAgentConnection(5000, Date.now() + 1000 * 60 * 5);
+      });
+
+      beforeEach(async () => {
+        await customAgentControls.clearReceivedTraceData();
+      });
+
+      after(async () => {
+        await customAgentControls.stopAgent();
+        await controls.stop();
+      });
+
+      it('should use env var config and ignore only get (not set)', async () => {
+        await controls
+          .sendRequest({
+            method: 'POST',
+            path: '/values',
+            qs: {
+              key: 'discount',
+              value: 50
+            }
+          })
+          .then(async () => {
+            return retry(async () => {
+              const spans = await customAgentControls.getSpans();
+              // 1 x http entry span
+              // 1 x http client span
+              // 1 x redis set span (set is NOT ignored because env var only ignores 'get')
+              expect(spans.length).to.equal(3);
+
+              const redisSpans = spans.filter(span => span.n === 'redis');
+              expect(redisSpans.length).to.equal(1);
+              expect(redisSpans[0].data.redis.command).to.equal('set');
+            });
+          });
+      });
+    });
+  });
+
   mochaSuiteFn('ignore-endpoints:', function () {
     describe('when ignore-endpoints is enabled via agent configuration', () => {
-      const { AgentStubControls } = require('@_local/collector/test/apps/agentStubControls');
       const customAgentControls = new AgentStubControls();
       let controls;
 

@@ -379,6 +379,57 @@ module.exports = function (name, version, isLatest) {
           });
         });
       });
+
+      describe('precedence: when both agent and env are configured, env takes precedence', () => {
+        let customAgentControls;
+        let precedenceControls;
+
+        before(async () => {
+          customAgentControls = new AgentStubControls();
+          await customAgentControls.startAgent({
+            disable: { console: false }
+          });
+
+          precedenceControls = new ProcessControls({
+            agentControls: customAgentControls,
+            dirname: __dirname,
+            env: {
+              INSTANA_TRACING_DISABLE_INSTRUMENTATIONS: ['console'],
+              LIBRARY_LATEST: isLatest,
+              LIBRARY_VERSION: version,
+              LIBRARY_NAME: name
+            }
+          });
+          await precedenceControls.startAndWaitForAgentConnection();
+        });
+
+        after(async () => {
+          await precedenceControls.stop();
+          await customAgentControls.stopAgent();
+        });
+
+        it('should not trace console.warn calls (env var takes precedence over agent config)', async () => {
+          await precedenceControls.sendRequest({ path: '/warn' });
+
+          await testUtils.retry(async () => {
+            const spans = await customAgentControls.getSpans();
+            const httpEntrySpan = verifyHttpRootEntry({
+              spans,
+              apiPath: '/warn',
+              pid: String(precedenceControls.getPid())
+            });
+
+            verifyHttpExit({
+              spans,
+              parent: httpEntrySpan,
+              pid: String(precedenceControls.getPid())
+            });
+
+            const consoleLogSpans = testUtils.getSpansByName(spans, 'log.console');
+            expect(consoleLogSpans).to.be.empty;
+          });
+        });
+      });
     });
   });