README

Overview

This package implements a number of translators that help translate spans to and from OpenCensus format to a number of other supported formats such as Jaeger Proto, Jaeger Thrift, Zipkin Thrift, Zipkin JSON. This document mentions how certain non-obvious things should be handled.

Links:

• OpenTracing Semantic Conventions

Status Codes and Messages

OpenCensus

OpenCensus protocol has a special field to represent the status of an operation. The status field has two fields, an int32 field called code and a string field called message. When converting from other formats, status field must be set from the relevant tags/attributes of the source format. When converting from OC to other formats, the status field must be translated to appropriate tags/attributes of the target format.

Jaeger to OC

Jaeger spans may contain two possible sets of tags that can possibly represent the status of an operation:

• status.code and status.message
• http.status_code and http.status_message

When converting from Jaeger to OC,

1. OC status should be set from status.code and status.message tags if status.code tag is found on the Jaeger span. Since OC already has a special status field, these tags (status.code and status.message) are redundant and should be dropped from resultant OC span.
2. If the status.code tag is not present, status should be set from http.status_code and http.status_message if the http.status_code tag is found. HTTP status code should be mapped to the appropriate gRPC status code before using it in OC status. These tags should be preserved and added to the resultant OC span as attributes.
3. If none of the tags are found, OC status should not be set.

Zipkin to OC

In addition to the two sets of tags mentioned in the previous section, Zipkin spans can possibly contain a third set of tags to represent operation status resulting in the following sets of tags:

• census.status_code and census.status_description
• status.code and status.message
• http.status_code and http.status_message

When converting from Zipkin to OC,

1. OC status should be set from census.status_code and census.status_description if census.status_code tag is found on the Zipkin span. These tags should be dropped from the resultant OC span.
2. If the census.status_code tag is not found in step 1, OC status should be set from status.code and status.message tags if the status.code tag is present. The tags should be dropped from the resultant OC span.
3. If no tags are found in step 1 and 2, OC status should be set from http.status_code and http.status_message if either http.status_code tag is found. These tags should be preserved and added to the resultant OC span as attributes.
4. If none of the tags are found, OC status should not be set.

Note that codes and messages from different sets of tags should not be mixed to form the status field. For example, OC status should not contain code from http.status_code but message from status.message and vice-versa. Both fields must be set from the same set of tags even if it means leaving one of the two fields empty.

OC to Jaeger

When converting from OC to Jaeger, if the OC span has a status field set, then

• code should be added as a status.code tag.
• message should be added as a status.message tag.

OC to Zipkin

When converting from OC to Zipkin, if the OC span has the status field set, then

• code should be added as a census.status_code tag.
• message should be added as a census.status_description tag.

In addition to this, if the OC status field represents a non-OK status, then a tag with the key error should be added and set to the same value as that of the status message falling back to status code when status message is not available.

Note:

If either target tags (status.* or census.status_*) are already present on the span, then they should be preserved and not overwritten from the status field. This is extremely unlikely to happen within the collector because of how things are implemented but any other implementations should still follow this rule.

Converting HTTP status codes to OC codes

The following guidelines should be followed for translating HTTP status codes to OC ones. https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto

This is implemented by the tracetranslator package as HTTPToOCCodeMapper.

Documentation

Index

• Constants
• func AttributeArrayToSlice(attrArray pdata.AnyValueArray) []interface{}
• func AttributeMapToMap(attrMap pdata.AttributeMap) map[string]interface{}
• func AttributeValueToString(attr pdata.AttributeValue, jsonLike bool) string
• func BytesToInt64SpanID(b [8]byte) int64
• func BytesToInt64TraceID(traceID [16]byte) (int64, int64)
• func BytesToUInt64SpanID(b [8]byte) uint64
• func BytesToUInt64TraceID(traceID [16]byte) (uint64, uint64)
• func DetermineValueType(value string, omitSimpleTypes bool) pdata.AttributeValueType
• func HTTPStatusCodeFromOCStatus(code int32) int32
• func Int64ToByteSpanID(id int64) [8]byte
• func Int64ToByteTraceID(high, low int64) [16]byte
• func Int64ToSpanID(id int64) pdata.SpanID
• func Int64ToTraceID(high, low int64) pdata.TraceID
• func OCAttributeKeyExist(ocAttributes *tracepb.Span_Attributes, key string) bool
• func OCStatusCodeFromHTTP(code int32) int32
• func StatusCodeFromHTTP(httpStatusCode int) pdata.StatusCode
• func TraceIDToUInt64Pair(traceID pdata.TraceID) (uint64, uint64)
• func UInt64ToByteSpanID(id uint64) [8]byte
• func UInt64ToByteTraceID(high, low uint64) [16]byte
• func UInt64ToSpanID(id uint64) pdata.SpanID
• func UInt64ToTraceID(high, low uint64) pdata.TraceID
• func UpsertStringToAttributeMap(key string, val string, dest pdata.AttributeMap, omitSimpleTypes bool)
• type OpenTracingSpanKind

