// Copyright 2024 Google LLC
//
// 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.
syntax = "proto3";
package google.devtools.cloudtrace.v2;
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";
import "google/rpc/status.proto";
option csharp_namespace = "Google.Cloud.Trace.V2";
option go_package = "cloud.google.com/go/trace/apiv2/tracepb;tracepb";
option java_multiple_files = true;
option java_outer_classname = "TraceProto";
option java_package = "com.google.devtools.cloudtrace.v2";
option php_namespace = "Google\\Cloud\\Trace\\V2";
option ruby_package = "Google::Cloud::Trace::V2";
// 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 might be
// gaps or overlaps between spans in a trace.
message Span {
option (google.api.resource) = {
type: "cloudtrace.googleapis.com/Span"
pattern: "projects/{project}/traces/{trace}/spans/{span}"
};
// A set of attributes as key-value pairs.
message Attributes {
// A set of attributes. Each attribute's key can be up to 128 bytes
// long. The value can be a string up to 256 bytes, a signed 64-bit integer,
// or the boolean values `true` or `false`. For example:
//
// "/instance_id": { "string_value": { "value": "my-instance" } }
// "/http/request_bytes": { "int_value": 300 }
// "abc.com/myattribute": { "bool_value": false }
map<string, AttributeValue> attribute_map = 1;
// 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 all attributes are valid.
int32 dropped_attributes_count = 2;
}
// A time-stamped annotation or message event in the Span.
message TimeEvent {
// Text annotation with a set of attributes.
message Annotation {
// A user-supplied message describing the event. The maximum length for
// the description is 256 bytes.
TruncatableString description = 1;
// A set of attributes on the annotation. You can have up to 4 attributes
// per Annotation.
Attributes attributes = 2;
}
// An event describing a message sent/received between Spans.
message MessageEvent {
// Indicates whether the message was sent or received.
enum Type {
// Unknown event type.
TYPE_UNSPECIFIED = 0;
// Indicates a sent message.
SENT = 1;
// Indicates a received message.
RECEIVED = 2;
}
// Type of MessageEvent. Indicates whether the message was sent or
// received.
Type type = 1;
// An identifier for the MessageEvent's message that can be used to match
// `SENT` and `RECEIVED` MessageEvents.
int64 id = 2;
// The number of uncompressed bytes sent or received.
int64 uncompressed_size_bytes = 3;
// The number of compressed bytes sent or received. If missing, the
// compressed size is assumed to be the same size as the uncompressed
// size.
int64 compressed_size_bytes = 4;
}
// The timestamp indicating the time the event occurred.
google.protobuf.Timestamp time = 1;
// A `TimeEvent` can contain either an `Annotation` object or a
// `MessageEvent` object, but not both.
oneof value {
// Text annotation with a set of attributes.
Annotation annotation = 2;
// An event describing a message sent/received between Spans.
MessageEvent message_event = 3;
}
}
// A collection of `TimeEvent`s. 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.
message TimeEvents {
// A collection of `TimeEvent`s.
repeated TimeEvent time_event = 1;
// The number of dropped annotations in all the included time events.
// If the value is 0, then no annotations were dropped.
int32 dropped_annotations_count = 2;
// The number of dropped message events in all the included time events.
// If the value is 0, then no message events were dropped.
int32 dropped_message_events_count = 3;
}
// 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.
message Link {
// The relationship of the current span relative to the linked span: child,
// parent, or unspecified.
enum Type {
// The relationship of the two spans is unknown.
TYPE_UNSPECIFIED = 0;
// The linked span is a child of the current span.
CHILD_LINKED_SPAN = 1;
// The linked span is a parent of the current span.
PARENT_LINKED_SPAN = 2;
}
// The `[TRACE_ID]` for a trace within a project.
string trace_id = 1;
// The `[SPAN_ID]` for a span within a trace.
string span_id = 2;
// The relationship of the current span relative to the linked span.
Type type = 3;
// A set of attributes on the link. Up to 32 attributes can be
// specified per link.
Attributes attributes = 4;
}
// A collection of links, which are references from this span to a span
// in the same or different trace.
message Links {
// A collection of links.
repeated Link link = 1;
// The number of dropped links after the maximum size was enforced. If
// this value is 0, then no links were dropped.
int32 dropped_links_count = 2;
}
// Type of span. Can be used to specify additional relationships between spans
// in addition to a parent/child relationship.
enum SpanKind {
// Unspecified. Do NOT use as default.
// Implementations MAY assume SpanKind.INTERNAL to be default.
SPAN_KIND_UNSPECIFIED = 0;
// Indicates that the span is used internally. Default value.
INTERNAL = 1;
// Indicates that the span covers server-side handling of an RPC or other
// remote network request.
SERVER = 2;
// Indicates that the span covers the client-side wrapper around an RPC or
// other remote request.
CLIENT = 3;
// Indicates that the span describes producer sending a message to a broker.
// Unlike client and server, there is no direct critical path latency
// relationship between producer and consumer spans (e.g. publishing a
// message to a pubsub service).
PRODUCER = 4;
// Indicates that the span describes consumer receiving a message from a
// broker. Unlike client and server, there is no direct critical path
// latency relationship between producer and consumer spans (e.g. receiving
// a message from a pubsub service subscription).
CONSUMER = 5;
}
// Required. The resource name of the span in the following format:
//
// * `projects/[PROJECT_ID]/traces/[TRACE_ID]/spans/[SPAN_ID]`
//
// `[TRACE_ID]` is a unique identifier for a trace within a project;
// it is a 32-character hexadecimal encoding of a 16-byte array. It should
// not be zero.
//
// `[SPAN_ID]` is a unique identifier for a span within a trace; it
// is a 16-character hexadecimal encoding of an 8-byte array. It should not
// be zero.
// .
string name = 1 [(google.api.field_behavior) = REQUIRED];
// Required. The `[SPAN_ID]` portion of the span's resource name.
string span_id = 2 [(google.api.field_behavior) = REQUIRED];
// The `[SPAN_ID]` of this span's parent span. If this is a root span,
// then this field must be empty.
string parent_span_id = 3;
// Required. A description of the span's operation (up to 128 bytes).
// Cloud Trace displays the description in the
// Cloud console.
// For example, the display 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 within an application and at the same call point.
// This makes it easier to correlate spans in different traces.
TruncatableString display_name = 4 [(google.api.field_behavior) = REQUIRED];
// Required. 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.
google.protobuf.Timestamp start_time = 5
[(google.api.field_behavior) = REQUIRED];
// Required. 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.
google.protobuf.Timestamp end_time = 6
[(google.api.field_behavior) = REQUIRED];
// A set of attributes on the span. You can have up to 32 attributes per
// span.
Attributes attributes = 7;
// Stack trace captured at the start of the span.
StackTrace stack_trace = 8;
// A set of time events. You can have up to 32 annotations and 128 message
// events per span.
TimeEvents time_events = 9;
// Links associated with the span. You can have up to 128 links per Span.
Links links = 10;
// Optional. The final status for this span.
google.rpc.Status status = 11 [(google.api.field_behavior) = OPTIONAL];
// Optional. Set this parameter to indicate whether this span is in
// the same process as its parent. If you do not set this parameter,
// Trace is unable to take advantage of this helpful information.
google.protobuf.BoolValue same_process_as_parent_span = 12
[(google.api.field_behavior) = OPTIONAL];
// Optional. The number of child spans that were generated while this span
// was active. If set, allows implementation to detect missing child spans.
google.protobuf.Int32Value child_span_count = 13
[(google.api.field_behavior) = OPTIONAL];
// Optional. 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 an RPC call.
SpanKind span_kind = 14 [(google.api.field_behavior) = OPTIONAL];
}
// The allowed types for `[VALUE]` in a `[KEY]:[VALUE]` attribute.
message AttributeValue {
// The type of the value.
oneof value {
// A string up to 256 bytes long.
TruncatableString string_value = 1;
// A 64-bit signed integer.
int64 int_value = 2;
// A Boolean value represented by `true` or `false`.
bool bool_value = 3;
}
}
// A call stack appearing in a trace.
message StackTrace {
// Represents a single stack frame in a stack trace.
message StackFrame {
// The fully-qualified name that uniquely identifies the function or
// method that is active in this frame (up to 1024 bytes).
TruncatableString function_name = 1;
// An un-mangled function name, if `function_name` is mangled.
// To get information about name mangling, run
// [this search](https://www.google.com/search?q=cxx+name+mangling).
// The name can be fully-qualified (up to 1024 bytes).
TruncatableString original_function_name = 2;
// The name of the source file where the function call appears (up to 256
// bytes).
TruncatableString file_name = 3;
// The line number in `file_name` where the function call appears.
int64 line_number = 4;
// The column number where the function call appears, if available.
// This is important in JavaScript because of its anonymous functions.
int64 column_number = 5;
// The binary module from where the code was loaded.
Module load_module = 6;
// The version of the deployed source code (up to 128 bytes).
TruncatableString source_version = 7;
}
// A collection of stack frames, which can be truncated.
message StackFrames {
// Stack frames in this call stack.
repeated StackFrame frame = 1;
// 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.
int32 dropped_frames_count = 2;
}
// Stack frames in this stack trace. A maximum of 128 frames are allowed.
StackFrames stack_frames = 1;
// 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 the
// `stackFrame` content and a value in `stackTraceHashId`.
//
// Subsequent spans within the same request can refer
// to that stack trace by only setting `stackTraceHashId`.
int64 stack_trace_hash_id = 2;
}
// Binary module.
message Module {
// For example: main binary, kernel modules, and dynamic libraries
// such as libc.so, sharedlib.so (up to 256 bytes).
TruncatableString module = 1;
// A unique identifier for the module, usually a hash of its
// contents (up to 128 bytes).
TruncatableString build_id = 2;
}
// Represents a string that might be shortened to a specified length.
message TruncatableString {
// The shortened string. For example, if the original string is 500
// bytes long and the limit of the string is 128 bytes, then
// `value` contains the first 128 bytes of the 500-byte string.
//
// Truncation always happens on a UTF8 character boundary. If there
// are multi-byte characters in the string, then the length of the
// shortened string might be less than the size limit.
string value = 1;
// The number of bytes removed from the original string. If this
// value is 0, then the string was not shortened.
int32 truncated_byte_count = 2;
}