feat: implemented span stack trace configuration

[abhilash-sivan]

EPIC link: https://jsw.ibm.com/browse/INSTA-57356

This will be the final PR to main for the stack trace filtering feature!

This PR proposes a refactor of the current instrumentation error/stack logic and introduces a new configuration option (INSTANA_STACK_TRACE) to control stack trace collection behaviour across all instrumentations based on the EPIC design.

---

Goals / Design

• Unify and simplify error/stack handling across all instrumentations. -refactor
• Add configurable stack trace modes (none, error, all) - implementation

in-code/env:
INSTANA_STACK_TRACE_LENGTH (was already supported by Node.js tracer) - this is global. We don't have any community design for global/local envs yet.
INSTANA_STACK_TRACE (this is new) - this is also global. We don't have any community design for global/local envs yet.
tracing.stackTraceLength (was already supported by Node.js tracer) -> this is also global. We accept tracing.global.stackTraceLength as an input param and we print a deprecation warning for tracing.stackTraceLength. Later on as soon as we have full local filtering support, we can continue with the migration.
tracing.stackTrace (this is new) - this is also global for now. Same here, we start with the migration (tracing.global.stackTrace) and finish it up as soon as we have to (because there is no local filtering support yet)

agent:
tracing.global.stackTraceLength (this is new)
tracing.global.stackTrace (this is new)
-> no local support yet (this needs to go into the post task for stack trace filtering)

1. Refactor & Unify Instrumentation Logic

1.1 Introduce a Common Error / Stack Handling Helper

Unify setError logic

Create a shared helper used by all instrumentations for attaching error details and stack traces.

Ensure getErrorDetails always returns a string

Guarantees consistent type in span.data.<tech>.error.

Implement V8 string → stack trace conversion

Handle cases where the stack arrives as a plain string.
Add a test validating correct conversion behaviour.

Add dedicated tests

At least one test to ensure conversion logic is correct.

---

1.2 Update All Instrumentations to Use Shared Logic

All categories will be updated to call the new unified helper:

• DB instrumentations
• Messaging instrumentations
• Protocol / HTTP instrumentations

This ensures:

• Consistent error assignment
• Consistent stack generation / overwrite rules
• Reduced code duplication

---

1.3 Add Category-Level Tests

Tests to validate:

• Every category behaves consistently under errors
• Stack traces are attached or removed correctly
• Error fields are stringified

---

2. Add Configurable Stack Trace Mode

Introduce a configuration setting:

INSTANA_STACK_TRACE = none | error | all
configuration via agent and custom file

2.1 Implement Stack Trace Mode Behaviour

---

2.2 Add or Update Tests

Add full coverage for the three modes:

• none → stack always removed
• error → stack present only on error
• all → stack always present (and overwritten on error)

---

Task List Summary

Refactoring Tasks

• Unify setError across all instrumentations
• strong test in generic stack_trace for error case - test: added test for span.stack replacement logic #2213
• Extension of setErrorDetails function: refactor: added error stack replacement logic #2167 (comment)
• setErrorDetails needs to handle err being a string – e.g., nats, natsStreaming chore: updated setErrorStack to handle string error case for nats, etc #2214
• setErrorDetails needs to handle err.details – e.g., grpcJs - refactor: updated grpc to use setErrorDetails fn #2216
• fix SDK Error capture logic (Different custom key for error) - refactor: updated sdk to use setErrorDetails fn #2222
• Remove usage of getErrorDetails - refactor: updated sdk to use setErrorDetails fn #2222
• Implement V8 string → stack trace conversion refactor: added utility to convert V8 stack string into Instana call site object #2226
• Add try/catch in setErrorDetails fn

---

Stack Trace Configuration Tasks

• Introduce to codebase INSTANA_STACK_TRACE_LENGTH env variable – already implemented in our codebase
• Accept stackTraceLength configuration from in-code and agent config - feat: unified stack trace configuration from agent, in-code and env vars #2235
• Accept stackTrace configuration from in-code and agent config - feat: unified stack trace configuration from agent, in-code and env vars #2235
• Apply the stackTraceLength limit on the setErrorDetails and getStackDetails functions
• Introduce INSTANA_STACK_TRACE env variable – only the global configuration for now; create card for the technology-specific implementation later
• Add TDD and implement modes (none | error | all)
• Filtering on stack.error, ie, removing node_modules & internal calls (decide about internal calls) - added todo https://jsw.ibm.com/browse/INSTA-64086
• INSTANA_CONFIG_PATH implementation - create card for later - already have one https://jsw.ibm.com/browse/INSTA-41392

---

Optional

• We should not generate stacks at all if span is filtered out

---

After Implementation

• Update public documentation to reflect the new configuration and unified behaviour.

points to note:

1. Stack trace length:

   max length: 500
   by default: 10

---

Other issues to resolve after this PR/in between directly to main

• Move some config constants to the newly created file packages/core/src/util/constants.js (unrelated to stack tarce feat)
• feat: unified stack trace configuration from agent, in-code and env vars #2235 (comment)
• feat: unified stack trace configuration from agent, in-code and env vars #2235 (comment)