From 17acb4ff3d8d869b8a145ad38e45669074ce6280 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Fri, 27 May 2022 13:34:50 -0400 Subject: [PATCH] Ensure enums are consistently declared Resolves https://github.com/open-telemetry/opentelemetry-proto/issues/363 The rules are: - Place enums outside the messages. - Prefix the enum value names with enum name, using underscores with uppercase. The changes in this PR should be backwards compatible (or allowed because they are in experimental parts): - For Binary Protobuf: the encoding does not use enum names anywhere on the wire. There are no changes on the wire at all. - For JSON Protobuf: - DataPointFlags and LogRecordFlags are not visible on the wire since they are just helper enums to be used in the code. - Moving SpanKind and StatusCode out of the message should not result in any changes on the wire. - ConstantDecision is experimental and we are free to break it. I would like someone to independently confirm my analysis to make sure this PR does not break anything on the wire (neither for binary nor for JSON). --- opentelemetry/proto/logs/v1/logs.proto | 4 +- opentelemetry/proto/metrics/v1/metrics.proto | 4 +- opentelemetry/proto/trace/v1/trace.proto | 84 +++++++++---------- .../proto/trace/v1/trace_config.proto | 11 +-- 4 files changed, 52 insertions(+), 51 deletions(-) diff --git a/opentelemetry/proto/logs/v1/logs.proto b/opentelemetry/proto/logs/v1/logs.proto index c524a96c2..0141a644f 100644 --- a/opentelemetry/proto/logs/v1/logs.proto +++ b/opentelemetry/proto/logs/v1/logs.proto @@ -151,8 +151,8 @@ enum SeverityNumber { // Masks for LogRecord.flags field. enum LogRecordFlags { - LOG_RECORD_FLAG_UNSPECIFIED = 0; - LOG_RECORD_FLAG_TRACE_FLAGS_MASK = 0x000000FF; + LOG_RECORD_FLAGS_UNSPECIFIED = 0; + LOG_RECORD_FLAGS_TRACE_FLAGS_MASK = 0x000000FF; } // A log record according to OpenTelemetry Log Data Model: diff --git a/opentelemetry/proto/metrics/v1/metrics.proto b/opentelemetry/proto/metrics/v1/metrics.proto index 4a59f92a1..d9c45a8b5 100644 --- a/opentelemetry/proto/metrics/v1/metrics.proto +++ b/opentelemetry/proto/metrics/v1/metrics.proto @@ -364,12 +364,12 @@ enum AggregationTemporality { // (point.flags & FLAG_NO_RECORDED_VALUE) == FLAG_NO_RECORDED_VALUE // enum DataPointFlags { - FLAG_NONE = 0; + DATA_POINTS_FLAG_NONE = 0; // This DataPoint is valid but has no recorded value. This value // SHOULD be used to reflect explicitly missing data in a series, as // for an equivalent to the Prometheus "staleness marker". - FLAG_NO_RECORDED_VALUE = 1; + DATA_POINTS_FLAG_NO_RECORDED_VALUE = 1; // Bits 2-31 are reserved for future use. } diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index f2c13712b..837daa4cd 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -171,36 +171,6 @@ message Span { // This field is required. string name = 5; - // SpanKind is the type of span. Can be used to specify additional relationships between spans - // in addition to a parent/child relationship. - enum SpanKind { - // Unspecified. Do NOT use as default. - // Implementations MAY assume SpanKind to be INTERNAL when receiving UNSPECIFIED. - SPAN_KIND_UNSPECIFIED = 0; - - // Indicates that the span represents an internal operation within an application, - // as opposed to an operation happening at the boundaries. Default value. - SPAN_KIND_INTERNAL = 1; - - // Indicates that the span covers server-side handling of an RPC or other - // remote network request. - SPAN_KIND_SERVER = 2; - - // Indicates that the span describes a request to some remote service. - SPAN_KIND_CLIENT = 3; - - // Indicates that the span describes a producer sending a message to a broker. - // Unlike CLIENT and SERVER, there is often no direct critical path latency relationship - // between producer and consumer spans. A PRODUCER span ends when the message was accepted - // by the broker while the logical processing of the message might span a much longer time. - SPAN_KIND_PRODUCER = 4; - - // Indicates that the span describes consumer receiving a message from a broker. - // Like the PRODUCER kind, there is often no direct critical path latency relationship - // between producer and consumer spans. - SPAN_KIND_CONSUMER = 5; - } - // 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. @@ -306,6 +276,36 @@ message Span { Status status = 15; } +// SpanKind is the type of span. Can be used to specify additional relationships between spans +// in addition to a parent/child relationship. +enum SpanKind { + // Unspecified. Do NOT use as default. + // Implementations MAY assume SpanKind to be INTERNAL when receiving UNSPECIFIED. + SPAN_KIND_UNSPECIFIED = 0; + + // Indicates that the span represents an internal operation within an application, + // as opposed to an operation happening at the boundaries. Default value. + SPAN_KIND_INTERNAL = 1; + + // Indicates that the span covers server-side handling of an RPC or other + // remote network request. + SPAN_KIND_SERVER = 2; + + // Indicates that the span describes a request to some remote service. + SPAN_KIND_CLIENT = 3; + + // Indicates that the span describes a producer sending a message to a broker. + // Unlike CLIENT and SERVER, there is often no direct critical path latency relationship + // between producer and consumer spans. A PRODUCER span ends when the message was accepted + // by the broker while the logical processing of the message might span a much longer time. + SPAN_KIND_PRODUCER = 4; + + // Indicates that the span describes consumer receiving a message from a broker. + // Like the PRODUCER kind, there is often no direct critical path latency relationship + // between producer and consumer spans. + SPAN_KIND_CONSUMER = 5; +} + // The Status type defines a logical error model that is suitable for different // programming environments, including REST APIs and RPC APIs. message Status { @@ -314,18 +314,18 @@ message Status { // A developer-facing human readable error message. string message = 2; - // For the semantics of status codes see - // https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#set-status - enum StatusCode { - // The default status. - STATUS_CODE_UNSET = 0; - // The Span has been validated by an Application developers or Operator to have - // completed successfully. - STATUS_CODE_OK = 1; - // The Span contains an error. - STATUS_CODE_ERROR = 2; - }; - // The status code. StatusCode code = 3; } + +// For the semantics of status codes see +// https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#set-status +enum StatusCode { + // The default status. + STATUS_CODE_UNSET = 0; + // The Span has been validated by an Application developers or Operator to have + // completed successfully. + STATUS_CODE_OK = 1; + // The Span contains an error. + STATUS_CODE_ERROR = 2; +}; diff --git a/opentelemetry/proto/trace/v1/trace_config.proto b/opentelemetry/proto/trace/v1/trace_config.proto index 43f038a7f..b4b2813cd 100644 --- a/opentelemetry/proto/trace/v1/trace_config.proto +++ b/opentelemetry/proto/trace/v1/trace_config.proto @@ -56,14 +56,15 @@ message ConstantSampler { // - 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; } +enum ConstantDecision { + CONSTANT_DECISION_ALWAYS_OFF = 0; + CONSTANT_DECISION_ALWAYS_ON = 1; + CONSTANT_DECISION_ALWAYS_PARENT = 2; +} + // Sampler that tries to uniformly sample traces with a given ratio. // The ratio of sampling a trace is equal to that of the specified ratio. message TraceIdRatioBased {