Package org.opendaylight.infrautils.utils.mdc

Class ExecutionOrigin

  • All Implemented Interfaces:
    Serializable
    @Beta
public final class ExecutionOrigin
extends MDCEntry
    Execution Origin utility.

    An "Execution Origin" identifies the first (original) point of contact of an external event entering the system. That first event typically leads to numerous subsequent internal events in a system, and the point of such an ID is (only) to be able to correlate a series of such internal events among themselves and back to the original first external event. All log messages automatically include this ID.

    In the case of OpenDaylight, such "origins" include HTTP requests (which are often from the nortbound APIs exposed by YANG RESTCONF, but not limited to), or something like an incoming Thrift request from a router, or an OVSDB notification, etc.

    An Origin ID is "unique" within a certain given time span, which is typically "long enough" to correlate events. However it may "overflow" and repeat, at some point in time. This is dependent on the number of events (and thus the load of the system). This implementation issues an INFO level log indicating when such an overflow occurred.

    Author:
    Michael Vorburger.ch
    See Also:
    Serialized Form

    • Method Detail

      • next

        public static ExecutionOrigin next()
        Returns the next origin ID.

        This method does NOT put that next value into the MDC; doing that, as well as (crucially) cleaning it up again at some point, is the responsibility of the caller of this method, typically using one of MDCs' methods.

      • currentID

        public static String currentID()
        Returns the current origin ID.

        Normal application code will never have to invoke this. Do NOT explicitly use this in your Logger; the origin ID will already be automatically included in all ODL logs, always.

        Typical usage of this method would only be in order to e.g. propagate the current origin ID onwards to another system during an RPC call; if that other system has it's own tracing facility similar to this, it will make it possible to correlate events.

        This method is really just a convenience short-cut around MDC.get(MDC_KEY), and can be used for more readable code. It also does throw a clear error message instead of returning null.

        Throws:
        IllegalStateException - if there is no Origin ID set in the MDC

      • mdcValueString

        public String mdcValueString()
        The exact internal implementation format of this ID may change over time, and should not be relied upon. It currently is a char '0' padded base-32 encoded atomically incremented 64 bit long.
        Specified by:
        mdcValueString in class MDCEntry