Annex C OpenTelemetry Mapping (Normative)

C.1 Open Telemetry Overview

OpenTelemetry is described as “a vendor-neutral open source observability framework for instrumenting, generating, collecting, and exporting telemetry data such as traces, metrics, and logs.” This modern system includes an infrastructure for collecting trace / metrics / log data, but this infrastructure may be too resource intensive for constrained devices. In these cases, it would be useful to be able to collect log / trace information and import it into the OpenTelemetry system.

In OpenTelemetry, a client triggered action can be assigned a globally unique trace-id (a 16 byte identifier, excluding 0). This trace-id is maintained for all actions related to the client request. In addition, actions are grouped using a unique span-id (an 8 byte identifier, excluding 0). This span-id might be promoted to a parent-id, when a tree of related trace / log message needs to be generated. This process is illustrated in Figure C.1.

The TraceId in OPC UA is a GUID (16 byte unique identifier). The SpanId in OPC UA is an UInt64 (8 byte integer, excluding 0), and it should be unique inside of a TraceId inside of an application. An easy manner of achieving this is to just increment an UInt64 and persist the last value across the Application. If an Application receives a passed in TraceId and SpanId, the passed in SpanId becomes a ParentId and unique SpanIds are generated in the Application. If an application cannot generate a unique SpanId, then it may leave it as null (see C.2).

Figure C.1 also illustrates how an OpenTelemetry system could collect LogRecords from an LogObject C.2 describes part of the mapping an import tool would have to perform to convert LogObject LogRecords to OpenTelemetry records.

C.2 Open Telemetry System Import

If an OpenTelemetry system is importing LogObject LogRecords, the collector will need to pull information from the TraceContext field. This structure contains the TraceId and SpanId, it might also contain ParentSpanId (if one was provided). The SpanId field is used to group LogRecords together. If the SpanId field is null, then for each unique entry in the GroupingId field, the import tool shall generate a unique SpanId.

TraceId are always random, they are a generated GUID, so the FLAG_RANDOM Trace flag shall always be set.