trace.proto
Package : opencensus.proto.trace.v1
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 |
Span.Link
| 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. |
Span.Links
| 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. |