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:
- Span
- Attributes
- TimeEvent
- Annotation
- MessageEvent
- Type
- TimeEvents
- Link
- Type
- Links
- SpanKind
- Status
- AttributeValue
- StackTrace
- StackFrame
- StackFrames
- Module
- TruncatableString
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. |
Link
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. |
Links
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. |