Configuring stack traces for .NET Framework

By default, the .NET Framework Tracer captures stack traces for all spans with a default stack trace depth of 35 frames. You can use the stack trace configuration to control the amount of trace data that is collected and ingested by Instana. Use stack trace configuration to customize the .NET Framework Tracer to collect stack traces only for erroneous spans, disable stack trace collection entirely, and control stack trace depth.

Important:
With the introduction of Stack traces configuration, the INSTANA_OMIT_CALLBACK environment variable is deprecated in .NET Framework Tracer 1.321.2.

Configuration methods

The .NET Framework Tracer supports the following methods for configuring stack traces:

Option 1: Configuring stack traces through environment variables

You can configure the stack trace level and stack trace length by using the INSTANA_STACK_TRACE and INSTANA_STACK_TRACE_LENGTH environment variables.

Table 1. Stack trace environment variables
Environment variable Description Supported values
INSTANA_STACK_TRACE Stack trace level all (default): Collect stack traces for all spans; error: Collect stack traces only for erroneous EXIT spans. Stack traces are not collected for ENTRY spans (for example, ASP.NET request spans), as they typically contain only framework-level frames that offer little diagnostic value; none: Disable stack trace collection. Regardless of the configured mode, HTTP entry and exit spans that generate an error (span.ec=1) always report a stack trace.
INSTANA_STACK_TRACE_LENGTH Stack trace depth 1 – 200 (default: 35)

To collect stack traces only for erroneous spans with a stack trace depth of 10, set the following environment variables:

INSTANA_STACK_TRACE=error
INSTANA_STACK_TRACE_LENGTH=10

Option 2: Configuring stack traces through a YAML configuration file

For structured, version-controlled configuration, use a YAML configuration file.

To configure stack traces through a YAML configuration file, complete the following steps:

  1. Create a YAML configuration file, for example, instana-config.yaml, and add the stack trace configuration under the tracing.global section. You can also set per-technology overrides under tracing.<technology>: 
    tracing:
  global:
    stack-trace: error
    stack-trace-length: 12
  aspnet:
    stack-trace: all
    stack-trace-length: 20

    The tracing.global section applies to all spans. Use a tracing.<technology> section to override the global settings for a specific technology (for example, aspnet, sqlserver). Per-technology settings take precedence over tracing.global.

  2. Set the INSTANA_CONFIG_PATH environment variable to the absolute path of the YAML file: 
    INSTANA_CONFIG_PATH=C:\path\to\instana-config.yaml

For details about the supported fields and values, see Stack trace configuration reference.

Option 3: Configuring stack traces through Instana agent configuration

To configure stack traces through the Instana agent, create or update the com.instana.tracing section in the agent configuration.yaml file (<instana-agent>/etc/instana/configuration.yaml).

To collect stack traces for all spans with a stack trace depth of 4, add the following snippet to the agent configuration.yaml file:

com.instana.tracing:
  global:
    stack-trace: all
    stack-trace-length: 4
Note:
When you use a YAML configuration file (Option 2), use the tracing key (required). The com.instana.tracing key is also accepted for backward compatibility but triggers a deprecation warning.
Note:
The .NET Framework Tracer automatically fetches configuration from the agent at startup and periodically checks for updates. Subsequent configuration changes take effect without requiring a restart of the .NET Framework application.

For details about the supported fields and values, see Stack trace configuration reference.

Stack trace configuration reference

Use the following YAML syntax to provide the stack trace configuration:

# Use 'tracing' key in a YAML configuration file (required)
# Use 'com.instana.tracing' key in the agent configuration.yaml file (accepted for backward compatibility)
tracing:
  global:
    stack-trace: <string>
    stack-trace-length: <int>
  <technology>:          # Optional: override global settings per technology
    stack-trace: <string>
    stack-trace-length: <int>
Table 2. Stack trace configuration fields
Field Description Supported values
stack-trace Stack trace level all (default): Collect stack traces for all spans; error: Collect stack traces only for erroneous EXIT spans. Stack traces are not collected for ENTRY spans (for example, ASP.NET request spans), as they typically contain only framework-level frames that offer little diagnostic value; none: Disable stack trace collection. Regardless of the configured mode, HTTP entry and exit spans that generate an error (span.ec=1) always report a stack trace.
stack-trace-length Stack trace depth 1 – 200 (default: 35). For erroneous EXIT spans, the tracer may disregard this limit and capture the full stack.
Note:
The <technology> key in the tracing section accepts any technology identifier supported by the .NET Framework Tracer (for example, aspnet, sqlserver). Per-technology settings take precedence over tracing.global.

Configuration precedence

Stack trace configuration settings are applied in the following order of precedence:

  1. Stack trace configuration from the YAML configuration file that is passed through the INSTANA_CONFIG_PATH environment variable.
  2. Stack trace configuration set through the environment variables INSTANA_STACK_TRACE and INSTANA_STACK_TRACE_LENGTH.
  3. Stack trace configuration from the agent configuration.yaml file.

The precedence is evaluated and applied separately for the stack trace level and stack trace length settings.