trace.proto

Package : opencensus.proto.trace.v1

Top

trace.proto

Table of Contents

AttributeValue

Field Type Label Description
stringValue opencensus.proto.trace.v1.TruncatableString A string up to 256 bytes long.
intValue int64 A 64-bit signed integer.
boolValue bool A Boolean value represented by true or false.
doubleValue double A double value.

Module

Field Type Label Description
module opencensus.proto.trace.v1.TruncatableString TODO: document the meaning of this field. For example: main binary, kernel modules, and dynamic libraries such as libc.so, sharedlib.so.
buildId opencensus.proto.trace.v1.TruncatableString A unique identifier for the module, usually a hash of its contents.

Span

Field Type Label Description
traceId bytes A unique identifier for a trace. All spans from the same trace share the same trace_id. The ID is a 16-byte array. An ID with all zeroes is considered invalid.
This field is semantically required. Receiver should generate new random trace_id if empty or invalid trace_id was received.
This field is required.
spanId bytes A unique identifier for a span within a trace, assigned when the span is created. The ID is an 8-byte array. An ID with all zeroes is considered invalid.
This field is semantically required. Receiver should generate new random span_id if empty or invalid span_id was received.
This field is required.
tracestate opencensus.proto.trace.v1.Span.Tracestate The Tracestate on the span.
parentSpanId bytes The span_id of this span's parent span. If this is a root span, then this field must be empty. The ID is an 8-byte array.
name opencensus.proto.trace.v1.TruncatableString A description of the span's operation.
For example, the name can be a qualified method name or a file name and a line number where the operation is called. A best practice is to use the same display name at the same call point in an application. This makes it easier to correlate spans in different traces.
This field is semantically required to be set to non-empty string. When null or empty string received - receiver may use string “name” as a replacement. There might be smarted algorithms implemented by receiver to fix the empty span name.
This field is required.
kind opencensus.proto.trace.v1.Span.SpanKind Distinguishes between spans generated in a particular context. For example, two spans with the same name may be distinguished using CLIENT (caller) and SERVER (callee) to identify queueing latency associated with the span.
startTime google.protobuf.Timestamp The start time of the span. On the client side, this is the time kept by the local machine where the span execution starts. On the server side, this is the time when the server's application handler starts running.
This field is semantically required. When not set on receive - receiver should set it to the value of end_time field if it was set. Or to the current time if neither was set. It is important to keep end_time > start_time for consistency.
This field is required.
endTime google.protobuf.Timestamp The end time of the span. On the client side, this is the time kept by the local machine where the span execution ends. On the server side, this is the time when the server application handler stops running.
This field is semantically required. When not set on receive - receiver should set it to start_time value. It is important to keep end_time > start_time for consistency.
This field is required.
attributes opencensus.proto.trace.v1.Span.Attributes A set of attributes on the span.
stackTrace opencensus.proto.trace.v1.StackTrace A stack trace captured at the start of the span.
timeEvents opencensus.proto.trace.v1.Span.TimeEvents The included time events.
links opencensus.proto.trace.v1.Span.Links The included links.
status opencensus.proto.trace.v1.Status An optional final status for this span. Semantically when Status wasn't set it is means span ended without errors and assume Status.Ok (code = 0).
resource opencensus.proto.resource.v1.Resource An optional resource that is associated with this span. If not set, this span should be part of a batch that does include the resource information, unless resource information is unknown.
sameProcessAsParentSpan google.protobuf.BoolValue A highly recommended but not required flag that identifies when a trace crosses a process boundary. True when the parent_span belongs to the same process as the current span. This flag is most commonly used to indicate the need to adjust time as clocks in different processes may not be synchronized.
childSpanCount google.protobuf.UInt32Value An optional number of child spans that were generated while this span was active. If set, allows an implementation to detect missing child spans.

Span.Attributes

Field Type Label Description
attributeMap []opencensus.proto.trace.v1.Span.Attributes.AttributeMapEntry repeated The set of attributes. The value can be a string, an integer, a double or the Boolean values true or false. Note, global attributes like server name can be set as tags using resource API. Examples of attributes:
“/http/user_agent”: “Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36” “/http/server_latency”: 300 “abc.com/myattribute”: true “abc.com/score”: 10.239
droppedAttributesCount int32 The number of attributes that were discarded. Attributes can be discarded because their keys are too long or because there are too many attributes. If this value is 0, then no attributes were dropped.

Span.Attributes.AttributeMapEntry

Field Type Label Description
key string
value opencensus.proto.trace.v1.AttributeValue

Field Type Label Description
traceId bytes A unique identifier of a trace that this linked span is part of. The ID is a 16-byte array.
spanId bytes A unique identifier for the linked span. The ID is an 8-byte array.
type opencensus.proto.trace.v1.Span.Link.Type The relationship of the current span relative to the linked span.
attributes opencensus.proto.trace.v1.Span.Attributes A set of attributes on the link.
tracestate opencensus.proto.trace.v1.Span.Tracestate The Tracestate associated with the link.

Field Type Label Description
link []opencensus.proto.trace.v1.Span.Link repeated A collection of links.
droppedLinksCount int32 The number of dropped links after the maximum size was enforced. If this value is 0, then no links were dropped.

Span.TimeEvent

