From 43378b8fee257466ffb2de139eb7d0c94fd03215 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Fri, 25 Sep 2020 10:42:46 -0400 Subject: [PATCH 1/9] Modify Span status according to specification 1. Renamed Status.code field to Status.deprecated_code. 2. Renamed Status.code.StatusCode enum to Status.DeprecatedStatusCode. 3. Introduce new Status.code with corresponding StatusCanonicalCode enum. 4. Added guidelines about how to use the fields to ensure backward compatibility. --- opentelemetry/proto/trace/v1/trace.proto | 107 +++++++++++++++++------ 1 file changed, 81 insertions(+), 26 deletions(-) diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index 9ecae6c2f..2d2e4c49c 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -220,9 +220,8 @@ message Span { // enforced. If this value is 0, then no links were dropped. uint32 dropped_links_count = 14; - // 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). + // An optional final status for this span. Semantically when Status isn't set it means + // span's status code is unset, i.e. assume STATUS_CANONICAL_CODE_UNSET (code = 0). Status status = 15; } @@ -230,32 +229,88 @@ message Span { // programming environments, including REST APIs and RPC APIs. message Status { - // StatusCode mirrors the codes defined at - // https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/api-tracing.md#statuscanonicalcode - enum StatusCode { - STATUS_CODE_OK = 0; - STATUS_CODE_CANCELLED = 1; - STATUS_CODE_UNKNOWN_ERROR = 2; - STATUS_CODE_INVALID_ARGUMENT = 3; - STATUS_CODE_DEADLINE_EXCEEDED = 4; - STATUS_CODE_NOT_FOUND = 5; - STATUS_CODE_ALREADY_EXISTS = 6; - STATUS_CODE_PERMISSION_DENIED = 7; - STATUS_CODE_RESOURCE_EXHAUSTED = 8; - STATUS_CODE_FAILED_PRECONDITION = 9; - STATUS_CODE_ABORTED = 10; - STATUS_CODE_OUT_OF_RANGE = 11; - STATUS_CODE_UNIMPLEMENTED = 12; - STATUS_CODE_INTERNAL_ERROR = 13; - STATUS_CODE_UNAVAILABLE = 14; - STATUS_CODE_DATA_LOSS = 15; - STATUS_CODE_UNAUTHENTICATED = 16; + enum DeprecatedStatusCode { + DEPRECATED_STATUS_CODE_OK = 0; + DEPRECATED_STATUS_CODE_CANCELLED = 1; + DEPRECATED_STATUS_CODE_UNKNOWN_ERROR = 2; + DEPRECATED_STATUS_CODE_INVALID_ARGUMENT = 3; + DEPRECATED_STATUS_CODE_DEADLINE_EXCEEDED = 4; + DEPRECATED_STATUS_CODE_NOT_FOUND = 5; + DEPRECATED_STATUS_CODE_ALREADY_EXISTS = 6; + DEPRECATED_STATUS_CODE_PERMISSION_DENIED = 7; + DEPRECATED_STATUS_CODE_RESOURCE_EXHAUSTED = 8; + DEPRECATED_STATUS_CODE_FAILED_PRECONDITION = 9; + DEPRECATED_STATUS_CODE_ABORTED = 10; + DEPRECATED_STATUS_CODE_OUT_OF_RANGE = 11; + DEPRECATED_STATUS_CODE_UNIMPLEMENTED = 12; + DEPRECATED_STATUS_CODE_INTERNAL_ERROR = 13; + DEPRECATED_STATUS_CODE_UNAVAILABLE = 14; + DEPRECATED_STATUS_CODE_DATA_LOSS = 15; + DEPRECATED_STATUS_CODE_UNAUTHENTICATED = 16; }; - // The status code. This is optional field. It is safe to assume 0 (OK) - // when not set. - StatusCode code = 1; + // The deprecated status code. This is an optional field. + // + // This field is deprecated and is replaced by `code` field below. See backward + // compatibility notes below. According to our stability guarantees this field + // will be removed in 12 months, on Sep 26, 2021. All usage of old senders and + // receivers that do not understand the `code` field MUST be phased out by then. + DeprecatedStatusCode deprecated_code = 1 [deprecated=true]; // 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/master/specification/trace/api.md#statuscanonicalcode + enum StatusCanonicalCode { + // The default status. + STATUS_CANONICAL_CODE_UNSET = 0; + // The Span has been validated by an Application developers or Operator to have + // completed successfully. + STATUS_CANONICAL_CODE_OK = 1; + // The Span contains an error. + STATUS_CANONICAL_CODE_ERROR = 2; + }; + + // The status code. + StatusCanonicalCode code = 3; + + // IMPORTANT: Backward compatibility notes: + // + // To ensure any two pair of senders and receivers continues to correctly signal and + // interpret erroneous situation the senders and receivers SHOULD follow these rules: + // + // 1. Old senders and receives that are not aware of `code` field will continue using + // `deprecated_code` field to signal and interpret erroneous situation. + // + // 2. New senders, which are aware of `code` field should set both `deprecated_code` + // and `code` fields according to the following rules: + // + // if code==STATUS_CANONICAL_CODE_UNSET then `deprecated_code` must be + // set to DEPRECATED_STATUS_CODE_OK. + // + // if code==STATUS_CANONICAL_CODE_ERROR then `deprecated_code` must be + // set to DEPRECATED_STATUS_CODE_UNKNOWN_ERROR. + // + // if code==STATUS_CANONICAL_CODE_OK then `deprecated_code` must be + // set to DEPRECATED_STATUS_CODE_OK. + // + // These rules allow old receivers to correctly interpret data received from new senders. + // + // 3. New receivers should look both at `code` and `deprecated_code` fields in order + // to interpret the overall status: + // + // If code==STATUS_CANONICAL_CODE_UNSET then the value of `deprecated_code` is the + // carrier of the overall status according to these rules: + // + // if deprecated_code==DEPRECATED_STATUS_CODE_OK then the receiver should interpret + // the overall status to be STATUS_CANONICAL_CODE_UNSET. + // + // if deprecated_code!=DEPRECATED_STATUS_CODE_OK then the receiver should interpret + // the overall status to be STATUS_CANONICAL_CODE_ERROR. + // + // If code!=STATUS_CANONICAL_CODE_UNSET then the value of `deprecated_code` should be + // ignored, the `code` field is the sole carrier of status. + // + // These rules allow new receivers to correctly interpret data received from old senders. } From 5e88c599b894341f97d397351811f3bafd5297a8 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Mon, 28 Sep 2020 12:46:40 -0400 Subject: [PATCH 2/9] Address PR comments --- opentelemetry/proto/trace/v1/trace.proto | 30 ++++++++++++------------ 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index 2d2e4c49c..590170acb 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -220,7 +220,7 @@ message Span { // enforced. If this value is 0, then no links were dropped. uint32 dropped_links_count = 14; - // An optional final status for this span. Semantically when Status isn't set it means + // An optional final status for this span. Semantically when Status isn't set, it means // span's status code is unset, i.e. assume STATUS_CANONICAL_CODE_UNSET (code = 0). Status status = 15; } @@ -251,7 +251,7 @@ message Status { // The deprecated status code. This is an optional field. // - // This field is deprecated and is replaced by `code` field below. See backward + // This field is deprecated and is replaced by the `code` field below. See backward // compatibility notes below. According to our stability guarantees this field // will be removed in 12 months, on Sep 26, 2021. All usage of old senders and // receivers that do not understand the `code` field MUST be phased out by then. @@ -277,27 +277,27 @@ message Status { // IMPORTANT: Backward compatibility notes: // - // To ensure any two pair of senders and receivers continues to correctly signal and - // interpret erroneous situation the senders and receivers SHOULD follow these rules: + // To ensure any pair of senders and receivers continues to correctly signal and + // interpret erroneous situations, the senders and receivers SHOULD follow these rules: // - // 1. Old senders and receives that are not aware of `code` field will continue using - // `deprecated_code` field to signal and interpret erroneous situation. + // 1. Old senders and receivers that are not aware of `code` field will continue using + // the `deprecated_code` field to signal and interpret erroneous situation. // - // 2. New senders, which are aware of `code` field should set both `deprecated_code` - // and `code` fields according to the following rules: + // 2. New senders, which are aware of the `code` field SHOULD set both the + // `deprecated_code` and `code` fields according to the following rules: // - // if code==STATUS_CANONICAL_CODE_UNSET then `deprecated_code` must be + // if code==STATUS_CANONICAL_CODE_UNSET then `deprecated_code` MUST be // set to DEPRECATED_STATUS_CODE_OK. // - // if code==STATUS_CANONICAL_CODE_ERROR then `deprecated_code` must be - // set to DEPRECATED_STATUS_CODE_UNKNOWN_ERROR. - // - // if code==STATUS_CANONICAL_CODE_OK then `deprecated_code` must be + // if code==STATUS_CANONICAL_CODE_OK then `deprecated_code` MUST be // set to DEPRECATED_STATUS_CODE_OK. // + // if code==STATUS_CANONICAL_CODE_ERROR then `deprecated_code` MUST be + // set to DEPRECATED_STATUS_CODE_UNKNOWN_ERROR. + // // These rules allow old receivers to correctly interpret data received from new senders. // - // 3. New receivers should look both at `code` and `deprecated_code` fields in order + // 3. New receivers should look at both the `code` and `deprecated_code` fields in order // to interpret the overall status: // // If code==STATUS_CANONICAL_CODE_UNSET then the value of `deprecated_code` is the @@ -310,7 +310,7 @@ message Status { // the overall status to be STATUS_CANONICAL_CODE_ERROR. // // If code!=STATUS_CANONICAL_CODE_UNSET then the value of `deprecated_code` should be - // ignored, the `code` field is the sole carrier of status. + // ignored, the `code` field is the sole carrier of the status. // // These rules allow new receivers to correctly interpret data received from old senders. } From fd140af28bb6594f2772215d40fcff13d997be32 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Wed, 7 Oct 2020 11:42:57 -0400 Subject: [PATCH 3/9] Revert renaming of code to deprecated_code We want to keep the old field and enum names. --- opentelemetry/proto/trace/v1/trace.proto | 83 ++++++++++++------------ 1 file changed, 42 insertions(+), 41 deletions(-) diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index 590170acb..61ebc021e 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -221,7 +221,7 @@ message Span { uint32 dropped_links_count = 14; // An optional final status for this span. Semantically when Status isn't set, it means - // span's status code is unset, i.e. assume STATUS_CANONICAL_CODE_UNSET (code = 0). + // span's status code is unset, i.e. assume STATUS_CANONICAL_CODE_UNSET (canonical_code = 0). Status status = 15; } @@ -229,33 +229,34 @@ message Span { // programming environments, including REST APIs and RPC APIs. message Status { - enum DeprecatedStatusCode { - DEPRECATED_STATUS_CODE_OK = 0; - DEPRECATED_STATUS_CODE_CANCELLED = 1; - DEPRECATED_STATUS_CODE_UNKNOWN_ERROR = 2; - DEPRECATED_STATUS_CODE_INVALID_ARGUMENT = 3; - DEPRECATED_STATUS_CODE_DEADLINE_EXCEEDED = 4; - DEPRECATED_STATUS_CODE_NOT_FOUND = 5; - DEPRECATED_STATUS_CODE_ALREADY_EXISTS = 6; - DEPRECATED_STATUS_CODE_PERMISSION_DENIED = 7; - DEPRECATED_STATUS_CODE_RESOURCE_EXHAUSTED = 8; - DEPRECATED_STATUS_CODE_FAILED_PRECONDITION = 9; - DEPRECATED_STATUS_CODE_ABORTED = 10; - DEPRECATED_STATUS_CODE_OUT_OF_RANGE = 11; - DEPRECATED_STATUS_CODE_UNIMPLEMENTED = 12; - DEPRECATED_STATUS_CODE_INTERNAL_ERROR = 13; - DEPRECATED_STATUS_CODE_UNAVAILABLE = 14; - DEPRECATED_STATUS_CODE_DATA_LOSS = 15; - DEPRECATED_STATUS_CODE_UNAUTHENTICATED = 16; + enum StatusCode { + STATUS_CODE_OK = 0; + STATUS_CODE_CANCELLED = 1; + STATUS_CODE_UNKNOWN_ERROR = 2; + STATUS_CODE_INVALID_ARGUMENT = 3; + STATUS_CODE_DEADLINE_EXCEEDED = 4; + STATUS_CODE_NOT_FOUND = 5; + STATUS_CODE_ALREADY_EXISTS = 6; + STATUS_CODE_PERMISSION_DENIED = 7; + STATUS_CODE_RESOURCE_EXHAUSTED = 8; + STATUS_CODE_FAILED_PRECONDITION = 9; + STATUS_CODE_ABORTED = 10; + STATUS_CODE_OUT_OF_RANGE = 11; + STATUS_CODE_UNIMPLEMENTED = 12; + STATUS_CODE_INTERNAL_ERROR = 13; + STATUS_CODE_UNAVAILABLE = 14; + STATUS_CODE_DATA_LOSS = 15; + STATUS_CODE_UNAUTHENTICATED = 16; }; // The deprecated status code. This is an optional field. // - // This field is deprecated and is replaced by the `code` field below. See backward - // compatibility notes below. According to our stability guarantees this field + // This field is deprecated and is replaced by the `canonical_code` field below. See + // backward compatibility notes below. According to our stability guarantees this field // will be removed in 12 months, on Sep 26, 2021. All usage of old senders and - // receivers that do not understand the `code` field MUST be phased out by then. - DeprecatedStatusCode deprecated_code = 1 [deprecated=true]; + // receivers that do not understand the `canonical_code` field MUST be phased out + // by then. + StatusCode code = 1 [deprecated=true]; // A developer-facing human readable error message. string message = 2; @@ -272,45 +273,45 @@ message Status { STATUS_CANONICAL_CODE_ERROR = 2; }; - // The status code. - StatusCanonicalCode code = 3; + // The new status canonical_code. + StatusCanonicalCode canonical_code = 3; // IMPORTANT: Backward compatibility notes: // // To ensure any pair of senders and receivers continues to correctly signal and // interpret erroneous situations, the senders and receivers SHOULD follow these rules: // - // 1. Old senders and receivers that are not aware of `code` field will continue using - // the `deprecated_code` field to signal and interpret erroneous situation. + // 1. Old senders and receivers that are not aware of `canonical_code` field will + // continue using the `code` field to signal and interpret erroneous situation. // - // 2. New senders, which are aware of the `code` field SHOULD set both the - // `deprecated_code` and `code` fields according to the following rules: + // 2. New senders, which are aware of the `canonical_code` field SHOULD set both the + // `code` and `canonical_code` fields according to the following rules: // - // if code==STATUS_CANONICAL_CODE_UNSET then `deprecated_code` MUST be - // set to DEPRECATED_STATUS_CODE_OK. + // if canonical_code==STATUS_CANONICAL_CODE_UNSET then `code` MUST be + // set to STATUS_CODE_OK. // - // if code==STATUS_CANONICAL_CODE_OK then `deprecated_code` MUST be - // set to DEPRECATED_STATUS_CODE_OK. + // if canonical_code==STATUS_CANONICAL_CODE_OK then `code` MUST be + // set to STATUS_CODE_OK. // - // if code==STATUS_CANONICAL_CODE_ERROR then `deprecated_code` MUST be - // set to DEPRECATED_STATUS_CODE_UNKNOWN_ERROR. + // if canonical_code==STATUS_CANONICAL_CODE_ERROR then `code` MUST be + // set to STATUS_CODE_UNKNOWN_ERROR. // // These rules allow old receivers to correctly interpret data received from new senders. // - // 3. New receivers should look at both the `code` and `deprecated_code` fields in order + // 3. New receivers should look at both the `canonical_code` and `code` fields in order // to interpret the overall status: // - // If code==STATUS_CANONICAL_CODE_UNSET then the value of `deprecated_code` is the + // If canonical_code==STATUS_CANONICAL_CODE_UNSET then the value of `code` is the // carrier of the overall status according to these rules: // - // if deprecated_code==DEPRECATED_STATUS_CODE_OK then the receiver should interpret + // if code==STATUS_CODE_OK then the receiver should interpret // the overall status to be STATUS_CANONICAL_CODE_UNSET. // - // if deprecated_code!=DEPRECATED_STATUS_CODE_OK then the receiver should interpret + // if code!=STATUS_CODE_OK then the receiver should interpret // the overall status to be STATUS_CANONICAL_CODE_ERROR. // - // If code!=STATUS_CANONICAL_CODE_UNSET then the value of `deprecated_code` should be - // ignored, the `code` field is the sole carrier of the status. + // If canonical_code!=STATUS_CANONICAL_CODE_UNSET then the value of `code` should be + // ignored, the `canonical_code` field is the sole carrier of the status. // // These rules allow new receivers to correctly interpret data received from old senders. } From 42cc74c39a4bf3304c315f09895fbd2686c6dae1 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Fri, 9 Oct 2020 09:15:31 -0400 Subject: [PATCH 4/9] Get rid of "canonical" adjective --- opentelemetry/proto/trace/v1/trace.proto | 45 +++++++++++------------- 1 file changed, 21 insertions(+), 24 deletions(-) diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index 61ebc021e..55902b0c4 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -221,7 +221,7 @@ message Span { uint32 dropped_links_count = 14; // An optional final status for this span. Semantically when Status isn't set, it means - // span's status code is unset, i.e. assume STATUS_CANONICAL_CODE_UNSET (canonical_code = 0). + // span's status code is unset, i.e. assume CODE_VALUE_UNSET (code_value = 0). Status status = 15; } @@ -251,10 +251,10 @@ message Status { // The deprecated status code. This is an optional field. // - // This field is deprecated and is replaced by the `canonical_code` field below. See + // This field is deprecated and is replaced by the `code_value` field below. See // backward compatibility notes below. According to our stability guarantees this field // will be removed in 12 months, on Sep 26, 2021. All usage of old senders and - // receivers that do not understand the `canonical_code` field MUST be phased out + // receivers that do not understand the `code_value` field MUST be phased out // by then. StatusCode code = 1 [deprecated=true]; @@ -263,55 +263,52 @@ message Status { // For the semantics of status codes see // https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#statuscanonicalcode - enum StatusCanonicalCode { + enum CodeValue { // The default status. - STATUS_CANONICAL_CODE_UNSET = 0; + CODE_VALUE_UNSET = 0; // The Span has been validated by an Application developers or Operator to have // completed successfully. - STATUS_CANONICAL_CODE_OK = 1; + CODE_VALUE_OK = 1; // The Span contains an error. - STATUS_CANONICAL_CODE_ERROR = 2; + CODE_VALUE_ERROR = 2; }; - // The new status canonical_code. - StatusCanonicalCode canonical_code = 3; + // The new status code value. + CodeValue code_value = 3; // IMPORTANT: Backward compatibility notes: // // To ensure any pair of senders and receivers continues to correctly signal and // interpret erroneous situations, the senders and receivers SHOULD follow these rules: // - // 1. Old senders and receivers that are not aware of `canonical_code` field will + // 1. Old senders and receivers that are not aware of `code_value` field will // continue using the `code` field to signal and interpret erroneous situation. // - // 2. New senders, which are aware of the `canonical_code` field SHOULD set both the - // `code` and `canonical_code` fields according to the following rules: + // 2. New senders, which are aware of the `code_value` field SHOULD set both the + // `code` and `code_value` fields according to the following rules: // - // if canonical_code==STATUS_CANONICAL_CODE_UNSET then `code` MUST be - // set to STATUS_CODE_OK. + // if code_value==CODE_VALUE_UNSET then `code` MUST be set to STATUS_CODE_OK. // - // if canonical_code==STATUS_CANONICAL_CODE_OK then `code` MUST be - // set to STATUS_CODE_OK. + // if code_value==CODE_VALUE_OK then `code` MUST be set to STATUS_CODE_OK. // - // if canonical_code==STATUS_CANONICAL_CODE_ERROR then `code` MUST be - // set to STATUS_CODE_UNKNOWN_ERROR. + // if code_value==CODE_VALUE_ERROR then `code` MUST be set to STATUS_CODE_UNKNOWN_ERROR. // // These rules allow old receivers to correctly interpret data received from new senders. // - // 3. New receivers should look at both the `canonical_code` and `code` fields in order + // 3. New receivers should look at both the `code_value` and `code` fields in order // to interpret the overall status: // - // If canonical_code==STATUS_CANONICAL_CODE_UNSET then the value of `code` is the + // If code_value==CODE_VALUE_UNSET then the value of `code` is the // carrier of the overall status according to these rules: // // if code==STATUS_CODE_OK then the receiver should interpret - // the overall status to be STATUS_CANONICAL_CODE_UNSET. + // the overall status to be CODE_UNSET. // // if code!=STATUS_CODE_OK then the receiver should interpret - // the overall status to be STATUS_CANONICAL_CODE_ERROR. + // the overall status to be CODE_ERROR. // - // If canonical_code!=STATUS_CANONICAL_CODE_UNSET then the value of `code` should be - // ignored, the `canonical_code` field is the sole carrier of the status. + // If code_value!=CODE_VALUE_UNSET then the value of `code` should be + // ignored, the `code_value` field is the sole carrier of the status. // // These rules allow new receivers to correctly interpret data received from old senders. } From f2eb7faabdded231fb0c9bd498d7b15db73f7b25 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Thu, 22 Oct 2020 11:16:31 -0400 Subject: [PATCH 5/9] Revert "Get rid of "canonical" adjective" This reverts commit b3b01e1a27dc31e258c60c9b441a4f96c7a240e4. --- opentelemetry/proto/trace/v1/trace.proto | 45 +++++++++++++----------- 1 file changed, 24 insertions(+), 21 deletions(-) diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index 55902b0c4..61ebc021e 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -221,7 +221,7 @@ message Span { uint32 dropped_links_count = 14; // An optional final status for this span. Semantically when Status isn't set, it means - // span's status code is unset, i.e. assume CODE_VALUE_UNSET (code_value = 0). + // span's status code is unset, i.e. assume STATUS_CANONICAL_CODE_UNSET (canonical_code = 0). Status status = 15; } @@ -251,10 +251,10 @@ message Status { // The deprecated status code. This is an optional field. // - // This field is deprecated and is replaced by the `code_value` field below. See + // This field is deprecated and is replaced by the `canonical_code` field below. See // backward compatibility notes below. According to our stability guarantees this field // will be removed in 12 months, on Sep 26, 2021. All usage of old senders and - // receivers that do not understand the `code_value` field MUST be phased out + // receivers that do not understand the `canonical_code` field MUST be phased out // by then. StatusCode code = 1 [deprecated=true]; @@ -263,52 +263,55 @@ message Status { // For the semantics of status codes see // https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#statuscanonicalcode - enum CodeValue { + enum StatusCanonicalCode { // The default status. - CODE_VALUE_UNSET = 0; + STATUS_CANONICAL_CODE_UNSET = 0; // The Span has been validated by an Application developers or Operator to have // completed successfully. - CODE_VALUE_OK = 1; + STATUS_CANONICAL_CODE_OK = 1; // The Span contains an error. - CODE_VALUE_ERROR = 2; + STATUS_CANONICAL_CODE_ERROR = 2; }; - // The new status code value. - CodeValue code_value = 3; + // The new status canonical_code. + StatusCanonicalCode canonical_code = 3; // IMPORTANT: Backward compatibility notes: // // To ensure any pair of senders and receivers continues to correctly signal and // interpret erroneous situations, the senders and receivers SHOULD follow these rules: // - // 1. Old senders and receivers that are not aware of `code_value` field will + // 1. Old senders and receivers that are not aware of `canonical_code` field will // continue using the `code` field to signal and interpret erroneous situation. // - // 2. New senders, which are aware of the `code_value` field SHOULD set both the - // `code` and `code_value` fields according to the following rules: + // 2. New senders, which are aware of the `canonical_code` field SHOULD set both the + // `code` and `canonical_code` fields according to the following rules: // - // if code_value==CODE_VALUE_UNSET then `code` MUST be set to STATUS_CODE_OK. + // if canonical_code==STATUS_CANONICAL_CODE_UNSET then `code` MUST be + // set to STATUS_CODE_OK. // - // if code_value==CODE_VALUE_OK then `code` MUST be set to STATUS_CODE_OK. + // if canonical_code==STATUS_CANONICAL_CODE_OK then `code` MUST be + // set to STATUS_CODE_OK. // - // if code_value==CODE_VALUE_ERROR then `code` MUST be set to STATUS_CODE_UNKNOWN_ERROR. + // if canonical_code==STATUS_CANONICAL_CODE_ERROR then `code` MUST be + // set to STATUS_CODE_UNKNOWN_ERROR. // // These rules allow old receivers to correctly interpret data received from new senders. // - // 3. New receivers should look at both the `code_value` and `code` fields in order + // 3. New receivers should look at both the `canonical_code` and `code` fields in order // to interpret the overall status: // - // If code_value==CODE_VALUE_UNSET then the value of `code` is the + // If canonical_code==STATUS_CANONICAL_CODE_UNSET then the value of `code` is the // carrier of the overall status according to these rules: // // if code==STATUS_CODE_OK then the receiver should interpret - // the overall status to be CODE_UNSET. + // the overall status to be STATUS_CANONICAL_CODE_UNSET. // // if code!=STATUS_CODE_OK then the receiver should interpret - // the overall status to be CODE_ERROR. + // the overall status to be STATUS_CANONICAL_CODE_ERROR. // - // If code_value!=CODE_VALUE_UNSET then the value of `code` should be - // ignored, the `code_value` field is the sole carrier of the status. + // If canonical_code!=STATUS_CANONICAL_CODE_UNSET then the value of `code` should be + // ignored, the `canonical_code` field is the sole carrier of the status. // // These rules allow new receivers to correctly interpret data received from old senders. } From 95ee9fdc1da6c3fad178b57955b53e3bf38a97ae Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Thu, 22 Oct 2020 11:16:31 -0400 Subject: [PATCH 6/9] Revert "Revert renaming of code to deprecated_code" This reverts commit 6b9a7a41e527c345da3a221ea691fe79a973a898. --- opentelemetry/proto/trace/v1/trace.proto | 83 ++++++++++++------------ 1 file changed, 41 insertions(+), 42 deletions(-) diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index 61ebc021e..590170acb 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -221,7 +221,7 @@ message Span { uint32 dropped_links_count = 14; // An optional final status for this span. Semantically when Status isn't set, it means - // span's status code is unset, i.e. assume STATUS_CANONICAL_CODE_UNSET (canonical_code = 0). + // span's status code is unset, i.e. assume STATUS_CANONICAL_CODE_UNSET (code = 0). Status status = 15; } @@ -229,34 +229,33 @@ message Span { // programming environments, including REST APIs and RPC APIs. message Status { - enum StatusCode { - STATUS_CODE_OK = 0; - STATUS_CODE_CANCELLED = 1; - STATUS_CODE_UNKNOWN_ERROR = 2; - STATUS_CODE_INVALID_ARGUMENT = 3; - STATUS_CODE_DEADLINE_EXCEEDED = 4; - STATUS_CODE_NOT_FOUND = 5; - STATUS_CODE_ALREADY_EXISTS = 6; - STATUS_CODE_PERMISSION_DENIED = 7; - STATUS_CODE_RESOURCE_EXHAUSTED = 8; - STATUS_CODE_FAILED_PRECONDITION = 9; - STATUS_CODE_ABORTED = 10; - STATUS_CODE_OUT_OF_RANGE = 11; - STATUS_CODE_UNIMPLEMENTED = 12; - STATUS_CODE_INTERNAL_ERROR = 13; - STATUS_CODE_UNAVAILABLE = 14; - STATUS_CODE_DATA_LOSS = 15; - STATUS_CODE_UNAUTHENTICATED = 16; + enum DeprecatedStatusCode { + DEPRECATED_STATUS_CODE_OK = 0; + DEPRECATED_STATUS_CODE_CANCELLED = 1; + DEPRECATED_STATUS_CODE_UNKNOWN_ERROR = 2; + DEPRECATED_STATUS_CODE_INVALID_ARGUMENT = 3; + DEPRECATED_STATUS_CODE_DEADLINE_EXCEEDED = 4; + DEPRECATED_STATUS_CODE_NOT_FOUND = 5; + DEPRECATED_STATUS_CODE_ALREADY_EXISTS = 6; + DEPRECATED_STATUS_CODE_PERMISSION_DENIED = 7; + DEPRECATED_STATUS_CODE_RESOURCE_EXHAUSTED = 8; + DEPRECATED_STATUS_CODE_FAILED_PRECONDITION = 9; + DEPRECATED_STATUS_CODE_ABORTED = 10; + DEPRECATED_STATUS_CODE_OUT_OF_RANGE = 11; + DEPRECATED_STATUS_CODE_UNIMPLEMENTED = 12; + DEPRECATED_STATUS_CODE_INTERNAL_ERROR = 13; + DEPRECATED_STATUS_CODE_UNAVAILABLE = 14; + DEPRECATED_STATUS_CODE_DATA_LOSS = 15; + DEPRECATED_STATUS_CODE_UNAUTHENTICATED = 16; }; // The deprecated status code. This is an optional field. // - // This field is deprecated and is replaced by the `canonical_code` field below. See - // backward compatibility notes below. According to our stability guarantees this field + // This field is deprecated and is replaced by the `code` field below. See backward + // compatibility notes below. According to our stability guarantees this field // will be removed in 12 months, on Sep 26, 2021. All usage of old senders and - // receivers that do not understand the `canonical_code` field MUST be phased out - // by then. - StatusCode code = 1 [deprecated=true]; + // receivers that do not understand the `code` field MUST be phased out by then. + DeprecatedStatusCode deprecated_code = 1 [deprecated=true]; // A developer-facing human readable error message. string message = 2; @@ -273,45 +272,45 @@ message Status { STATUS_CANONICAL_CODE_ERROR = 2; }; - // The new status canonical_code. - StatusCanonicalCode canonical_code = 3; + // The status code. + StatusCanonicalCode code = 3; // IMPORTANT: Backward compatibility notes: // // To ensure any pair of senders and receivers continues to correctly signal and // interpret erroneous situations, the senders and receivers SHOULD follow these rules: // - // 1. Old senders and receivers that are not aware of `canonical_code` field will - // continue using the `code` field to signal and interpret erroneous situation. + // 1. Old senders and receivers that are not aware of `code` field will continue using + // the `deprecated_code` field to signal and interpret erroneous situation. // - // 2. New senders, which are aware of the `canonical_code` field SHOULD set both the - // `code` and `canonical_code` fields according to the following rules: + // 2. New senders, which are aware of the `code` field SHOULD set both the + // `deprecated_code` and `code` fields according to the following rules: // - // if canonical_code==STATUS_CANONICAL_CODE_UNSET then `code` MUST be - // set to STATUS_CODE_OK. + // if code==STATUS_CANONICAL_CODE_UNSET then `deprecated_code` MUST be + // set to DEPRECATED_STATUS_CODE_OK. // - // if canonical_code==STATUS_CANONICAL_CODE_OK then `code` MUST be - // set to STATUS_CODE_OK. + // if code==STATUS_CANONICAL_CODE_OK then `deprecated_code` MUST be + // set to DEPRECATED_STATUS_CODE_OK. // - // if canonical_code==STATUS_CANONICAL_CODE_ERROR then `code` MUST be - // set to STATUS_CODE_UNKNOWN_ERROR. + // if code==STATUS_CANONICAL_CODE_ERROR then `deprecated_code` MUST be + // set to DEPRECATED_STATUS_CODE_UNKNOWN_ERROR. // // These rules allow old receivers to correctly interpret data received from new senders. // - // 3. New receivers should look at both the `canonical_code` and `code` fields in order + // 3. New receivers should look at both the `code` and `deprecated_code` fields in order // to interpret the overall status: // - // If canonical_code==STATUS_CANONICAL_CODE_UNSET then the value of `code` is the + // If code==STATUS_CANONICAL_CODE_UNSET then the value of `deprecated_code` is the // carrier of the overall status according to these rules: // - // if code==STATUS_CODE_OK then the receiver should interpret + // if deprecated_code==DEPRECATED_STATUS_CODE_OK then the receiver should interpret // the overall status to be STATUS_CANONICAL_CODE_UNSET. // - // if code!=STATUS_CODE_OK then the receiver should interpret + // if deprecated_code!=DEPRECATED_STATUS_CODE_OK then the receiver should interpret // the overall status to be STATUS_CANONICAL_CODE_ERROR. // - // If canonical_code!=STATUS_CANONICAL_CODE_UNSET then the value of `code` should be - // ignored, the `canonical_code` field is the sole carrier of the status. + // If code!=STATUS_CANONICAL_CODE_UNSET then the value of `deprecated_code` should be + // ignored, the `code` field is the sole carrier of the status. // // These rules allow new receivers to correctly interpret data received from old senders. } From bc0050f2d92a346fb6fc7c7ffd620b1ad386f32f Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Thu, 22 Oct 2020 11:18:52 -0400 Subject: [PATCH 7/9] Get rid of "canonical" adjective --- opentelemetry/proto/trace/v1/trace.proto | 28 ++++++++++++------------ 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index 590170acb..3b70ebfb8 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -221,7 +221,7 @@ message Span { uint32 dropped_links_count = 14; // An optional final status for this span. Semantically when Status isn't set, it means - // span's status code is unset, i.e. assume STATUS_CANONICAL_CODE_UNSET (code = 0). + // span's status code is unset, i.e. assume STATUS_CODE_UNSET (code = 0). Status status = 15; } @@ -261,19 +261,19 @@ message Status { string message = 2; // For the semantics of status codes see - // https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#statuscanonicalcode - enum StatusCanonicalCode { + // https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#set-status + enum StatusCode { // The default status. - STATUS_CANONICAL_CODE_UNSET = 0; + STATUS_CODE_UNSET = 0; // The Span has been validated by an Application developers or Operator to have // completed successfully. - STATUS_CANONICAL_CODE_OK = 1; + STATUS_CODE_OK = 1; // The Span contains an error. - STATUS_CANONICAL_CODE_ERROR = 2; + STATUS_CODE_ERROR = 2; }; // The status code. - StatusCanonicalCode code = 3; + StatusCode code = 3; // IMPORTANT: Backward compatibility notes: // @@ -286,13 +286,13 @@ message Status { // 2. New senders, which are aware of the `code` field SHOULD set both the // `deprecated_code` and `code` fields according to the following rules: // - // if code==STATUS_CANONICAL_CODE_UNSET then `deprecated_code` MUST be + // if code==STATUS_CODE_UNSET then `deprecated_code` MUST be // set to DEPRECATED_STATUS_CODE_OK. // - // if code==STATUS_CANONICAL_CODE_OK then `deprecated_code` MUST be + // if code==STATUS_CODE_OK then `deprecated_code` MUST be // set to DEPRECATED_STATUS_CODE_OK. // - // if code==STATUS_CANONICAL_CODE_ERROR then `deprecated_code` MUST be + // if code==STATUS_CODE_ERROR then `deprecated_code` MUST be // set to DEPRECATED_STATUS_CODE_UNKNOWN_ERROR. // // These rules allow old receivers to correctly interpret data received from new senders. @@ -300,16 +300,16 @@ message Status { // 3. New receivers should look at both the `code` and `deprecated_code` fields in order // to interpret the overall status: // - // If code==STATUS_CANONICAL_CODE_UNSET then the value of `deprecated_code` is the + // If code==STATUS_CODE_UNSET then the value of `deprecated_code` is the // carrier of the overall status according to these rules: // // if deprecated_code==DEPRECATED_STATUS_CODE_OK then the receiver should interpret - // the overall status to be STATUS_CANONICAL_CODE_UNSET. + // the overall status to be STATUS_CODE_UNSET. // // if deprecated_code!=DEPRECATED_STATUS_CODE_OK then the receiver should interpret - // the overall status to be STATUS_CANONICAL_CODE_ERROR. + // the overall status to be STATUS_CODE_ERROR. // - // If code!=STATUS_CANONICAL_CODE_UNSET then the value of `deprecated_code` should be + // If code!=STATUS_CODE_UNSET then the value of `deprecated_code` should be // ignored, the `code` field is the sole carrier of the status. // // These rules allow new receivers to correctly interpret data received from old senders. From d21654b7e61d63d8698fa49d4dac18224aeb4684 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Thu, 22 Oct 2020 12:00:01 -0400 Subject: [PATCH 8/9] Update removal date --- opentelemetry/proto/trace/v1/trace.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index 3b70ebfb8..3172d3e08 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -253,7 +253,7 @@ message Status { // // This field is deprecated and is replaced by the `code` field below. See backward // compatibility notes below. According to our stability guarantees this field - // will be removed in 12 months, on Sep 26, 2021. All usage of old senders and + // will be removed in 12 months, on Oct 22, 2021. All usage of old senders and // receivers that do not understand the `code` field MUST be phased out by then. DeprecatedStatusCode deprecated_code = 1 [deprecated=true]; From 3edd5e747221d4ad3bf552e02db307ef78aa1428 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Thu, 22 Oct 2020 12:09:05 -0400 Subject: [PATCH 9/9] Change SHOULD->MUST, move comment section to the top. --- opentelemetry/proto/trace/v1/trace.proto | 77 ++++++++++++------------ 1 file changed, 38 insertions(+), 39 deletions(-) diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index 3172d3e08..3eb766a5f 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -228,6 +228,44 @@ message Span { // The Status type defines a logical error model that is suitable for different // programming environments, including REST APIs and RPC APIs. message Status { + // IMPORTANT: Backward compatibility notes: + // + // To ensure any pair of senders and receivers continues to correctly signal and + // interpret erroneous situations, the senders and receivers MUST follow these rules: + // + // 1. Old senders and receivers that are not aware of `code` field will continue using + // the `deprecated_code` field to signal and interpret erroneous situation. + // + // 2. New senders, which are aware of the `code` field MUST set both the + // `deprecated_code` and `code` fields according to the following rules: + // + // if code==STATUS_CODE_UNSET then `deprecated_code` MUST be + // set to DEPRECATED_STATUS_CODE_OK. + // + // if code==STATUS_CODE_OK then `deprecated_code` MUST be + // set to DEPRECATED_STATUS_CODE_OK. + // + // if code==STATUS_CODE_ERROR then `deprecated_code` MUST be + // set to DEPRECATED_STATUS_CODE_UNKNOWN_ERROR. + // + // These rules allow old receivers to correctly interpret data received from new senders. + // + // 3. New receivers MUST look at both the `code` and `deprecated_code` fields in order + // to interpret the overall status: + // + // If code==STATUS_CODE_UNSET then the value of `deprecated_code` is the + // carrier of the overall status according to these rules: + // + // if deprecated_code==DEPRECATED_STATUS_CODE_OK then the receiver MUST interpret + // the overall status to be STATUS_CODE_UNSET. + // + // if deprecated_code!=DEPRECATED_STATUS_CODE_OK then the receiver MUST interpret + // the overall status to be STATUS_CODE_ERROR. + // + // If code!=STATUS_CODE_UNSET then the value of `deprecated_code` MUST be + // ignored, the `code` field is the sole carrier of the status. + // + // These rules allow new receivers to correctly interpret data received from old senders. enum DeprecatedStatusCode { DEPRECATED_STATUS_CODE_OK = 0; @@ -274,43 +312,4 @@ message Status { // The status code. StatusCode code = 3; - - // IMPORTANT: Backward compatibility notes: - // - // To ensure any pair of senders and receivers continues to correctly signal and - // interpret erroneous situations, the senders and receivers SHOULD follow these rules: - // - // 1. Old senders and receivers that are not aware of `code` field will continue using - // the `deprecated_code` field to signal and interpret erroneous situation. - // - // 2. New senders, which are aware of the `code` field SHOULD set both the - // `deprecated_code` and `code` fields according to the following rules: - // - // if code==STATUS_CODE_UNSET then `deprecated_code` MUST be - // set to DEPRECATED_STATUS_CODE_OK. - // - // if code==STATUS_CODE_OK then `deprecated_code` MUST be - // set to DEPRECATED_STATUS_CODE_OK. - // - // if code==STATUS_CODE_ERROR then `deprecated_code` MUST be - // set to DEPRECATED_STATUS_CODE_UNKNOWN_ERROR. - // - // These rules allow old receivers to correctly interpret data received from new senders. - // - // 3. New receivers should look at both the `code` and `deprecated_code` fields in order - // to interpret the overall status: - // - // If code==STATUS_CODE_UNSET then the value of `deprecated_code` is the - // carrier of the overall status according to these rules: - // - // if deprecated_code==DEPRECATED_STATUS_CODE_OK then the receiver should interpret - // the overall status to be STATUS_CODE_UNSET. - // - // if deprecated_code!=DEPRECATED_STATUS_CODE_OK then the receiver should interpret - // the overall status to be STATUS_CODE_ERROR. - // - // If code!=STATUS_CODE_UNSET then the value of `deprecated_code` should be - // ignored, the `code` field is the sole carrier of the status. - // - // These rules allow new receivers to correctly interpret data received from old senders. }