Package io.mats3.util

Class TraceId


public class TraceId extends Object
A small tool to produce a String - specifically an opinionated TraceId. An example of such a string could be "Order.placeOrder:calcShipping[cid:123456][oid:654321]iu4m3p.

The tool accepts null for any of the three "mandatory" pieces "appShort", "initShort" and "reason".

Remember that TraceIds should be as short as possible! Be conservative with the lengths of these constituent strings, and key names, and key values! Don't use UUIDs, they are typically both way too unique, and way too long since they only use a limited alphabet.

  1. appShort: A short-form of the application name - i.e. which service started this Mats Flow.
  2. initShort: A short-form of the InitiatorId - i.e. some clue as to where in the service's codebase this originates.
  3. reason: An element of "reason" behind for creating this Flow, either an element of "to", i.e. which service this targets. Or if multiple flows originate from this initiatorId-point, then a "sub-init" element.
  4. batchId(..): If this Mats Flow is a part of several that are sent out in a batch, then you may employ this to group them together.

The special factory variants concat(..) and fork(..) are used if you already have some kind of eventId or traceId which you want to hook into the new Mats Flow. If you want to add contextual information on the existing eventId for a new single Mats Flow, then you use concat(..) (uses a "+"). If this one single event leads to multiple new flows, then you use form(..) (uses a "|" - which is done automatically for you if you initiate new messages from within a Mats Flow, i.e. inside a Stage with processContext.initiate(..).

The only important thing with a TraceId is that it is unique. All else is only relevant for understanding when you need to reason about a specific flow, typically in a debugging scenario, e.g. why did this end up on a Dead Letter Queue. It is extremely nice to then immediately understand quite a bit out from the TraceId alone.

Note: It is possible to extend this concept into domain-specific tools which add more specialized add(key, value)-variants in that the key is specified. E.g. if you in many contexts have customerId and an orderId, it is nice if this always uses the same key "custId" and "orderId", instead of this varying between the initiating services. Thus you add a method customerId(value) and orderId(value), which just forwards to the add-method.

There's a document about these identifiers at Mats3's github: TraceIds and InitiatorIds.