Make it possible to indicate partial success in an OTLP export respon…

…se [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

@@ -22,6 +22,8 @@ Full list of differences found in [this compare](https:/open-telemet
 ### Added
 
 * Introduce Scope Attributes. [#395](https:/open-telemetry/opentelemetry-proto/pull/395)
+* Introduce partial success fields in `Export<signal>ServiceResponse`.
+ [#414](https:/open-telemetry/opentelemetry-proto/pull/414)
 
 ### Removed
 

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_<signal>` 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_<signal>` MUST have a value of `0` and
+ // the `error_message` MUST be non-empty.
+ //
+ // A `partial_success` message with an empty value (rejected_<signal> = 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_<signal>` 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;
 }

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_<signal>` 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_<signal>` MUST have a value of `0` and
+ // the `error_message` MUST be non-empty.
+ //
+ // A `partial_success` message with an empty value (rejected_<signal> = 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_<signal>` 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;
 }

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_<signal>` 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_<signal>` MUST have a value of `0` and
+ // the `error_message` MUST be non-empty.
+ //
+ // A `partial_success` message with an empty value (rejected_<signal> = 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_<signal>` 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;
 }