Regenerate ocagent proto files (#456)

Author: mayurkale22

packages/opencensus-exporter-ocagent/src/protos/opencensus/proto/agent/common/v1/common.proto

@@ -27,17 +27,20 @@ option java_outer_classname = "CommonProto";
 
 option go_package = "github.com/census-instrumentation/opencensus-proto/gen-go/agent/common/v1";
 
-// Identifier metadata of the Node that connects to OpenCensus Agent.
+option ruby_package = "OpenCensus.Proto.Agent.Common.V1";
+
+// Identifier metadata of the Node that produces the span or tracing data.
+// Note, this is not the metadata about the Node or service that is described by associated spans.
 // In the future we plan to extend the identifier proto definition to support
-// additional information (e.g cloud id, monitored resource, etc.)
+// additional information (e.g cloud id, etc.)
 message Node {
   // Identifier that uniquely identifies a process within a VM/container.
   ProcessIdentifier identifier = 1;
 
-  // Information on the OpenCensus Library who initiates the stream.
+  // Information on the OpenCensus Library that initiates the stream.
   LibraryInfo library_info = 2;
 
-  // Additional informantion on service.
+  // Additional information on service.
   ServiceInfo service_info = 3;
 
   // Additional attributes.
@@ -59,8 +62,6 @@ message ProcessIdentifier {
 
   // Start time of this ProcessIdentifier. Represented in epoch time.
   google.protobuf.Timestamp start_timestamp = 3;
-
-  // TODO(songya): Add more fields in the future as needed.
 }
 
 // Information on OpenCensus Library.

packages/opencensus-exporter-ocagent/src/protos/opencensus/proto/agent/trace/v1/trace_service.proto

@@ -20,6 +20,7 @@ syntax = "proto3";
 package opencensus.proto.agent.trace.v1;
 
 import "opencensus/proto/agent/common/v1/common.proto";
+import "opencensus/proto/resource/v1/resource.proto";
 import "opencensus/proto/trace/v1/trace.proto";
 import "opencensus/proto/trace/v1/trace_config.proto";
 
@@ -29,38 +30,57 @@ option java_outer_classname = "TraceServiceProto";
 
 option go_package = "github.com/census-instrumentation/opencensus-proto/gen-go/agent/trace/v1";
 
+option ruby_package = "OpenCensus.Proto.Agent.Trace.V1";
+
+// Service that can be used to push spans and configs between one Application
+// instrumented with OpenCensus and an agent, or between an agent and a
+// central collector or config service (in this case spans and configs are
+// sent/received to/from multiple Applications).
 service TraceService {
-  // After initialization, this RPC must be kept alive for the
-  // entire life of the application. The agent pushes configs
-  // down to applications via a stream.
+  // After initialization, this RPC must be kept alive for the entire life of
+  // the application. The agent pushes configs down to applications via a
+  // stream.
   rpc Config(stream CurrentLibraryConfig) returns (stream UpdatedLibraryConfig) {}
 
-  // Allows applications to send spans to the agent.
   // For performance reasons, it is recommended to keep this RPC
   // alive for the entire life of the application.
   rpc Export(stream ExportTraceServiceRequest) returns (stream ExportTraceServiceResponse) {}
 }
 
 message CurrentLibraryConfig {
-  // Identifier data effectively is a structured metadata.
-  // This is required only in the first message on the stream.
+  // This is required only in the first message on the stream or if the
+  // previous sent CurrentLibraryConfig message has a different Node (e.g.
+  // when the same RPC is used to configure multiple Applications).
   opencensus.proto.agent.common.v1.Node node = 1;
 
   // Current configuration.
   opencensus.proto.trace.v1.TraceConfig config = 2;
 }
 
 message UpdatedLibraryConfig {
+  // This field is ignored when the RPC is used to configure only one Application.
+  // This is required only in the first message on the stream or if the
+  // previous sent UpdatedLibraryConfig message has a different Node.
+  opencensus.proto.agent.common.v1.Node node = 1;
+
   // Requested updated configuration.
   opencensus.proto.trace.v1.TraceConfig config = 2;
 }
 
 message ExportTraceServiceRequest {
-  // Identifier data effectively is a structured metadata.
-  // This is required only in the first message on the stream.
+  // This is required only in the first message on the stream or if the
+  // previous sent ExportTraceServiceRequest message has a different Node (e.g.
+  // when the same RPC is used to send Spans from multiple Applications).
   opencensus.proto.agent.common.v1.Node node = 1;
 
+  // A list of Spans that belong to the last received Node.
   repeated opencensus.proto.trace.v1.Span spans = 2;
+
+  // The resource for the spans in this message that do not have an explicit
+  // resource set.
+  // If unset, the most recently set resource in the RPC stream applies. It is
+  // valid to never be set within a stream, e.g. when no resource info is known.
+  opencensus.proto.resource.v1.Resource resource = 3;
 }
 
 message ExportTraceServiceResponse {

packages/opencensus-exporter-ocagent/src/protos/opencensus/proto/resource/v1/resource.proto

@@ -0,0 +1,35 @@
+// Copyright 2018, 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.
+
+syntax = "proto3";
+
+package opencensus.proto.resource.v1;
+
+option go_package = "github.com/census-instrumentation/opencensus-proto/gen-go/resource/v1";
+
+option java_multiple_files = true;
+option java_package = "io.opencensus.proto.resource.v1";
+option java_outer_classname = "ResourceProto";
+
+option ruby_package = "OpenCensus.Proto.Resource.V1";
+
+// Resource information.
+message Resource {
+
+  // Type identifier for the resource.
+  string type = 1;
+
+  // Set of labels that describe the resource.
+  map<string,string> labels = 2;
+}

packages/opencensus-exporter-ocagent/src/protos/opencensus/proto/trace/v1/trace.proto

@@ -16,6 +16,7 @@ syntax = "proto3";
 
 package opencensus.proto.trace.v1;
 
+import "opencensus/proto/resource/v1/resource.proto";
 import "google/protobuf/timestamp.proto";
 import "google/protobuf/wrappers.proto";
 
@@ -25,24 +26,35 @@ option java_outer_classname = "TraceProto";
 
 option go_package = "github.com/census-instrumentation/opencensus-proto/gen-go/trace/v1";
 
+option ruby_package = "OpenCensus.Proto.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.
+// The next id is 17.
 // 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 +94,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,29 +118,43 @@ 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
   // the local machine where the span execution starts. On the server side, this
   // is the time when the server's application handler starts running.
+  //
+  // This field is semantically required. When not set on receive -
+  // receiver should set it to the value of end_time field if it was
+  // set. Or to the current time if neither was set. It is important to
+  // keep end_time > start_time for consistency.
+  //
+  // This field is required.
   google.protobuf.Timestamp start_time = 5;
 
   // 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.
+  //
+  // This field is semantically required. When not set on receive -
+  // receiver should set it to start_time value. It is important to
+  // keep end_time > start_time for consistency.
+  //
+  // This field is required.
   google.protobuf.Timestamp end_time = 6;
 
   // 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<string, AttributeValue> attribute_map = 1;
 
     // The number of attributes that were discarded. Attributes can be discarded
@@ -217,12 +248,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,
@@ -255,15 +285,24 @@ message Span {
     int32 dropped_links_count = 2;
   }
 
-  // The inclued links.
+  // The included links.
   Links links = 10;
 
-  // An optional final status for this span.
+  // An optional final status for this span. Semantically when Status
+  // wasn't set it is means span ended without errors and assume
+  // Status.Ok (code = 0).
   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.
+  // An optional resource that is associated with this span. If not set, this span
+  // should be part of a batch that does include the resource information, unless resource
+  // information is unknown.
+  opencensus.proto.resource.v1.Resource resource = 16;
+
+  // 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
@@ -277,7 +316,8 @@ message Span {
 // [google.rpc.Status](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto),
 // which is used by [gRPC](https://github.com/grpc).
 message Status {
-  // The status code.
+  // The status code. This is optional field. It is safe to assume 0 (OK)
+  // when not set.
   int32 code = 1;
 
   // A developer-facing error message, which should be in English.
@@ -294,6 +334,8 @@ message AttributeValue {
     int64 int_value = 2;
     // A Boolean value represented by `true` or `false`.
     bool bool_value = 3;
+    // A double value.
+    double double_value = 4;
   }
 }
 

packages/opencensus-exporter-ocagent/src/protos/opencensus/proto/trace/v1/trace_config.proto

@@ -22,7 +22,10 @@ option java_outer_classname = "TraceConfigProto";
 
 option go_package = "github.com/census-instrumentation/opencensus-proto/gen-go/trace/v1";
 
-// Global configuration of the trace service.
+option ruby_package = "OpenCensus.Proto.Trace.V1";
+
+// Global configuration of the trace service. All fields must be specified, or
+// the default (zero) values will be used for each type.
 message TraceConfig {
 
   // The global default sampler used to make decisions on span sampling.
@@ -34,7 +37,17 @@ message TraceConfig {
     RateLimitingSampler rate_limiting_sampler = 3;
   }
 
-  // TODO(songya): add more fields.
+  // The global default max number of attributes per span.
+  int64 max_number_of_attributes = 4;
+
+  // The global default max number of annotation events per span.
+  int64 max_number_of_annotations = 5;
+
+  // The global default max number of message events per span.
+  int64 max_number_of_message_events = 6;
+
+  // The global default max number of link entries per span.
+  int64 max_number_of_links = 7;
 }
 
 // Sampler that tries to uniformly sample traces with a given probability.
@@ -45,12 +58,19 @@ message ProbabilitySampler {
   double samplingProbability = 1;
 }
 
-// Sampler that makes a constant decision (either always "yes" or always "no")
-// on span sampling.
+// Sampler that always makes a constant decision on span sampling.
 message ConstantSampler {
 
-  // Whether spans should be always sampled, or never sampled.
-  bool decision = 1;
+  // How spans should be sampled:
+  // - Always off
+  // - Always on
+  // - Always follow the parent Span's decision (off if no parent).
+  enum ConstantDecision {
+    ALWAYS_OFF = 0;
+    ALWAYS_ON = 1;
+    ALWAYS_PARENT = 2;
+  }
+  ConstantDecision decision = 1;
 }
 
 // Sampler that tries to sample with a rate per time window.