Constants

const (
	OCOK                 = 0
	OCCancelled          = 1
	OCUnknown            = 2
	OCInvalidArgument    = 3
	OCDeadlineExceeded   = 4
	OCNotFound           = 5
	OCAlreadyExists      = 6
	OCPermissionDenied   = 7
	OCResourceExhausted  = 8
	OCFailedPrecondition = 9
	OCAborted            = 10
	OCOutOfRange         = 11
	OCUnimplemented      = 12
	OCInternal           = 13
	OCUnavailable        = 14
	OCDataLoss           = 15
	OCUnauthenticated    = 16
)

https://github.com/googleapis/googleapis/blob/bee79fbe03254a35db125dc6d2f1e9b752b390fe/google/rpc/code.proto#L33-L186

const (
	AnnotationDescriptionKey = "description"

	MessageEventIDKey               = "message.id"
	MessageEventTypeKey             = "message.type"
	MessageEventCompressedSizeKey   = "message.compressed_size"
	MessageEventUncompressedSizeKey = "message.uncompressed_size"

	TagMessage = "message"

	TagSpanKind = "span.kind"

	TagStatusCode          = "status.code"
	TagStatusMsg           = "status.message"
	TagError               = "error"
	TagHTTPStatusCode      = "http.status_code"
	TagHTTPStatusMsg       = "http.status_message"
	TagZipkinCensusCode    = "census.status_code"
	TagZipkinCensusMsg     = "census.status_description"
	TagZipkinOpenCensusMsg = "opencensus.status_description"

	TagW3CTraceState          = "w3c.tracestate"
	TagServiceNameSource      = "otlp.service.name.source"
	TagInstrumentationName    = "otlp.instrumentation.library.name"
	TagInstrumentationVersion = "otlp.instrumentation.library.version"
)

Some of the keys used to represent OTLP constructs as tags or annotations in other formats.

const (
	SpanLinkDataFormat  = "%s|%s|%s|%s|%d"
	SpanEventDataFormat = "%s|%s|%d"
)

const (
	ResourceNoServiceName = "OTLPResourceNoServiceName"
)

Constants used for signifying batch-level attribute values where not supplied by OTLP data but required by other protocols.

Variables

This section is empty.

Functions

func AttributeArrayToSlice

func AttributeArrayToSlice(attrArray pdata.AnyValueArray) []interface{}

func AttributeMapToMap

func AttributeMapToMap(attrMap pdata.AttributeMap) map[string]interface{}

AttributeMapToMap converts an OTLP AttributeMap to a standard go map

func AttributeValueToString

func AttributeValueToString(attr pdata.AttributeValue, jsonLike bool) string

AttributeValueToString converts an OTLP AttributeValue object to its equivalent string representation

func BytesToInt64SpanID

func BytesToInt64SpanID(b [8]byte) int64

BytesToInt64SpanID takes a []byte representation of a SpanID and converts it to a int64 representation.

func BytesToInt64TraceID

func BytesToInt64TraceID(traceID [16]byte) (int64, int64)

BytesToInt64TraceID takes a []byte representation of a TraceID and converts it to a two int64 representation.

func BytesToUInt64SpanID

func BytesToUInt64SpanID(b [8]byte) uint64

BytesToUInt64SpanID takes a []byte representation of a SpanID and converts it to a uint64 representation.

func BytesToUInt64TraceID

