diff --git a/README.md b/README.md index 8b13789..7b12932 100644 --- a/README.md +++ b/README.md @@ -1 +1 @@ - +# Language Independent Interface Types For OpenTelemetry diff --git a/src/opentelemetry/proto/agent/README.md b/src/opentelemetry/proto/agent/README.md new file mode 100644 index 0000000..c54b9bc --- /dev/null +++ b/src/opentelemetry/proto/agent/README.md @@ -0,0 +1,10 @@ +# OpenTelemetry Agent Proto + +This package describes the OpenTelemetry Agent protocol. + +## Packages + +1. `common` package contains the common messages shared between different services, such as +`Node`, `Service` and `Library` identifiers. +2. `trace` package contains the Trace Service protos. +3. `metrics` package contains the Metrics Service protos. \ No newline at end of file diff --git a/src/opentelemetry/proto/agent/common/v1/common.proto b/src/opentelemetry/proto/agent/common/v1/common.proto new file mode 100644 index 0000000..45cd8a4 --- /dev/null +++ b/src/opentelemetry/proto/agent/common/v1/common.proto @@ -0,0 +1,96 @@ +// Copyright 2019, OpenTelemetry 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"; + +// NOTE: This proto is experimental and is subject to change at this point. +// Please do not use it at the moment. + +package opentelemetry.proto.agent.common.v1; + +import "google/protobuf/timestamp.proto"; + +option java_multiple_files = true; +option java_package = "io.opentelemetry.proto.agent.common.v1"; +option java_outer_classname = "CommonProto"; + +// 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, etc.) +message Node { + // Identifier that uniquely identifies a process within a VM/container. + ProcessIdentifier identifier = 1; + + // Information on the OpenTelemetry Library that initiates the stream. + LibraryInfo library_info = 2; + + // Additional information on service. + ServiceInfo service_info = 3; + + // Additional attributes. + map attributes = 4; + + // TODO(songya): Add more identifiers in the future as needed, like cloud + // identifiers. +} + +// Identifier that uniquely identifies a process within a VM/container. +message ProcessIdentifier { + + // The host name. Usually refers to the machine/container name. + // For example: os.Hostname() in Go, socket.gethostname() in Python. + string host_name = 1; + + // Process id. + uint32 pid = 2; + + // Start time of this ProcessIdentifier. Represented in epoch time. + google.protobuf.Timestamp start_timestamp = 3; +} + +// Information on OpenTelemetry Library. +message LibraryInfo { + + enum Language { + LANGUAGE_UNSPECIFIED = 0; + CPP = 1; + C_SHARP = 2; + ERLANG = 3; + GO_LANG = 4; + JAVA = 5; + NODE_JS = 6; + PHP = 7; + PYTHON = 8; + RUBY = 9; + } + + // Language of OpenTelemetry Library. + Language language = 1; + + // Version of Agent exporter of Library. + string exporter_version = 2; + + // Version of OpenTelemetry Library. + string core_library_version = 3; +} + +// Additional service information. +message ServiceInfo { + + // Name of the service. + string name = 1; + + // TODO(songya): add more fields as needed. +} diff --git a/src/opentelemetry/proto/agent/metrics/v1/metrics_service.proto b/src/opentelemetry/proto/agent/metrics/v1/metrics_service.proto new file mode 100644 index 0000000..f6c3f36 --- /dev/null +++ b/src/opentelemetry/proto/agent/metrics/v1/metrics_service.proto @@ -0,0 +1,54 @@ +// Copyright 2019, OpenTelemetry 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 opentelemetry.proto.agent.metrics.v1; + +import "agent/common/v1/common.proto"; +import "metrics/v1/metrics.proto"; +import "resource/v1/resource.proto"; + +option java_multiple_files = true; +option java_package = "io.opentelemetry.proto.agent.metrics.v1"; +option java_outer_classname = "MetricsServiceProto"; + +// Service that can be used to push metrics between one Application +// instrumented with OpenTelemetry and an agent, or between an agent and a +// central collector. +service MetricsService { + // For performance reasons, it is recommended to keep this RPC + // alive for the entire life of the application. + rpc Export(stream ExportMetricsServiceRequest) returns (stream ExportMetricsServiceResponse) {} +} + +message ExportMetricsServiceRequest { + // This is required only in the first message on the stream or if the + // previous sent ExportMetricsServiceRequest message has a different Node (e.g. + // when the same RPC is used to send Metrics from multiple Applications). + opentelemetry.proto.agent.common.v1.Node node = 1; + + // A list of metrics that belong to the last received Node. + repeated opentelemetry.proto.metrics.v1.Metric metrics = 2; + + // The resource for the metrics 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 + // at all or when all sent metrics have an explicit resource set. + opentelemetry.proto.resource.v1.Resource resource = 3; +} + +message ExportMetricsServiceResponse { +} diff --git a/src/opentelemetry/proto/agent/trace/v1/trace_service.proto b/src/opentelemetry/proto/agent/trace/v1/trace_service.proto new file mode 100644 index 0000000..75d77a0 --- /dev/null +++ b/src/opentelemetry/proto/agent/trace/v1/trace_service.proto @@ -0,0 +1,83 @@ +// Copyright 2019, OpenTelemetry 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"; + +// NOTE: This proto is experimental and is subject to change at this point. +// Please do not use it at the moment. + +package opentelemetry.proto.agent.trace.v1; + +import "agent/common/v1/common.proto"; +import "resource/v1/resource.proto"; +import "trace/v1/trace.proto"; +import "trace/v1/trace_config.proto"; + +option java_multiple_files = true; +option java_package = "io.opentelemetry.proto.agent.trace.v1"; +option java_outer_classname = "TraceServiceProto"; + +// Service that can be used to push spans and configs between one Application +// instrumented with OpenTelemetry 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. + rpc Config(stream CurrentLibraryConfig) returns (stream UpdatedLibraryConfig) {} + + // 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 { + // 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). + opentelemetry.proto.agent.common.v1.Node node = 1; + + // Current configuration. + opentelemetry.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. + opentelemetry.proto.agent.common.v1.Node node = 1; + + // Requested updated configuration. + opentelemetry.proto.trace.v1.TraceConfig config = 2; +} + +message ExportTraceServiceRequest { + // 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). + opentelemetry.proto.agent.common.v1.Node node = 1; + + // A list of Spans that belong to the last received Node. + repeated opentelemetry.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. + opentelemetry.proto.resource.v1.Resource resource = 3; +} + +message ExportTraceServiceResponse { +} diff --git a/src/opentelemetry/proto/agent/trace/v1/trace_service_http.yaml b/src/opentelemetry/proto/agent/trace/v1/trace_service_http.yaml new file mode 100644 index 0000000..8a8b86d --- /dev/null +++ b/src/opentelemetry/proto/agent/trace/v1/trace_service_http.yaml @@ -0,0 +1,12 @@ +# This is an API configuration to generate an HTTP/JSON -> gRPC gateway for the +# OpenTelemetry service using github.com/grpc-ecosystem/grpc-gateway. +type: google.api.Service +config_version: 3 +http: + rules: + - selector: opentelemetry.proto.agent.trace.v1.TraceService.Export + post: /v1/trace + body: "*" + - selector: opentelemetry.proto.agent.metrics.v1.MetricsService.Export + post: /v1/trace + body: "*" \ No newline at end of file diff --git a/src/opentelemetry/proto/metrics/v1/metrics.proto b/src/opentelemetry/proto/metrics/v1/metrics.proto new file mode 100644 index 0000000..1580a9b --- /dev/null +++ b/src/opentelemetry/proto/metrics/v1/metrics.proto @@ -0,0 +1,274 @@ +// Copyright 2019, OpenTelemetry 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 opentelemetry.proto.metrics.v1; + +import "google/protobuf/timestamp.proto"; +import "google/protobuf/wrappers.proto"; +import "resource/v1/resource.proto"; + +option java_multiple_files = true; +option java_package = "io.opentelemetry.proto.metrics.v1"; +option java_outer_classname = "MetricsProto"; + +// Defines a Metric which has one or more timeseries. +message Metric { + // The descriptor of the Metric. + MetricDescriptor metric_descriptor = 1; + + // One or more timeseries for a single metric, where each timeseries has + // one or more points. + repeated TimeSeries timeseries = 2; + + // The resource for the metric. If unset, it may be set to a default value + // provided for a sequence of messages in an RPC stream. + opentelemetry.proto.resource.v1.Resource resource = 3; +} + +// Defines a metric type and its schema. +message MetricDescriptor { + // The metric type, including its DNS name prefix. It must be unique. + string name = 1; + + // A detailed description of the metric, which can be used in documentation. + string description = 2; + + // The unit in which the metric value is reported. Follows the format + // described by http://unitsofmeasure.org/ucum.html. + string unit = 3; + + // The kind of metric. It describes how the data is reported. + // + // A gauge is an instantaneous measurement of a value. + // + // A counter/cumulative measurement is a value accumulated over a time + // interval. In a time series, cumulative measurements should have the same + // start time, increasing values and increasing end times, until an event + // resets the cumulative value to zero and sets a new start time for the + // following points. + enum Type { + // Do not use this default value. + UNSPECIFIED = 0; + + // Integer gauge. The value can go both up and down. + GAUGE_INT64 = 1; + + // Floating point gauge. The value can go both up and down. + GAUGE_DOUBLE = 2; + + // Histogram gauge measurement. The count and sum can go both up and + // down. Recorded values are always >= 0. + // Used in scenarios like a snapshot of time the current items in a queue + // have spent there. + GAUGE_HISTOGRAM = 3; + + // Integer counter measurement. The value cannot decrease, if resets + // then the start_time should also be reset. + COUNTER_INT64 = 4; + + // Floating point counter measurement. The value cannot decrease, if + // resets then the start_time should also be reset. Recorded values are + // always >= 0. + COUNTER_DOUBLE = 5; + + // Histogram cumulative measurement. The count and sum cannot decrease, + // if resets then the start_time should also be reset. + CUMULATIVE_HISTOGRAM = 6; + + // Some frameworks implemented Histograms as a summary of observations + // (usually things like request durations and response sizes). While it + // also provides a total count of observations and a sum of all observed + // values, it calculates configurable percentiles over a sliding time + // window. This is not recommended, since it cannot be aggregated. + SUMMARY = 7; + } + Type type = 4; + + // The label keys associated with the metric descriptor. + repeated LabelKey label_keys = 5; +} + +// Defines a label key associated with a metric descriptor. +message LabelKey { + // The key for the label. + string key = 1; + + // A human-readable description of what this label key represents. + string description = 2; +} + +// A collection of data points that describes the time-varying values +// of a metric. +message TimeSeries { + // The set of label values that uniquely identify this timeseries. Applies to + // all points. The order of label values must match that of label keys in the + // metric descriptor. + repeated LabelValue label_values = 1; + + // The data points of this timeseries. Point.value type MUST match the + // MetricDescriptor.type. + repeated Point points = 2; +} + +message LabelValue { + // The value for the label. + string value = 1; + // If false the value field is ignored and considered not set. + // This is used to differentiate a missing label from an empty string. + bool has_value = 2; +} + +// A timestamped measurement. +message Point { + // Must be present for counter/cumulative metrics. The time when the + // cumulative value was reset to zero. The cumulative value is over the time + // interval (start_timestamp, timestamp]. If not specified, the backend can + // use the previous recorded value. + google.protobuf.Timestamp start_timestamp = 1; + + // The moment when this point was recorded. + // If not specified, the timestamp will be decided by the backend. + google.protobuf.Timestamp timestamp = 2; + + // The actual point value. + oneof value { + // A 64-bit integer. + int64 int64_value = 3; + + // A 64-bit double-precision floating-point number. + double double_value = 4; + + // A histogram value. + HistogramValue histogram_value = 5; + + // A summary value. This is not recommended, since it cannot be aggregated. + SummaryValue summary_value = 6; + } +} + +// Histogram contains summary statistics for a population of values. It may +// optionally contain the distribution of those values across a set of buckets. +message HistogramValue { + // The number of values in the population. Must be non-negative. This value + // must equal the sum of the values in bucket_counts if a histogram is + // provided. + int64 count = 1; + + // The sum of the values in the population. If count is zero then this field + // must be zero. + double sum = 2; + + // A Histogram may optionally contain the distribution of the values in the + // population. The bucket boundaries are described by BucketOptions. + message BucketOptions { + oneof type { + // Bucket with explicit bounds. + Explicit explicit = 1; + } + + // Specifies a set of buckets with arbitrary upper-bounds. + // This defines size(bounds) + 1 (= N) buckets. The boundaries for bucket + // index i are: + // + // [0, bucket_bounds[i]) for i == 0 + // [bucket_bounds[i-1], bucket_bounds[i]) for 0 < i < N-1 + // [bucket_bounds[i], +infinity) for i == N-1 + message Explicit { + // The values must be strictly increasing and > 0. + repeated double bounds = 1; + } + + // TODO: If OpenMetrics decides to support (a, b] intervals we should add + // support for these by defining a boolean value here which decides what + // type of intervals to use. + } + + // Don't change bucket boundaries within a TimeSeries if your backend doesn't + // support this. + BucketOptions bucket_options = 3; + + message Bucket { + // The number of values in each bucket of the histogram, as described in + // bucket_bounds. + int64 count = 1; + + // Exemplars are example points that may be used to annotate aggregated + // Histogram values. They are metadata that gives information about a + // particular value added to a Histogram bucket. + message Exemplar { + // Value of the exemplar point. It determines which bucket the exemplar + // belongs to. + double value = 1; + + // The observation (sampling) time of the above value. + google.protobuf.Timestamp timestamp = 2; + + // Contextual information about the example value. + map attachments = 3; + } + + // Exemplars are example points that may be used to annotate aggregated + // Histogram values. + Exemplar exemplar = 2; + } + + // The sum of the values in the Bucket counts must equal the value in the + // count field of the histogram. + repeated Bucket buckets = 4; +} + +// The start_timestamp only applies to the count and sum in the SummaryValue. +message SummaryValue { + // The total number of recorded values since start_time. Optional since + // some systems don't expose this. + google.protobuf.Int64Value count = 1; + + // The total sum of recorded values since start_time. Optional since some + // systems don't expose this. If count is zero then this field must be zero. + // This field must be unset if the sum is not available. + google.protobuf.DoubleValue sum = 2; + + // The values in this message can be reset at arbitrary unknown times, with + // the requirement that all of them are reset at the same time. + message Snapshot { + // The number of values in the snapshot. Optional since some systems don't + // expose this. + google.protobuf.Int64Value count = 1; + + // The sum of values in the snapshot. Optional since some systems don't + // expose this. If count is zero then this field must be zero or not set + // (if not supported). + google.protobuf.DoubleValue sum = 2; + + // Represents the value at a given percentile of a distribution. + message ValueAtPercentile { + // The percentile of a distribution. Must be in the interval + // (0.0, 100.0]. + double percentile = 1; + + // The value at the given percentile of a distribution. + double value = 2; + } + + // A list of values at different percentiles of the distribution calculated + // from the current snapshot. The percentiles must be strictly increasing. + repeated ValueAtPercentile percentile_values = 3; + } + + // Values calculated over an arbitrary time window. + Snapshot snapshot = 3; +} + diff --git a/src/opentelemetry/proto/resource/v1/resource.proto b/src/opentelemetry/proto/resource/v1/resource.proto new file mode 100644 index 0000000..2200208 --- /dev/null +++ b/src/opentelemetry/proto/resource/v1/resource.proto @@ -0,0 +1,27 @@ +// Copyright 2019, OpenTelemetry 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 opentelemetry.proto.resource.v1; + +option java_multiple_files = true; +option java_package = "io.opentelemetry.proto.resource.v1"; +option java_outer_classname = "ResourceProto"; + +// Resource information. +message Resource { + // Set of labels that describe the resource. + map labels = 1; +} diff --git a/src/opentelemetry/proto/trace/v1/trace.proto b/src/opentelemetry/proto/trace/v1/trace.proto new file mode 100644 index 0000000..3a586da --- /dev/null +++ b/src/opentelemetry/proto/trace/v1/trace.proto @@ -0,0 +1,294 @@ +// Copyright 2019, OpenTelemetry 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 opentelemetry.proto.trace.v1; + +import "google/protobuf/timestamp.proto"; +import "google/protobuf/wrappers.proto"; +import "resource/v1/resource.proto"; + +option java_multiple_files = true; +option java_package = "io.opentelemetry.proto.trace.v1"; +option java_outer_classname = "TraceProto"; + +// A span represents a single operation within a trace. Spans can be +// 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. +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. 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. 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; + + // This field conveys information about request position in multiple distributed tracing graphs. + // It is a list of Tracestate.Entry with a maximum of 32 members in the list. + // + // See the https://github.com/w3c/distributed-tracing for more details about this field. + message Tracestate { + message Entry { + // The key must begin with a lowercase letter, and can only contain + // lowercase letters 'a'-'z', digits '0'-'9', underscores '_', dashes + // '-', asterisks '*', and forward slashes '/'. + string key = 1; + + // The value is opaque string up to 256 characters printable ASCII + // RFC0020 characters (i.e., the range 0x20 to 0x7E) except ',' and '='. + // Note that this also excludes tabs, newlines, carriage returns, etc. + string value = 2; + } + + // A list of entries that represent the Tracestate. + repeated Entry entries = 1; + } + + // The Tracestate on the span. + Tracestate tracestate = 3; + + // The `span_id` of this span's parent span. If this is a root span, then this + // field must be empty. The ID is an 8-byte array. + bytes parent_span_id = 4; + + // 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. + opentelemetry.proto.resource.v1.Resource resource = 5; + + // A description of the span's operation. + // + // For example, the 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 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 = 6; + + // 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. + SERVER = 1; + + // Indicates that the span covers the client-side wrapper around an RPC or + // other remote request. + CLIENT = 2; + } + + // 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 queueing latency associated with the span. + SpanKind kind = 7; + + // 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 = 8; + + // 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 = 9; + + // 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, 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: + // + // "/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 + // because their keys are too long or because there are too many attributes. + // If this value is 0, then no attributes were dropped. + int32 dropped_attributes_count = 2; + } + + // A set of attributes on the span. + Attributes attributes = 10; + + + // A time-stamped event in the Span. + message TimedEvent { + // The time the event occurred. + google.protobuf.Timestamp time = 1; + + // A text annotation with a set of attributes. + message Event { + // A user-supplied name describing the event. + TruncatableString name = 1; + + // A set of attributes on the event. + Attributes attributes = 2; + } + + // The event. + Event event = 2; + } + + // 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 TimedEvents { + // A collection of `TimedEvent`s. + repeated TimedEvent timed_event = 1; + + // The number of dropped timed events. If the value is 0, then no events were dropped. + int32 dropped_timed_events_count = 2; + } + + // The included timed events. + TimedEvents time_events = 11; + + // 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 { + // 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 the linked span. The ID is an 8-byte array. + bytes span_id = 2; + + // The Tracestate associated with the link. + Tracestate tracestate = 3; + + // A set of attributes on the 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; + } + + // The included links. + Links links = 12; + + // 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 = 13; + + // 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 = 14; + + // An optional number of child spans that were generated while this span + // was active. If set, allows an implementation to detect missing child spans. + google.protobuf.UInt32Value child_span_count = 15; +} + +// The `Status` type defines a logical error model that is suitable for different +// programming environments, including REST APIs and RPC APIs. This proto's fields +// are a subset of those of +// [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. 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. + string message = 2; +} + +// The value of an 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 double value. + double double_value = 4; + } +} + +// A string that might be shortened to a specified length. +message TruncatableString { + // The shortened string. For example, if the original string was 500 bytes long and + // the limit of the string was 128 bytes, then this value contains the first 128 + // bytes of the 500-byte string. Note that truncation always happens on a + // character boundary, to ensure that a truncated string is still valid UTF-8. + // Because it may contain multi-byte characters, the size of the truncated string + // may be less than the truncation 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; +} diff --git a/src/opentelemetry/proto/trace/v1/trace_config.proto b/src/opentelemetry/proto/trace/v1/trace_config.proto new file mode 100644 index 0000000..467391c --- /dev/null +++ b/src/opentelemetry/proto/trace/v1/trace_config.proto @@ -0,0 +1,77 @@ +// Copyright 2019, OpenTelemetry 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 opentelemetry.proto.trace.v1; + +option java_multiple_files = true; +option java_package = "io.opentelemetry.proto.trace.v1"; +option java_outer_classname = "TraceConfigProto"; + +// 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. + oneof sampler { + ConstantSampler constant_sampler = 1; + + ProbabilitySampler probability_sampler = 2; + + RateLimitingSampler rate_limiting_sampler = 3; + } + + // 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_timed_events= 5; + + // The global default max number of attributes per timed event. + int64 max_number_of_attributes_per_timed_event = 6; + + // The global default max number of link entries per span. + int64 max_number_of_links = 7; + + // The global default max number of attributes per span. + int64 max_number_of_attributes_per_link = 8; +} + +// Sampler that always makes a constant decision on span sampling. +message ConstantSampler { + // 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 uniformly sample traces with a given probability. +// The probability of sampling a trace is equal to that of the specified probability. +message ProbabilitySampler { + // The desired probability of sampling. Must be within [0.0, 1.0]. + double samplingProbability = 1; +} + +// Sampler that tries to sample with a rate per time window. +message RateLimitingSampler { + // Rate per second. + int64 qps = 1; +}