Module de.codecamp.tracer.core
Package de.codecamp.tracer

Interface TraceContext

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
NoOpTraceContext, TraceContextImpl
public interface TraceContext extends AutoCloseable
The TraceContext represents a certain area of code, like a method. Contexts can be nested. Each context has a root Trace that can be further divided into sub-traces.

  • Method Details

    • getId

      UUID getId()

    • isRootContext

      boolean isRootContext()
      Trace contexts can be nested. This method returns whether this is the root context.
      Returns:
      whether this is the root context

    • setExitThrowable

      void setExitThrowable(Throwable exitThrowable)
      Setting a throwable indicates that the trace context hasn't exited regularly. As a consequence, durations can't necessarily be compared to other traces.
      Parameters:
      exitThrowable - the throwable that exited the trace

    • openContext

      default TraceContext openContext(String fullContextName, String contextLabel)
      Opens a new sub-context. Each context will implicitly have an associated root trace. All traces started through that context will be sub-traces (i.e. children) of that root trace. If the context is started within another active context (i.e. also bound to the current thread), the new context's root trace will be a sub-trace of the currently active trace.
      Parameters:
      fullContextName - the full context name, typically the fully qualified name of the traced class suffixed with '#' and the method name, if applicable; this name is used for selection, e.g. in includes, excludes and warnings
      contextLabel - a label for the context; in contrast to fullContextName this is supposed to be a shorter label better suited for logging
      Returns:
      the started trace session
      See Also:

    • openContext

      TraceContext openContext(String fullContextName, String contextLabel, Object... labelFormatArgs)
      Opens a new sub-context. Each context will implicitly have an associated root trace. All traces started through that context will be sub-traces (i.e. children) of that root trace. If the context is started within another active context (i.e. also bound to the current thread), the new context's root trace will be a sub-trace of the currently active trace.
      Parameters:
      fullContextName - the full context name, typically the fully qualified name of the traced class suffixed with '#' and the method name, if applicable; this name is used for selection, e.g. in includes, excludes and warnings
      contextLabel - a label for the context; in contrast to fullContextName this is supposed to be a shorter label better suited for logging; may contain {} as placeholders that will be replaced with the given format arguments in sequence
      labelFormatArgs - the format arguments for the context label
      Returns:
      the started trace context
      See Also:

    • startTrace

      default ActiveTrace startTrace(String label)
      Starts a new sub-trace as a direct child of this trace context. Ends any currently active trace of this context, if there is one.

      This method returns an ActiveTrace that can be used in a try-with-resource.

      Parameters:
      label - the label to use for this trace
      Returns:
      an ActiveTrace that can be used in a try-with-resource

    • startTrace

      ActiveTrace startTrace(String label, Object... labelFormatArgs)
      Starts a new sub-trace within this trace context. Ends the currently active trace of this trace context, if there is one.

      v *

      Parameters:
      label - the label to use for this trace; may contain placeholders
      labelFormatArgs - the format arguments for the placeholders in the label
      Returns:
      an ActiveTrace that can be used in a try-with-resource

    • getActiveTrace

      ActiveTrace getActiveTrace()
      Returns the deepest currently active trace of the current context or a no-op dummy if none is available.
      Returns:
      the deepest currently active trace of the current context or a no-op dummy if none is available.

    • close

      void close()
      Closes this trace context. Closing a trace context is the responsibility of the one opening it.

      Overridden from AutoCloseable.close() to remove thrown Exception.

      Specified by:
      close in interface AutoCloseable