From 2042bc283d852c827986781234d9af92288bf4de Mon Sep 17 00:00:00 2001 From: jack-berg Date: Mon, 27 Sep 2021 18:10:00 -0500 Subject: [PATCH 1/3] Add specification for otlp retry configuration parameters and defaults --- specification/protocol/exporter.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/specification/protocol/exporter.md b/specification/protocol/exporter.md index 5a3268f2f54..d9eb1c6bc36 100644 --- a/specification/protocol/exporter.md +++ b/specification/protocol/exporter.md @@ -62,6 +62,20 @@ The `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_EXPORTER_OTLP_TRACES_HEADERS`, `OTEL_EXP Transient errors MUST be handled with a retry strategy. This retry strategy MUST implement an exponential back-off with jitter to avoid overwhelming the destination until the network is restored or the destination has recovered. -For OTLP/HTTP, the errors `408 (Request Timeout)` and `5xx (Server Errors)` are defined as transient, detailed information about erros can be found in the [HTTP failures section](otlp.md#failures). For the OTLP/gRPC, the full list of the gRPC retryable status codes can be found in the [gRPC response section](otlp.md#otlpgrpc-response). +For OTLP/HTTP, the errors `408 (Request Timeout)` and `5xx (Server Errors)` are defined as transient, detailed information about errors can be found in the [HTTP failures section](otlp.md#failures). For the OTLP/gRPC, the full list of the gRPC retryable status codes can be found in the [gRPC response section](otlp.md#otlpgrpc-response). + +SDKs MAY use the built-in [gRPC Retry](https://github.com/grpc/proposal/blob/master/A6-client-retries.md) mechanism to facilitate exponential back-off. If the built-in gRPC mechanism is used, the following values SHOULD be available for configuration: + +- `maxAttempts`: The maximum number of attempts, including the original request. Must be an integer greater than 1 and less than 6. (The built-in gRPC mechanism treats values greater than 5 as 5.) Defaults to `5`. +- `initialBackoff`: Must be a duration greater than 0. Defaults to `1s` +- `maxBackoff`: Must be a duration greater than 0. Defaults to `5s`. +- `backoffMultiplier` Must be a number greater than 0. Defaults to `1.5`. + +These properties are used to compute the backoff as follows: + +- The initial retry attempt will occur after `random(0, initialBackoff)` +- The `n`-th retry attempt will occur after `random(0, min(initialBackoff*backoffMultiplier**(n-1), maxBackoff))` + +Language SDKs SHOULD have retry configuration and mechanics that are consistent across protocols. For example, if the built-in gRPC Retry mechanism is used for the `grpc` protocol, the `http/protobuf` and `http/json` protocols should expose the same configuration options and compute the backoff duration in the same manner. [otlphttp-req]: otlp.md#otlphttp-request From c1eb940b3df5a2e446cd2205614d24efb0c3628b Mon Sep 17 00:00:00 2001 From: jack-berg Date: Tue, 5 Oct 2021 16:03:03 -0500 Subject: [PATCH 2/3] Remove default values for retry properties. --- specification/protocol/exporter.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/protocol/exporter.md b/specification/protocol/exporter.md index d9eb1c6bc36..325dcf7700c 100644 --- a/specification/protocol/exporter.md +++ b/specification/protocol/exporter.md @@ -66,16 +66,16 @@ For OTLP/HTTP, the errors `408 (Request Timeout)` and `5xx (Server Errors)` are SDKs MAY use the built-in [gRPC Retry](https://github.com/grpc/proposal/blob/master/A6-client-retries.md) mechanism to facilitate exponential back-off. If the built-in gRPC mechanism is used, the following values SHOULD be available for configuration: -- `maxAttempts`: The maximum number of attempts, including the original request. Must be an integer greater than 1 and less than 6. (The built-in gRPC mechanism treats values greater than 5 as 5.) Defaults to `5`. -- `initialBackoff`: Must be a duration greater than 0. Defaults to `1s` -- `maxBackoff`: Must be a duration greater than 0. Defaults to `5s`. -- `backoffMultiplier` Must be a number greater than 0. Defaults to `1.5`. +- `maxAttempts`: The maximum number of attempts, including the original request. Must be an integer greater than 1 and less than 6. +- `initialBackoff`: Must be a duration greater than 0. +- `maxBackoff`: Must be a duration greater than 0. +- `backoffMultiplier` Must be a number greater than 0. -These properties are used to compute the backoff as follows: +SDKs have unspecified default values for these properties. They are used to compute the backoff as follows: - The initial retry attempt will occur after `random(0, initialBackoff)` - The `n`-th retry attempt will occur after `random(0, min(initialBackoff*backoffMultiplier**(n-1), maxBackoff))` -Language SDKs SHOULD have retry configuration and mechanics that are consistent across protocols. For example, if the built-in gRPC Retry mechanism is used for the `grpc` protocol, the `http/protobuf` and `http/json` protocols should expose the same configuration options and compute the backoff duration in the same manner. +Language SDKs SHOULD have retry configuration and mechanics that are consistent across OTLP protocols. For example, if the built-in gRPC Retry mechanism is used for the `grpc` protocol, the `http/protobuf` and `http/json` protocols should expose the same configuration options and compute the backoff duration in the same manner. [otlphttp-req]: otlp.md#otlphttp-request From ec4a4e9d41b9698f345c0d76f1b3b50438fb3827 Mon Sep 17 00:00:00 2001 From: jack-berg Date: Thu, 14 Oct 2021 10:09:09 -0500 Subject: [PATCH 3/3] Reduce scope --- specification/protocol/exporter.md | 14 ++------------ 1 file changed, 2 insertions(+), 12 deletions(-) diff --git a/specification/protocol/exporter.md b/specification/protocol/exporter.md index 325dcf7700c..6353650eccc 100644 --- a/specification/protocol/exporter.md +++ b/specification/protocol/exporter.md @@ -64,18 +64,8 @@ Transient errors MUST be handled with a retry strategy. This retry strategy MUST For OTLP/HTTP, the errors `408 (Request Timeout)` and `5xx (Server Errors)` are defined as transient, detailed information about errors can be found in the [HTTP failures section](otlp.md#failures). For the OTLP/gRPC, the full list of the gRPC retryable status codes can be found in the [gRPC response section](otlp.md#otlpgrpc-response). -SDKs MAY use the built-in [gRPC Retry](https://github.com/grpc/proposal/blob/master/A6-client-retries.md) mechanism to facilitate exponential back-off. If the built-in gRPC mechanism is used, the following values SHOULD be available for configuration: +SDKs MAY use the built-in [gRPC Retry](https://github.com/grpc/proposal/blob/master/A6-client-retries.md) mechanism to facilitate exponential back-off. -- `maxAttempts`: The maximum number of attempts, including the original request. Must be an integer greater than 1 and less than 6. -- `initialBackoff`: Must be a duration greater than 0. -- `maxBackoff`: Must be a duration greater than 0. -- `backoffMultiplier` Must be a number greater than 0. - -SDKs have unspecified default values for these properties. They are used to compute the backoff as follows: - -- The initial retry attempt will occur after `random(0, initialBackoff)` -- The `n`-th retry attempt will occur after `random(0, min(initialBackoff*backoffMultiplier**(n-1), maxBackoff))` - -Language SDKs SHOULD have retry configuration and mechanics that are consistent across OTLP protocols. For example, if the built-in gRPC Retry mechanism is used for the `grpc` protocol, the `http/protobuf` and `http/json` protocols should expose the same configuration options and compute the backoff duration in the same manner. +SDKs SHOULD have retry configuration and mechanics that are consistent across OTLP protocols. For example, if the built-in gRPC Retry mechanism is used for the `grpc` protocol, the `http/protobuf` and `http/json` protocols should expose the same configuration options and compute the backoff duration in the same manner. [otlphttp-req]: otlp.md#otlphttp-request