From f1f2125e477f7ce81203e117a846788203f7f338 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Wed, 16 Jan 2019 14:23:47 -0800 Subject: [PATCH] Minor comments fixes (#160) * Minor fixes * Update trace.proto * addressed code review feedback --- src/opencensus/proto/trace/v1/trace.proto | 56 +++++++++++++++-------- 1 file changed, 36 insertions(+), 20 deletions(-) diff --git a/src/opencensus/proto/trace/v1/trace.proto b/src/opencensus/proto/trace/v1/trace.proto index 35cc5c6..b1ed544 100644 --- a/src/opencensus/proto/trace/v1/trace.proto +++ b/src/opencensus/proto/trace/v1/trace.proto @@ -26,23 +26,32 @@ option java_outer_classname = "TraceProto"; option go_package = "github.com/census-instrumentation/opencensus-proto/gen-go/trace/v1"; // 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. +// nested to form a trace tree. Spans may also be linked to other spans +// from the same or different trace. And form graphs. 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 16. // TODO(bdrutu): Add an example. message Span { // A unique identifier for a trace. All spans from the same trace share - // the same `trace_id`. The ID is a 16-byte array. + // the same `trace_id`. The ID is a 16-byte array. An ID with all zeroes + // is considered invalid. + // + // This field is semantically required. Receiver should generate new + // random trace_id if empty or invalid trace_id was received. // // This field is required. bytes trace_id = 1; // A unique identifier for a span within a trace, assigned when the span - // is created. The ID is an 8-byte array. + // is created. The ID is an 8-byte array. An ID with all zeroes is considered + // invalid. + // + // This field is semantically required. Receiver should generate new + // random span_id if empty or invalid span_id was received. // // This field is required. bytes span_id = 2; @@ -82,6 +91,11 @@ message Span { // 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 semantically required to be set to non-empty string. + // When null or empty string received - receiver may use string "name" + // as a replacement. There might be smarted algorithms implemented by + // receiver to fix the empty span name. + // // This field is required. TruncatableString name = 4; @@ -101,8 +115,8 @@ message Span { } // 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. + // two spans with the same name may be distinguished using `CLIENT` (caller) + // and `SERVER` (callee) to identify queueing latency associated with the span. SpanKind kind = 14; // The start time of the span. On the client side, this is the time kept by @@ -117,13 +131,14 @@ message Span { // A set of attributes, each with a key and a value. message Attributes { - // The set of attributes. The value can be a string, an integer, or the - // Boolean values `true` and `false`. For example: + // The set of attributes. The value can be a string, an integer, a double + // or the Boolean values `true` or `false`. Note, global attributes like + // server name can be set as tags using resource API. Examples of attributes: // - // "/instance_id": "my-instance" - // "/http/user_agent": "" + // "/http/user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36" // "/http/server_latency": 300 // "abc.com/myattribute": true + // "abc.com/score": 10.239 map attribute_map = 1; // The number of attributes that were discarded. Attributes can be discarded @@ -217,12 +232,11 @@ message Span { // where a single batch handler processes multiple requests from different // traces or when the handler receives a request from a different project. message Link { - // A unique identifier for a trace. All spans from the same trace share - // the same `trace_id`. The ID is a 16-byte array. + // A unique identifier of a trace that this linked span is part of. The ID is a + // 16-byte array. bytes trace_id = 1; - // A unique identifier for a span within a trace, assigned when the span - // is created. The ID is an 8-byte array. + // A unique identifier for the linked span. The ID is an 8-byte array. bytes span_id = 2; // The relationship of the current span relative to the linked span: child, @@ -261,9 +275,11 @@ message Span { // An optional final status for this span. Status status = 11; - // 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. + // 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. This flag is most commonly + // used to indicate the need to adjust time as clocks in different + // processes may not be synchronized. google.protobuf.BoolValue same_process_as_parent_span = 12; // An optional number of child spans that were generated while this span