forceflush should have a disclaimer about when it is used

open-telemetry · Jul 24, 2023 · 7338434 · 7338434
1 parent dc78006
commit 7338434
Show file tree

Hide file tree

Showing 3 changed files with 20 additions and 16 deletions.
diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md
@@ -285,10 +285,10 @@ it has made to achieve this goal.
 `ForceFlush` SHOULD provide a way to let the caller know whether it succeeded,
 failed or timed out.
 
-`ForceFlush` SHOULD only be called in cases where it is absolutely necessary,
-such as when using some FaaS providers that may suspend the process after an
-invocation, but before the `LogRecordProcessor` exports the
-emitted `LogRecord`s.
+`ForceFlush` SHOULD be documented with a disclaimer stating that it should only
+be called in cases where it is absolutely necessary, such as when using some
+FaaS providers that may suspend the process after an invocation, but before the
+`LogRecordProcessor` exports the emitted `LogRecord`s.
 
 `ForceFlush` SHOULD complete or abort within some timeout. `ForceFlush` can be
 implemented as a blocking API or an asynchronous API which notifies the caller
@@ -401,9 +401,10 @@ soon as possible, preferably before returning from this method.
 `ForceFlush` SHOULD provide a way to let the caller know whether it succeeded,
 failed or timed out.
 
-`ForceFlush` SHOULD only be called in cases where it is absolutely necessary,
-such as when using some FaaS providers that may suspend the process after an
-invocation, but before the exporter exports the `ReadlableLogRecords`.
+`ForceFlush` SHOULD be documented with a disclaimer stating that it should only
+be called in cases where it is absolutely necessary, such as when using some
+FaaS providers that may suspend the process after an invocation, but before the
+ exporter exports the `ReadlableLogRecords`.
 
 `ForceFlush` SHOULD complete or abort within some timeout. `ForceFlush` can be
 implemented as a blocking API or an asynchronous API which notifies the caller

diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md
@@ -1317,9 +1317,10 @@ possible, preferably before returning from this method.
 `ForceFlush` SHOULD provide a way to let the caller know whether it succeeded,
 failed or timed out.
 
-`ForceFlush` SHOULD only be called in cases where it is absolutely necessary,
-such as when using some FaaS providers that may suspend the process after an
-invocation, but before the exporter exports the completed metrics.
+`ForceFlush` SHOULD be documented with a disclaimer stating that it should only
+be called in cases where it is absolutely necessary, such as when using some
+FaaS providers that may suspend the process after an invocation, but before the
+exporter exports the completed metrics.
 
 `ForceFlush` SHOULD complete or abort within some timeout. `ForceFlush` can be
 implemented as a blocking API or an asynchronous API which notifies the caller

diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md
@@ -567,9 +567,10 @@ calls it has made to achieve this goal.
 `ForceFlush` SHOULD provide a way to let the caller know whether it succeeded,
 failed or timed out.
 
-`ForceFlush` SHOULD only be called in cases where it is absolutely necessary,
-such as when using some FaaS providers that may suspend the process after an
-invocation, but before the `SpanProcessor` exports the completed spans.
+`ForceFlush` SHOULD be documented with a disclaimer stating that it should only
+be called in cases where it is absolutely necessary, such as when using some
+FaaS providers that may suspend the process after an invocation, but before the
+`SpanProcessor` exports the completed spans.
 
 `ForceFlush` SHOULD complete or abort within some timeout. `ForceFlush` can be
 implemented as a blocking API or an asynchronous API which notifies the caller
@@ -717,9 +718,10 @@ returning from this method.
 `ForceFlush` SHOULD provide a way to let the caller know whether it succeeded,
 failed or timed out.
 
-`ForceFlush` SHOULD only be called in cases where it is absolutely necessary,
-such as when using some FaaS providers that may suspend the process after an
-invocation, but before the exporter exports the completed spans.
+`ForceFlush` SHOULD be documented with a disclaimer stating that it should only
+be called in cases where it is absolutely necessary, such as when using some
+FaaS providers that may suspend the process after an invocation, but before the
+exporter exports the completed spans.
 
 `ForceFlush` SHOULD complete or abort within some timeout. `ForceFlush` can be
 implemented as a blocking API or an asynchronous API which notifies the caller