trace.proto

Package: opencensus.proto.trace

Copyright 2017, OpenCensus Authors

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Types:

Source File: github.com/solo-io/solo-kit/api/external/trace.proto

Span

A span represents a single operation within a trace. Spans can be nested to form a trace tree. Often, a trace contains a root span that describes the end-to-end latency, and one or more subspans for its sub-operations. A trace can also contain multiple root spans, or none at all. Spans do not need to be contiguous - there may be gaps or overlaps between spans in a trace.

The next id is 15. TODO(bdrutu): Add an example.

"traceId": bytes
"spanId": bytes
"parentSpanId": bytes
"name": .opencensus.proto.trace.TruncatableString
"kind": .opencensus.proto.trace.Span.SpanKind
"startTime": .google.protobuf.Timestamp
"endTime": .google.protobuf.Timestamp
"attributes": .opencensus.proto.trace.Span.Attributes
"stackTrace": .opencensus.proto.trace.StackTrace
"timeEvents": .opencensus.proto.trace.Span.TimeEvents
"links": .opencensus.proto.trace.Span.Links
"status": .opencensus.proto.trace.Status
"sameProcessAsParentSpan": .google.protobuf.BoolValue
"childSpanCount": .google.protobuf.UInt32Value

Field Type 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. 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. This field is required.
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.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 required.
kind .opencensus.proto.trace.Span.SpanKind Distinguishes between spans generated in a particular context. For example, two spans with the same name may be distinguished using CLIENT and SERVER 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.
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.
attributes .opencensus.proto.trace.Span.Attributes A set of attributes on the span.
stackTrace .opencensus.proto.trace.StackTrace A stack trace captured at the start of the span.
timeEvents .opencensus.proto.trace.Span.TimeEvents The included time events.
links .opencensus.proto.trace.Span.Links The inclued links.
status .opencensus.proto.trace.Status An optional final status for this span.
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.
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.

Attributes

A set of attributes, each with a key and a value.

"attributeMap": map<string, .opencensus.proto.trace.AttributeValue>
"droppedAttributesCount": int

Field Type Description
attributeMap map<string, .opencensus.proto.trace.AttributeValue> The set of attributes. The value can be a string, an integer, or the Boolean values true and false. For example: “/instance_id”: “my-instance” “/http/user_agent”: "" “/http/server_latency”: 300 “abc.com/myattribute”: true.
droppedAttributesCount int 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.

TimeEvent

A time-stamped annotation or message event in the Span.

"time": .google.protobuf.Timestamp
"annotation": .opencensus.proto.trace.Span.TimeEvent.Annotation
"messageEvent": .opencensus.proto.trace.Span.TimeEvent.MessageEvent

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

Annotation

A text annotation with a set of attributes.

"description": .opencensus.proto.trace.TruncatableString
"attributes": .opencensus.proto.trace.Span.Attributes

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

MessageEvent

An event describing a message sent/received between Spans.

"type": .opencensus.proto.trace.Span.TimeEvent.MessageEvent.Type
"id": int
"uncompressedSize": int
"compressedSize": int

Field Type Description
type .opencensus.proto.trace.Span.TimeEvent.MessageEvent.Type The type of MessageEvent. Indicates whether the message was sent or received.
id int 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 int The number of uncompressed bytes sent or received.
compressedSize int The number of compressed bytes sent or received. If zero, assumed to be the same size as uncompressed.

Type

Indicates whether the message was sent or received.

Name Description
TYPE_UNSPECIFIED Unknown event type.
SENT Indicates a sent message.
RECEIVED Indicates a received message.

TimeEvents

A collection of TimeEvents. A TimeEvent is a time-stamped annotation on the span, consisting of either user-supplied key-value pairs, or details of a message sent/received between Spans.

"timeEvent": []opencensus.proto.trace.Span.TimeEvent
"droppedAnnotationsCount": int
"droppedMessageEventsCount": int

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

A pointer from the current span to another span in the same trace or in a different trace. For example, this can be used in batching operations, where a single batch handler processes multiple requests from different traces or when the handler receives a request from a different project.

"traceId": bytes
"spanId": bytes
"type": .opencensus.proto.trace.Span.Link.Type
"attributes": .opencensus.proto.trace.Span.Attributes

Field Type 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.
spanId bytes A unique identifier for a span within a trace, assigned when the span is created. The ID is an 8-byte array.
type .opencensus.proto.trace.Span.Link.Type The relationship of the current span relative to the linked span.
attributes .opencensus.proto.trace.Span.Attributes A set of attributes on the link.

Type

The relationship of the current span relative to the linked span: child, parent, or unspecified.

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

A collection of links, which are references from this span to a span in the same or different trace.

"link": []opencensus.proto.trace.Span.Link
"droppedLinksCount": int

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

SpanKind

Type of span. Can be used to specify additional relationships between spans in addition to a parent/child relationship.

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

Status

The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. This proto’s fields are a subset of those of google.rpc.Status, which is used by gRPC.

"code": int
"message": string

Field Type Description
code int The status code.
message string A developer-facing error message, which should be in English.

AttributeValue

The value of an Attribute.

"stringValue": .opencensus.proto.trace.TruncatableString
"intValue": int
"boolValue": bool

Field Type Description
stringValue .opencensus.proto.trace.TruncatableString A string up to 256 bytes long. Only one of stringValue, intValue, or boolValue can be set.
intValue int A 64-bit signed integer. Only one of intValue, stringValue, or boolValue can be set.
boolValue bool A Boolean value represented by true or false. Only one of boolValue, stringValue, or intValue can be set.

StackTrace

The call stack which originated this span.

"stackFrames": .opencensus.proto.trace.StackTrace.StackFrames
"stackTraceHashId": int

Field Type Description
stackFrames .opencensus.proto.trace.StackTrace.StackFrames Stack frames in this stack trace.
stackTraceHashId int 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.

StackFrame

A single stack frame in a stack trace.

"functionName": .opencensus.proto.trace.TruncatableString
"originalFunctionName": .opencensus.proto.trace.TruncatableString
"fileName": .opencensus.proto.trace.TruncatableString
"lineNumber": int
"columnNumber": int
"loadModule": .opencensus.proto.trace.Module
"sourceVersion": .opencensus.proto.trace.TruncatableString

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

StackFrames

A collection of stack frames, which can be truncated.

"frame": []opencensus.proto.trace.StackTrace.StackFrame
"droppedFramesCount": int

Field Type Description
frame []opencensus.proto.trace.StackTrace.StackFrame Stack frames in this call stack.
droppedFramesCount int 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.

Module

A description of a binary module.

"module": .opencensus.proto.trace.TruncatableString
"buildId": .opencensus.proto.trace.TruncatableString

Field Type Description
module .opencensus.proto.trace.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.TruncatableString A unique identifier for the module, usually a hash of its contents.

TruncatableString

A string that might be shortened to a specified length.

"value": string
"truncatedByteCount": int

Field Type 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 int The number of bytes removed from the original string. If this value is 0, then the string was not shortened.