From f66e425a93ca60ee49764bf97cbc3dd2efa97058 Mon Sep 17 00:00:00 2001 From: Ethan Bao Date: Mon, 26 Oct 2015 14:53:26 -0700 Subject: [PATCH] Import cloud trace proto. --- google/devtools/cloudtrace/v1/trace.proto | 216 ++++++++++++++++++++++ 1 file changed, 216 insertions(+) create mode 100644 google/devtools/cloudtrace/v1/trace.proto diff --git a/google/devtools/cloudtrace/v1/trace.proto b/google/devtools/cloudtrace/v1/trace.proto new file mode 100644 index 000000000..bd81c3f23 --- /dev/null +++ b/google/devtools/cloudtrace/v1/trace.proto @@ -0,0 +1,216 @@ +// Copyright (c) 2015, 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 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 Cloud 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. This identifier must be 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 + // Cloud 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 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; +}