Package com.tnsai.resilience

Class TracedSpan

java.lang.Object

com.tnsai.resilience.TracedSpan

All Implemented Interfaces:

AutoCloseable

public final class TracedSpan
extends Object
implements AutoCloseable

Per-invocation handle for a @Traced action — opened by TracedResolver.open(com.tnsai.metadata.ActionMetadata, com.tnsai.roles.Role, java.util.Map<java.lang.String, java.lang.Object>) immediately before dispatch and closed in a finally block. Emits two structured log lines per invocation (span.start + span.end) with a shared trace id, and pushes the trace id onto the SLF4J MDC so downstream logs within the same dispatch correlate cleanly.

Caller pattern (already wired in ActionExecutor):

 TracedSpan span = TracedResolver.open(action, role, params);
 try {
     Object result = executor.execute(...);
     span.recordSuccess(result);
     return result;
 } catch (Exception e) {
     // Narrow to Exception per the codebase's no-broad-catch rule
     // — JVM-fatal Errors propagate; the close() finally still runs.
     span.recordFailure(e);
     throw e;
 } finally {
     span.close();
 }
 

NOOP is returned when no @Traced annotation is present, so the calling pattern never branches.

Phase 1 emits via SLF4J only; Phase 2 will hand off to an OpenTelemetry SPI without changing the calling shape.

Since:

0.5.4 (issue #173, Phase 1)

Field Summary

Fields

Modifier and Type	Field	Description
static final String	MDC_TRACE_ID_KEY	Standard MDC key — downstream logs in the same dispatch reuse this trace id.
static final TracedSpan	NOOP	No-op span returned for actions without @Traced.

Method Summary

Modifier and Type	Method	Description
void	close()
void	recordFailure(Throwable t)	Marks the span as failed with the given throwable.
void	recordSuccess(Object result)	Marks the span as successful with the given return value (logged only if includeResult).

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

MDC_TRACE_ID_KEY

public static final String MDC_TRACE_ID_KEY

Standard MDC key — downstream logs in the same dispatch reuse this trace id.

See Also:

• Constant Field Values

NOOP

public static final TracedSpan NOOP

No-op span returned for actions without @Traced.

Method Details

recordSuccess

public void recordSuccess(Object result)

Marks the span as successful with the given return value (logged only if includeResult).

recordFailure

public void recordFailure(Throwable t)

Marks the span as failed with the given throwable.

close

public void close()

Specified by:

close in interface AutoCloseable