From 200ccff768a29f8bd431e0a4a463da7ed58be557 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Wed, 3 Aug 2022 18:10:23 +0200 Subject: [PATCH] Make it possible to indicate partial success in an OTLP export response [2] (#414) * Make it possible to indicate partial success in an OTLP export response * Update changelog with PR number * PR suggestions * Improve docs around using rejected as 0 to convey warnings * Adapt comments to match recent spec wording changes * Clarify behavior of partial success not set/empty --- CHANGELOG.md | 2 ++ .../collector/logs/v1/logs_service.proto | 33 +++++++++++++++++++ .../metrics/v1/metrics_service.proto | 33 +++++++++++++++++++ .../collector/trace/v1/trace_service.proto | 33 +++++++++++++++++++ 4 files changed, 101 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c2bf9fb8..ab0e97ce6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,8 @@ Full list of differences found in [this compare](https://github.com/open-telemet ### Added * Introduce Scope Attributes. [#395](https://github.com/open-telemetry/opentelemetry-proto/pull/395) +* Introduce partial success fields in `ExportServiceResponse`. + [#414](https://github.com/open-telemetry/opentelemetry-proto/pull/414) ### Removed diff --git a/opentelemetry/proto/collector/logs/v1/logs_service.proto b/opentelemetry/proto/collector/logs/v1/logs_service.proto index cc1162fd8..8260d8aae 100644 --- a/opentelemetry/proto/collector/logs/v1/logs_service.proto +++ b/opentelemetry/proto/collector/logs/v1/logs_service.proto @@ -43,4 +43,37 @@ message ExportLogsServiceRequest { } message ExportLogsServiceResponse { + // The details of a partially successful export request. + // + // If the request is only partially accepted + // (i.e. when the server accepts only parts of the data and rejects the rest) + // the server MUST initialize the `partial_success` field and MUST + // set the `rejected_` with the number of items it rejected. + // + // Servers MAY also make use of the `partial_success` field to convey + // warnings/suggestions to senders even when the request was fully accepted. + // In such cases, the `rejected_` MUST have a value of `0` and + // the `error_message` MUST be non-empty. + // + // A `partial_success` message with an empty value (rejected_ = 0 and + // `error_message` = "") is equivalent to it not being set/present. Senders + // SHOULD interpret it the same way as in the full success case. + ExportLogsPartialSuccess partial_success = 1; +} + +message ExportLogsPartialSuccess { + // The number of rejected log records. + // + // A `rejected_` field holding a `0` value indicates that the + // request was fully accepted. + int64 rejected_log_records = 1; + + // A developer-facing human-readable message in English. It should be used + // either to explain why the server rejected parts of the data during a partial + // success or to convey warnings/suggestions during a full success. The message + // should offer guidance on how users can address such issues. + // + // error_message is an optional field. An error_message with an empty value + // is equivalent to it not being set. + string error_message = 2; } diff --git a/opentelemetry/proto/collector/metrics/v1/metrics_service.proto b/opentelemetry/proto/collector/metrics/v1/metrics_service.proto index a013d2e77..dd48f1ad3 100644 --- a/opentelemetry/proto/collector/metrics/v1/metrics_service.proto +++ b/opentelemetry/proto/collector/metrics/v1/metrics_service.proto @@ -43,4 +43,37 @@ message ExportMetricsServiceRequest { } message ExportMetricsServiceResponse { + // The details of a partially successful export request. + // + // If the request is only partially accepted + // (i.e. when the server accepts only parts of the data and rejects the rest) + // the server MUST initialize the `partial_success` field and MUST + // set the `rejected_` with the number of items it rejected. + // + // Servers MAY also make use of the `partial_success` field to convey + // warnings/suggestions to senders even when the request was fully accepted. + // In such cases, the `rejected_` MUST have a value of `0` and + // the `error_message` MUST be non-empty. + // + // A `partial_success` message with an empty value (rejected_ = 0 and + // `error_message` = "") is equivalent to it not being set/present. Senders + // SHOULD interpret it the same way as in the full success case. + ExportMetricsPartialSuccess partial_success = 1; +} + +message ExportMetricsPartialSuccess { + // The number of rejected data points. + // + // A `rejected_` field holding a `0` value indicates that the + // request was fully accepted. + int64 rejected_data_points = 1; + + // A developer-facing human-readable message in English. It should be used + // either to explain why the server rejected parts of the data during a partial + // success or to convey warnings/suggestions during a full success. The message + // should offer guidance on how users can address such issues. + // + // error_message is an optional field. An error_message with an empty value + // is equivalent to it not being set. + string error_message = 2; } diff --git a/opentelemetry/proto/collector/trace/v1/trace_service.proto b/opentelemetry/proto/collector/trace/v1/trace_service.proto index 75d694294..d6fe67f9e 100644 --- a/opentelemetry/proto/collector/trace/v1/trace_service.proto +++ b/opentelemetry/proto/collector/trace/v1/trace_service.proto @@ -43,4 +43,37 @@ message ExportTraceServiceRequest { } message ExportTraceServiceResponse { + // The details of a partially successful export request. + // + // If the request is only partially accepted + // (i.e. when the server accepts only parts of the data and rejects the rest) + // the server MUST initialize the `partial_success` field and MUST + // set the `rejected_` with the number of items it rejected. + // + // Servers MAY also make use of the `partial_success` field to convey + // warnings/suggestions to senders even when the request was fully accepted. + // In such cases, the `rejected_` MUST have a value of `0` and + // the `error_message` MUST be non-empty. + // + // A `partial_success` message with an empty value (rejected_ = 0 and + // `error_message` = "") is equivalent to it not being set/present. Senders + // SHOULD interpret it the same way as in the full success case. + ExportTracePartialSuccess partial_success = 1; +} + +message ExportTracePartialSuccess { + // The number of rejected spans. + // + // A `rejected_` field holding a `0` value indicates that the + // request was fully accepted. + int64 rejected_spans = 1; + + // A developer-facing human-readable message in English. It should be used + // either to explain why the server rejected parts of the data during a partial + // success or to convey warnings/suggestions during a full success. The message + // should offer guidance on how users can address such issues. + // + // error_message is an optional field. An error_message with an empty value + // is equivalent to it not being set. + string error_message = 2; }