| // Copyright 2016 Google Inc. | |
| // | |
| // 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.v1; | |
| import "google/api/annotations.proto"; | |
| import "google/protobuf/empty.proto"; | |
| import "google/protobuf/timestamp.proto"; | |
| option csharp_namespace = "Google.Cloud.Trace.V1"; | |
| option go_package = "google.golang.org/genproto/googleapis/devtools/cloudtrace/v1;cloudtrace"; | |
| option java_multiple_files = true; | |
| option java_outer_classname = "TraceProto"; | |
| option java_package = "com.google.devtools.cloudtrace.v1"; | |
| // This file describes an API for collecting and viewing traces and spans | |
| // within a trace. A Trace is a collection of spans corresponding to a single | |
| // operation or set of operations for an application. A span is an individual | |
| // timed event which forms a node of the trace tree. Spans for a single trace | |
| // may span multiple services. | |
| service TraceService { | |
| // Returns of a list of traces that match the specified filter conditions. | |
| rpc ListTraces(ListTracesRequest) returns (ListTracesResponse) { | |
| option (google.api.http) = { get: "/v1/projects/{project_id}/traces" }; | |
| } | |
| // Gets a single trace by its ID. | |
| rpc GetTrace(GetTraceRequest) returns (Trace) { | |
| option (google.api.http) = { get: "/v1/projects/{project_id}/traces/{trace_id}" }; | |
| } | |
| // Sends new traces to Stackdriver Trace or updates existing traces. If the ID | |
| // of a trace that you send matches that of an existing trace, any fields | |
| // in the existing trace and its spans are overwritten by the provided values, | |
| // and any new fields provided are merged with the existing trace data. If the | |
| // ID does not match, a new trace is created. | |
| rpc PatchTraces(PatchTracesRequest) returns (google.protobuf.Empty) { | |
| option (google.api.http) = { patch: "/v1/projects/{project_id}/traces" body: "traces" }; | |
| } | |
| } | |
| // A trace describes how long it takes for an application to perform an | |
| // operation. It consists of a set of spans, each of which represent a single | |
| // timed event within the operation. | |
| message Trace { | |
| // Project ID of the Cloud project where the trace data is stored. | |
| string project_id = 1; | |
| // Globally unique identifier for the trace. This identifier is a 128-bit | |
| // numeric value formatted as a 32-byte hex string. | |
| string trace_id = 2; | |
| // Collection of spans in the trace. | |
| repeated TraceSpan spans = 3; | |
| } | |
| // List of new or updated traces. | |
| message Traces { | |
| // List of traces. | |
| repeated Trace traces = 1; | |
| } | |
| // A span represents a single timed event within a trace. Spans can be nested | |
| // and form a trace tree. Often, a trace contains a root span that describes the | |
| // end-to-end latency of an operation and, optionally, one or more subspans for | |
| // its suboperations. Spans do not need to be contiguous. There may be gaps | |
| // between spans in a trace. | |
| message TraceSpan { | |
| // Type of span. Can be used to specify additional relationships between spans | |
| // in addition to a parent/child relationship. | |
| enum SpanKind { | |
| // Unspecified. | |
| SPAN_KIND_UNSPECIFIED = 0; | |
| // Indicates that the span covers server-side handling of an RPC or other | |
| // remote network request. | |
| RPC_SERVER = 1; | |
| // Indicates that the span covers the client-side wrapper around an RPC or | |
| // other remote request. | |
| RPC_CLIENT = 2; | |
| } | |
| // Identifier for the span. Must be a 64-bit integer other than 0 and | |
| // unique within a trace. | |
| fixed64 span_id = 1; | |
| // Distinguishes between spans generated in a particular context. For example, | |
| // two spans with the same name may be distinguished using `RPC_CLIENT` | |
| // and `RPC_SERVER` to identify queueing latency associated with the span. | |
| SpanKind kind = 2; | |
| // Name of the trace. The trace name is sanitized and displayed in the | |
| // Stackdriver Trace tool in the Google Developers Console. | |
| // The name may be a method name or some other per-call site name. | |
| // For the same executable and the same call point, a best practice is | |
| // to use a consistent name, which makes it easier to correlate | |
| // cross-trace spans. | |
| string name = 3; | |
| // Start time of the span in nanoseconds from the UNIX epoch. | |
| google.protobuf.Timestamp start_time = 4; | |
| // End time of the span in nanoseconds from the UNIX epoch. | |
| google.protobuf.Timestamp end_time = 5; | |
| // ID of the parent span, if any. Optional. | |
| fixed64 parent_span_id = 6; | |
| // Collection of labels associated with the span. | |
| map<string, string> labels = 7; | |
| } | |
| // The request message for the `ListTraces` method. All fields are required | |
| // unless specified. | |
| message ListTracesRequest { | |
| // Type of data returned for traces in the list. | |
| enum ViewType { | |
| // Default is `MINIMAL` if unspecified. | |
| VIEW_TYPE_UNSPECIFIED = 0; | |
| // Minimal view of the trace record that contains only the project | |
| // and trace IDs. | |
| MINIMAL = 1; | |
| // Root span view of the trace record that returns the root spans along | |
| // with the minimal trace data. | |
| ROOTSPAN = 2; | |
| // Complete view of the trace record that contains the actual trace data. | |
| // This is equivalent to calling the REST `get` or RPC `GetTrace` method | |
| // using the ID of each listed trace. | |
| COMPLETE = 3; | |
| } | |
| // ID of the Cloud project where the trace data is stored. | |
| string project_id = 1; | |
| // Type of data returned for traces in the list. Optional. Default is | |
| // `MINIMAL`. | |
| ViewType view = 2; | |
| // Maximum number of traces to return. If not specified or <= 0, the | |
| // implementation selects a reasonable value. The implementation may | |
| // return fewer traces than the requested page size. Optional. | |
| int32 page_size = 3; | |
| // Token identifying the page of results to return. If provided, use the | |
| // value of the `next_page_token` field from a previous request. Optional. | |
| string page_token = 4; | |
| // End of the time interval (inclusive) during which the trace data was | |
| // collected from the application. | |
| google.protobuf.Timestamp start_time = 5; | |
| // Start of the time interval (inclusive) during which the trace data was | |
| // collected from the application. | |
| google.protobuf.Timestamp end_time = 6; | |
| // An optional filter for the request. | |
| string filter = 7; | |
| // Field used to sort the returned traces. Optional. | |
| // Can be one of the following: | |
| // | |
| // * `trace_id` | |
| // * `name` (`name` field of root span in the trace) | |
| // * `duration` (difference between `end_time` and `start_time` fields of | |
| // the root span) | |
| // * `start` (`start_time` field of the root span) | |
| // | |
| // Descending order can be specified by appending `desc` to the sort field | |
| // (for example, `name desc`). | |
| // | |
| // Only one sort field is permitted. | |
| string order_by = 8; | |
| } | |
| // The response message for the `ListTraces` method. | |
| message ListTracesResponse { | |
| // List of trace records returned. | |
| repeated Trace traces = 1; | |
| // If defined, indicates that there are more traces that match the request | |
| // and that this value should be passed to the next request to continue | |
| // retrieving additional traces. | |
| string next_page_token = 2; | |
| } | |
| // The request message for the `GetTrace` method. | |
| message GetTraceRequest { | |
| // ID of the Cloud project where the trace data is stored. | |
| string project_id = 1; | |
| // ID of the trace to return. | |
| string trace_id = 2; | |
| } | |
| // The request message for the `PatchTraces` method. | |
| message PatchTracesRequest { | |
| // ID of the Cloud project where the trace data is stored. | |
| string project_id = 1; | |
| // The body of the message. | |
| Traces traces = 2; | |
| } |