Skip to content

Diagnostic Trace Configuration

Diagnostic traces record short-lived execution details for workflow work items. They are useful while testing or troubleshooting process behavior, but they can add runtime storage and payload overhead. Configure them at the node level so each agent node captures the amount of diagnostic data that is appropriate for its role.

Trace Mode

Trace capture is controlled by Diagnostics:TraceMode.

Value Behavior
Disabled Does not capture traces and does not return stored traces.
TestMode Captures and returns traces only for test-mode instances.
All Captures and returns traces for both test-mode and live instances.

When Diagnostics:TraceMode is not set, the runtime falls back to TestMode unless the legacy Diagnostics:TraceEnabled setting is true, which enables All.

Retention

Stored trace retention is controlled by Diagnostics:TraceRetentionHours.

If the value is not set, or if it is set to zero or a negative number, the default retention is 24 hours. Keep retention short enough for diagnostics while avoiding unnecessary cache growth.

Configuration Examples

Example appsettings.json configuration:

1
2
3
4
5
6
{
  "Diagnostics": {
    "TraceMode": "TestMode",
    "TraceRetentionHours": 24
  }
}

Example environment variable overrides:

1
2
AK_Diagnostics__TraceMode=All
AK_Diagnostics__TraceRetentionHours=12

Set TraceMode to All only when live-instance diagnostics are needed. For normal process-development support, TestMode keeps diagnostics available for test runs without capturing every live work item.

Operational Notes

Diagnostic trace configuration is node-local. Apply the same settings to all web and worker nodes that should capture or return the same traces.

Traces are stored separately from business records and expire according to the configured retention. They should be treated as troubleshooting data, not as an audit log or long-term business history.