Observability and Tracing
Overview
The platform implements distributed tracing and dynamic log-level control through HTTP headers that propagate across incoming requests, downstream service calls, and asynchronous message queues. This enables comprehensive monitoring, debugging, and request correlation across microservices.
Core Headers
| Header | Purpose | Scope | Notes |
|---|---|---|---|
X-Trace-Id | Distributed trace identifier for end-to-end request tracking | Propagated automatically through service calls and message queues | Auto-generated if absent |
X-Correlation-Id | Correlates all events from a single user session | Propagated through service calls and message queues | Assigned by client (UI) |
X-Request-Id | Unique identifier for a single HTTP request | Propagated through service calls (not message queues) | Fallback: random UUID if absent |
X-Debug-Level | Temporarily override the effective log level for the request | Applies to entire request lifecycle and downstream calls | Values: TRACE, DEBUG, INFO, WARN, ERROR |
X-Trace-Id
A unique trace ID is generated for every incoming request that does not already carry one. This identifier flows automatically through downstream service calls and message producer records, enabling you to follow a single user action across the entire distributed system.
Use case: Correlating log entries across multiple microservices to understand the full journey of a request.
X-Correlation-Id
Allows correlating all log entries that belong to a single user session across multiple services. This is typically set once at the UI level and remains constant for the entire user session, even across multiple requests.
Use case: Grouping all activity from a single user session, even if the session spans multiple HTTP requests and asynchronous processes.
X-Request-Id
Identifies a single HTTP request uniquely. Unlike the trace ID (which may span multiple requests), the request ID changes with each HTTP call.
Note: Request IDs propagate through service-to-service calls but are not carried through message queues.
X-Debug-Level
Temporarily raises the effective log level for the entire request lifecycle without modifying persistent configuration. This is useful for investigating issues in production by enabling DEBUG or TRACE logs on demand.
Valid values (case-insensitive): TRACE, DEBUG, INFO, WARN, ERROR
Scope: Single request only—the override does not persist beyond the current request thread.
Script Execution Logging
Scripts executed through SpEL bindings automatically generate structured logs with:
- Execution start and completion times
- Script result or failure status
- Correlation context (trace ID, request ID, session context)
- Entity type and lifecycle phase (for entity event scripts)
- Process engine context (if available)
All script logs include the correlation headers, enabling seamless tracing across automation and manual workflows.
Scoped Log Level Control in Scripts
Within SpEL scripts, you can temporarily raise the log level for a specific code block using @logger.withLevel():
@logger.withLevel('DEBUG').do(
#x = 10,
#y = 20,
@logger.debug("Calculation: " + #x + " + " + #y),
#x + #y
)
How it works:
- The log level is elevated to the specified level (
DEBUG,TRACE, etc.) only for expressions within the.do()block - All logging statements inside the block will respect the elevated level, even if the logger is normally configured at a higher threshold (e.g.,
INFO) - Once the block completes, the log level reverts to its previous state
- The last expression in the block is the return value
Use case: Enable verbose logging for specific sections of complex scripts without affecting the log level globally or for the entire request.
Configuration
Baggage configuration and header propagation rules are defined in the application commons configuration. The specific implementation details (filter names, class structures, configuration file locations) are maintained separately in the infrastructure documentation to avoid coupling business logic with internal infrastructure details.
Refer to the tsm-infra/docs repository for implementation-level details.