Field Type Label Description
time google.protobuf.Timestamp The time the event occurred.
annotation opencensus.proto.trace.v1.Span.TimeEvent.Annotation A text annotation with a set of attributes.
messageEvent opencensus.proto.trace.v1.Span.TimeEvent.MessageEvent An event describing a message sent/received between Spans.

Span.TimeEvent.Annotation

Field Type Label Description
description opencensus.proto.trace.v1.TruncatableString A user-supplied message describing the event.
attributes opencensus.proto.trace.v1.Span.Attributes A set of attributes on the annotation.

Span.TimeEvent.MessageEvent

Field Type Label Description
type opencensus.proto.trace.v1.Span.TimeEvent.MessageEvent.Type The type of MessageEvent. Indicates whether the message was sent or received.
id uint64 An identifier for the MessageEvent's message that can be used to match SENT and RECEIVED MessageEvents. For example, this field could represent a sequence ID for a streaming RPC. It is recommended to be unique within a Span.
uncompressedSize uint64 The number of uncompressed bytes sent or received.
compressedSize uint64 The number of compressed bytes sent or received. If zero, assumed to be the same size as uncompressed.

Span.TimeEvents

Field Type Label Description
timeEvent []opencensus.proto.trace.v1.Span.TimeEvent repeated A collection of TimeEvents.
droppedAnnotationsCount int32 The number of dropped annotations in all the included time events. If the value is 0, then no annotations were dropped.
droppedMessageEventsCount int32 The number of dropped message events in all the included time events. If the value is 0, then no message events were dropped.

Span.Tracestate

Field Type Label Description
entries []opencensus.proto.trace.v1.Span.Tracestate.Entry repeated A list of entries that represent the Tracestate.

Span.Tracestate.Entry

Field Type Label Description
key string The key must begin with a lowercase letter, and can only contain lowercase letters ‘a’-‘z’, digits ‘0’-‘9’, underscores ‘_', dashes ‘-', asterisks ‘*', and forward slashes ‘/'.
value string The value is opaque string up to 256 characters printable ASCII RFC0020 characters (i.e., the range 0x20 to 0x7E) except ‘,’ and ‘=’. Note that this also excludes tabs, newlines, carriage returns, etc.

StackTrace

Field Type Label Description
stackFrames opencensus.proto.trace.v1.StackTrace.StackFrames Stack frames in this stack trace.
stackTraceHashId uint64 The hash ID is used to conserve network bandwidth for duplicate stack traces within a single trace.
Often multiple spans will have identical stack traces. The first occurrence of a stack trace should contain both stack_frames and a value in stack_trace_hash_id.
Subsequent spans within the same request can refer to that stack trace by setting only stack_trace_hash_id.
TODO: describe how to deal with the case where stack_trace_hash_id is zero because it was not set.

StackTrace.StackFrame

Field Type Label Description
functionName opencensus.proto.trace.v1.TruncatableString The fully-qualified name that uniquely identifies the function or method that is active in this frame.
originalFunctionName opencensus.proto.trace.v1.TruncatableString An un-mangled function name, if function_name is mangled. The name can be fully qualified.
fileName opencensus.proto.trace.v1.TruncatableString The name of the source file where the function call appears.
lineNumber int64 The line number in file_name where the function call appears.
columnNumber int64 The column number where the function call appears, if available. This is important in JavaScript because of its anonymous functions.
loadModule opencensus.proto.trace.v1.Module The binary module from where the code was loaded.
sourceVersion opencensus.proto.trace.v1.TruncatableString The version of the deployed source code.

StackTrace.StackFrames

Field Type Label Description
frame []opencensus.proto.trace.v1.StackTrace.StackFrame repeated Stack frames in this call stack.
droppedFramesCount int32 The number of stack frames that were dropped because there were too many stack frames. If this value is 0, then no stack frames were dropped.

Status

Field Type Label Description
code int32 The status code. This is optional field. It is safe to assume 0 (OK) when not set.
message string A developer-facing error message, which should be in English.

TruncatableString

Field Type Label Description
value string The shortened string. For example, if the original string was 500 bytes long and the limit of the string was 128 bytes, then this value contains the first 128 bytes of the 500-byte string. Note that truncation always happens on a character boundary, to ensure that a truncated string is still valid UTF-8. Because it may contain multi-byte characters, the size of the truncated string may be less than the truncation limit.
truncatedByteCount int32 The number of bytes removed from the original string. If this value is 0, then the string was not shortened.

Span.Link.Type

Name Number Description
TYPE_UNSPECIFIED 0 The relationship of the two spans is unknown, or known but other than parent-child.
CHILD_LINKED_SPAN 1 The linked span is a child of the current span.
PARENT_LINKED_SPAN 2 The linked span is a parent of the current span.

Span.SpanKind

Name Number Description
SPAN_KIND_UNSPECIFIED 0 Unspecified.
SERVER 1 Indicates that the span covers server-side handling of an RPC or other remote network request.
CLIENT 2 Indicates that the span covers the client-side wrapper around an RPC or other remote request.

Span.TimeEvent.MessageEvent.Type

Name Number Description
TYPE_UNSPECIFIED 0 Unknown event type.
SENT 1 Indicates a sent message.
RECEIVED 2 Indicates a received message.