feat: unified stack trace configuration from agent, in-code and env vars #2235

abhilash-sivan · 2025-12-16T10:04:19Z

refs https://jsw.ibm.com/browse/INSTA-63750

Current PR

Accept stack trace configuration (tracing.global.stack-trace-length and stack-trace) from the agent.
Support in-code configuration via tracing.global.stackTraceLength and stackTrace, while keeping tracing.stackTraceLength for backward compatibility.
Configuration precedence (highest to lowest):
agent → tracing.global.stackTraceLength → tracing.stackTraceLength → env var → default
Introduce a maximum limit of 500 for stackTraceLength; the default remains 10.
Apply agent configuration when present.
Enforce the configured stackTraceLength limit in setErrorDetails to demonstrate that the limit is applied.

Next PR

~~Extend the stackTraceLength limit to the getStackTrace function and add the required tests.~~ done in this pr
Apply the stackTrace mode and add corresponding tests.

packages/core/test/config/normalizeConfig_test.js

packages/core/src/config/index.js

packages/collector/src/announceCycle/unannounced.js

packages/collector/src/util/normalizeConfig.js

packages/core/src/util/constants.js

packages/core/test/config/normalizeConfig_test.js

packages/collector/src/util/normalizeConfig.js

packages/core/src/tracing/tracingUtil.js

packages/core/test/config/normalizeConfig_test.js

packages/core/test/tracing/tracingUtil_test.js

packages/collector/test/tracing/protocols/http/proxy/expressProxyControls.js

packages/collector/test/tracing/misc/stack_trace/test.js

packages/core/src/tracing/tracingUtil.js

packages/core/src/config/index.js

Co-authored-by: kirrg001 <katharina.irrgang@ibm.com>

kirrg001 · 2025-12-22T09:29:50Z

packages/core/src/config/configNormalizers/stackTrace.js

