Tracing Canonical Items

Canonical Item UUID

When Data Hub creates each new canonical item, it assigns a universally unique identifier (UUID) to it. The UUID is persisted together with the canonical item in the database. The UUID is guaranteed to be unique, even after you restart and reinitialize Data Hub. No existing UUID ever gets overwritten, making monitoring and tracing canonical items possible, even over extended periods of time.

All new canonical items, including those items created during a merge operation, are assigned a new UUID. However, if the status of an existing canonical item changes, the original UUID is maintained. This process is explained in the following diagram.

Assignment of Canonical Item UUIDs during a merge

When canonical items are merged, a new canonical item results from the merge, which is given a new UUID. Data Hub then archives the original canonical items, maintaining their original UUIDs.

Raw Item Batch ID and Trace ID for Canonical Items

In addition to the canonical item UUID, Data Hub populates each canonical item with an associated raw item batch ID and traceID. Sometimes more than one raw item results in a single canonical item. In those cases, Data Hub takes the batch ID and trace ID from the last raw item picked up for composition in that composition group. In this way, canonical items are linked to the raw items from which they are composed.

Using the batch ID and trace ID, you can track canonical items through their lifecycle based on their raw item origin.

+----+-------------------+--------------------------------------+--------------------------------------+
| id | batchid           | traceid                              | uuid                                 |
+----+-------------------+--------------------------------------+--------------------------------------+
|  1 | 123|456|myVariant | ce8ffd71-775d-31a2-a2be-03932f028b43 | 0f906cc7-f92a-456b-9e3e-70545ccc755c |
+----+-------------------+--------------------------------------+--------------------------------------+

When merging a new and existing canonical item, the merged canonical item takes its batch and trace IDs from the newest canonical item being merged. An ArchivedCanonicalItemEvent fires for each canonical item archived and persisted during the merge. These archived canonical items contain their original raw item batch and trace IDs. Data Hub also fires an ArchivedCanonicalItemEvent for each raw item, when items from more than one batch are composed into a single canonical item.

UUID, BatchID, and TraceID in Events and Logging

When you enable item-level events for canonical items, Data Hub includes the canonical item UUID, batch ID, and trace ID in all related event publications. If you also enable item-level logging, the IDs are recorded for each canonical item in the logs, as follows:

2017-02-23 10:54:15,862 [INFO] [c.h.d.l.i.CanonicalItemLoggingService] GLOBAL CanonicalProduct uuid=0f906cc7-f92a-456b-9e3e-70545ccc755c id=1 action=1 status=SUCCESS integrationKey='1' rawSources=[1] traceId=5f3f3118-1411-3353-b658-4aa1c4e2aef3 batchId=123|456|myVariant

For more information on enabling item level logging, see Logging Item Behavior.