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.
appShort: A short-form of the application name - i.e. which service started this Mats Flow.initShort: A short-form of the InitiatorId - i.e. some clue as to where in the service's codebase this
originates.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.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.