+    } else {
+      logger?.warn(
+        `The value of config.tracing.stackTrace has the non-supported type ${typeof config.tracing.stackTrace}. ` +
+          `Valid values are: ${validStackTraceModes.join(', ')}. Using default: all`


This is also validation.

kirrg001

Pre-approving

…ength

packages/core/src/config/configNormalizers/stackTrace.js

packages/collector/src/announceCycle/unannounced.js

kirrg001 · 2025-12-29T10:45:23Z

packages/core/src/config/configNormalizers/stackTrace.js

+  const envVar = 'INSTANA_STACK_TRACE';
+
+  if (isAgentConfig) {
+    const configPath = 'stack-trace value from agent';


What is that?

configPath is used only for logging purposes.
isAgentConfig is used to identify the source of the configuration, as we apply different rules for agent and non-agent sources.

If the configuration comes from the agent, it takes precedence, and we do not evaluate any other sources.

If the configuration comes from in-code settings, it eventually resolves to the default value if config is not provided.

The isAgentConfig flag helps determine whether we should exit early or continue processing.

This is part of an optimisation effort. Previously, similar logic existed separately for agent and non-agent normalisation, which has now been merged.

kirrg001 · 2025-12-29T10:46:28Z

packages/core/src/config/configNormalizers/stackTrace.js

+  }
+
+  const validatedConfigGlobal = validateStackTraceMode(
+    tracingObj?.global?.stackTrace,


Its a bit confusing that for agent we forward the config value without global (see unannounced) but for incode we use the global usage here. That needs to be corrected, hard to follow the code.

kirrg001 · 2025-12-29T10:47:51Z

packages/core/src/config/configNormalizers/stackTrace.js

+  if (isAgentConfig) {
+    const configPath = 'stack-trace-length value from agent';
+
+    const validatedAgentConfig = validateStackTraceLength(tracingObj?.stackTraceLength, configPath);


I feel like we still mix validation and normalization :D
The parent caller should deal with that - otherwise you are coupling the code too much

kirrg001 · 2025-12-29T10:48:38Z

packages/core/src/config/configNormalizers/stackTrace.js

+  }
+
+  const validatedConfig = validateStackTraceLength(tracingObj?.stackTraceLength, 'config.tracing.stackTraceLength');
+  if (validatedConfig != null) {


Deprecation warning missing

kirrg001

See comments

packages/core/src/config/index.js

abhilash-sivan · 2025-12-29T13:59:24Z

packages/core/test/config/configNormalizers/stackTrace_test.js

    resetEnv();
  });

-  describe('normalize()', () => {


This function is now split into 2 and has some logic change (removed validation)

kirrg001 · 2025-12-29T15:40:40Z

packages/core/src/tracing/tracingUtil.js

+    stackTraceMode = agentTraceConfig.stackTrace;
+  }
+
+  // stackTraceLength is valid when set to any number, including 0


// stackTraceLength is valid when set to any number, including 0

Why do we have to do another validation check here? 🤔

At activation time, extraConfig?.tracing will be present, and stackTrace may or may not be set by the agent.
If we blindly assign the value, it may be undefined, which would overwrite the existing stackTraceMode.
Therefore, we need to check for its existence before assigning it.

The same applies to length, but in this case we must also support 0 as a valid value.
For that reason, we check the type to confirm validity.

Only when these checks pass do we overwrite the previously resolved value (from core, environment, or default).

ps: we follow this similar logic already:

nodejs/packages/core/src/util/spanFilter.js

Line 40 in 62dddcb

if (isIgnoreEndpointsEmpty && extraConfig?.tracing?.ignoreEndpoints) {

kirrg001 · 2025-12-29T15:41:37Z

packages/core/src/config/index.js


 module.exports.configNormalizers = configNormalizers;
+module.exports.configValidators = {
+  stackTraceValidation: require('./configValidators/stackTraceValidation')


Lets keep requires on top. There is a way to lazy load modules, but not part of this PR.

kirrg001 · 2025-12-29T15:43:06Z

packages/core/src/config/index.js

+  if (config.tracing.global?.stackTrace !== undefined) {
+    const modeResult = validateStackTraceMode(config.tracing.global.stackTrace);
+    if (!modeResult.isValid) {
+      logger.warn(`Invalid config.tracing.global.stackTrace: ${modeResult.error}`);


Bug: if not valid, you have to return and use the default

Yes, that is already covered in the logic. We validate first and then call the normaliser. The normaliser already returns the default in the relevant cases.

kirrg001 · 2025-12-29T15:47:01Z

packages/core/src/config/index.js

-      );
-      config.tracing.stackTraceLength = defaults.tracing.stackTraceLength;
+function normalizeTracingStackTrace(config) {
+  if (config.tracing.global?.stackTrace !== undefined) {


if (config.tracing.global?.stackTrace !== undefined) {
const modeResult = validateStackTraceMode(config.tracing.global.stackTrace);
if (!modeResult.isValid) {
logger.warn(Invalid config.tracing.global.stackTrace: ${modeResult.error});
}
}
config.tracing.stackTrace = configNormalizers.stackTrace.normalizeStackTraceMode(config);

Why do we call normalize if config.tracing.global?.stackTrace is not set?
The logic in this fn does not look right to me

This is the same as the previous case: the normaliser returns default values under the relevant conditions, such as when the value is not set or when an invalid value is provided.

Unlike the agent (unannounced), we always call the normaliser here. For the unannounced case, the normaliser is only called when a valid configuration is present.

I will change this to be in line with unannounced!

kirrg001

See comments

sonarqubecloud · 2025-12-29T16:57:53Z

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
85.1% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

abhilash-sivan force-pushed the feat-stack-trace branch from 5965b8c to b30a2d8 Compare December 17, 2025 05:14

abhilash-sivan mentioned this pull request Dec 17, 2025

feat: implemented span stack trace configuration #2181

Draft

20 tasks

abhilash-sivan force-pushed the feat-stack-trace-config-agent branch from 7213e70 to efa9059 Compare December 17, 2025 06:07

abhilash-sivan commented Dec 17, 2025

View reviewed changes

packages/core/test/config/normalizeConfig_test.js Show resolved Hide resolved

abhilash-sivan marked this pull request as ready for review December 17, 2025 06:34

abhilash-sivan requested a review from a team as a code owner December 17, 2025 06:34

abhilash-sivan marked this pull request as draft December 17, 2025 06:43

abhilash-sivan changed the title ~~feat: accept stack trace config from agent and apply limit of 50~~ feat: accept stack trace config from agent Dec 17, 2025

abhilash-sivan commented Dec 17, 2025

View reviewed changes

packages/core/src/config/index.js Outdated Show resolved Hide resolved

abhilash-sivan marked this pull request as ready for review December 17, 2025 10:34

kirrg001 reviewed Dec 18, 2025

View reviewed changes

packages/core/src/util/constants.js Show resolved Hide resolved

kirrg001 reviewed Dec 18, 2025

View reviewed changes

packages/core/test/config/normalizeConfig_test.js Show resolved Hide resolved

abhilash-sivan changed the title ~~feat: accept stack trace config from agent~~ feat: accept stack trace config from agent and env, and apply Dec 19, 2025

abhilash-sivan commented Dec 19, 2025

View reviewed changes

kirrg001 reviewed Dec 19, 2025

View reviewed changes

packages/collector/test/tracing/protocols/http/proxy/expressProxyControls.js Outdated Show resolved Hide resolved

kirrg001 reviewed Dec 19, 2025

View reviewed changes

packages/collector/test/tracing/misc/stack_trace/test.js Show resolved Hide resolved

kirrg001 reviewed Dec 19, 2025

View reviewed changes

packages/core/src/tracing/tracingUtil.js Outdated Show resolved Hide resolved

kirrg001 reviewed Dec 19, 2025

View reviewed changes

packages/core/src/config/index.js Outdated Show resolved Hide resolved

abhilash-sivan force-pushed the feat-stack-trace branch from b30a2d8 to 04b7085 Compare December 22, 2025 03:34

abhilash-sivan and others added 10 commits December 22, 2025 09:07

feat: accept stack trace config from agent and apply limit of 50

39dc792

chore: updated precedence

82bd90f

chore: typo

721991d

chore: optimize and add todo

3f2ab68

chore: update

dede9c9

chore: added INSTANA_STACK_TRACE

7725330

chore: removed unwanted comment

30bc5e4

Co-authored-by: kirrg001 <katharina.irrgang@ibm.com>

chore: updated variable name

e6e4178

chore: removed unwanted logs

36e62bc

chore: pr comment udpate

bf2221d

kirrg001 reviewed Dec 22, 2025

View reviewed changes

kirrg001 approved these changes Dec 22, 2025

View reviewed changes

abhilash-sivan added 2 commits December 22, 2025 16:00

chore: udpated code to follow precendence order agent, code, env

8bdd3e9

chore: refactor

557e26e

abhilash-sivan changed the title ~~feat: unified stack trace configuration from agent config and env vars~~ feat: unified stack trace configuration from agent, in-code and env vars Dec 22, 2025

chore: added support for incode config for tracing.global.stackTracel…

80f98e4

…ength

kirrg001 reviewed Dec 29, 2025

View reviewed changes

packages/core/src/config/configNormalizers/stackTrace.js Outdated Show resolved Hide resolved

kirrg001 reviewed Dec 29, 2025

View reviewed changes

packages/core/src/config/configNormalizers/stackTrace.js Outdated Show resolved Hide resolved

chore: updated comments

994c2ad

kirrg001 reviewed Dec 29, 2025

View reviewed changes

packages/collector/src/announceCycle/unannounced.js Show resolved Hide resolved

kirrg001 reviewed Dec 29, 2025

View reviewed changes

kirrg001 requested changes Dec 29, 2025

View reviewed changes

abhilash-sivan added 2 commits December 29, 2025 17:22

chore: pr comments

3ced00c

chore: refactor config normalizer and validator

80976b6

abhilash-sivan commented Dec 29, 2025

View reviewed changes

packages/core/src/config/index.js Show resolved Hide resolved

abhilash-sivan commented Dec 29, 2025

View reviewed changes

chore: removed duplicate log

bb4cf08

abhilash-sivan force-pushed the feat-stack-trace-config-agent branch from 686b641 to bb4cf08 Compare December 29, 2025 14:10

kirrg001 reviewed Dec 29, 2025

View reviewed changes

kirrg001 requested changes Dec 29, 2025

View reviewed changes

abhilash-sivan added 3 commits December 29, 2025 21:38

chore: corrected require

91de921

chore: fix logic in agent config normalisation

35f76be

test: fix tracingutil test

86461c1

feat: unified stack trace configuration from agent, in-code and env vars #2235

Are you sure you want to change the base?

feat: unified stack trace configuration from agent, in-code and env vars #2235

Uh oh!

Conversation

abhilash-sivan commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kirrg001 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kirrg001 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kirrg001 Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kirrg001 left a comment

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud bot commented Dec 29, 2025

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

abhilash-sivan commented Dec 16, 2025 •

edited

Loading

kirrg001 Dec 29, 2025 •

edited

Loading