func BytesToUInt64TraceID(traceID [16]byte) (uint64, uint64)

BytesToUInt64TraceID takes a []byte representation of a TraceID and converts it to a two uint64 representation.

func DetermineValueType

func DetermineValueType(value string, omitSimpleTypes bool) pdata.AttributeValueType

DetermineValueType returns the native OTLP attribute type the string translates to.

func HTTPStatusCodeFromOCStatus

func HTTPStatusCodeFromOCStatus(code int32) int32

HTTPStatusCodeFromOCStatus takes an OpenTelemetry status code and return the appropriate HTTP status code See: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/data-http.md

func Int64ToByteSpanID

func Int64ToByteSpanID(id int64) [8]byte

Int64ToByteSpanID takes a int64 representation of a SpanID and converts it to a []byte representation.

func Int64ToByteTraceID

func Int64ToByteTraceID(high, low int64) [16]byte

Int64ToByteTraceID takes a two int64 representation of a TraceID and converts it to a []byte representation.

func Int64ToSpanID

func Int64ToSpanID(id int64) pdata.SpanID

Int64ToByteSpanID takes a int64 representation of a SpanID and converts it to a []byte representation.

func Int64ToTraceID

func Int64ToTraceID(high, low int64) pdata.TraceID

Int64ToByteTraceID takes a two int64 representation of a TraceID and converts it to a []byte representation.

func OCAttributeKeyExist

func OCAttributeKeyExist(ocAttributes *tracepb.Span_Attributes, key string) bool

OCAttributeKeyExist returns true if a key in attribute of an OC Span exists. It returns false, if attributes is nil, the map itself is nil or the key wasn't found.

func OCStatusCodeFromHTTP

func OCStatusCodeFromHTTP(code int32) int32

OCStatusCodeFromHTTP takes an HTTP status code and return the appropriate OpenTelemetry status code See: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/data-http.md

func StatusCodeFromHTTP

func StatusCodeFromHTTP(httpStatusCode int) pdata.StatusCode

StatusCodeFromHTTP takes an HTTP status code and return the appropriate OpenTelemetry status code See: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md#status

func TraceIDToUInt64Pair

func TraceIDToUInt64Pair(traceID pdata.TraceID) (uint64, uint64)

TraceIDToUInt64Pair takes a pdata.TraceID and converts it to a pair of uint64 representation.

func UInt64ToByteSpanID

func UInt64ToByteSpanID(id uint64) [8]byte

UInt64ToByteSpanID takes a uint64 representation of a SpanID and converts it to a []byte representation.

func UInt64ToByteTraceID

func UInt64ToByteTraceID(high, low uint64) [16]byte

UInt64ToByteTraceID takes a two uint64 representation of a TraceID and converts it to a []byte representation.

func UInt64ToSpanID

func UInt64ToSpanID(id uint64) pdata.SpanID

UInt64ToSpanID takes a uint64 representation of a SpanID and converts it to a pdata.SpanID representation.

func UInt64ToTraceID

func UInt64ToTraceID(high, low uint64) pdata.TraceID

UInt64ToByteTraceID takes a two uint64 representation of a TraceID and converts it to a []byte representation.

func UpsertStringToAttributeMap

func UpsertStringToAttributeMap(key string, val string, dest pdata.AttributeMap, omitSimpleTypes bool)

UpsertStringToAttributeMap upserts a string value to the specified key as it's native OTLP type

Types

type OpenTracingSpanKind

type OpenTracingSpanKind string

OpenTracingSpanKind are possible values for TagSpanKind and match the OpenTracing conventions: https://github.com/opentracing/specification/blob/main/semantic_conventions.md These values are used for representing span kinds that have no equivalents in OpenCensus format. They are stored as values of TagSpanKind

const (
	OpenTracingSpanKindUnspecified OpenTracingSpanKind = ""
	OpenTracingSpanKindClient      OpenTracingSpanKind = "client"
	OpenTracingSpanKindServer      OpenTracingSpanKind = "server"
	OpenTracingSpanKindConsumer    OpenTracingSpanKind = "consumer"
	OpenTracingSpanKindProducer    OpenTracingSpanKind = "producer"
	OpenTracingSpanKindInternal    OpenTracingSpanKind = "internal"
)