merge main

Signed-off-by: svrnm <[email protected]>

.github/workflows/check-spelling.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: streetsidesoftware/cspell-action@v2
+      - uses: streetsidesoftware/cspell-action@v5
         with:
           # Files should be consistent with check:spelling files
           files: |

content/en/docs/collector/_index.md

@@ -3,7 +3,7 @@ title: Collector
 description: Vendor-agnostic way to receive, process and export telemetry data.
 aliases: [collector/about]
 cascade:
-  vers: 0.91.0
+  vers: 0.92.0
 weight: 10
 ---
 

content/en/docs/concepts/signals/traces.md

@@ -289,17 +289,31 @@ another.
 
 ### Span Status
 
-A status will be attached to a span. Typically, you will set a span status when
-there is a known error in the application code, such as an exception. A Span
-Status will be tagged as one of the following values:
+Each span has a status. The three possible values are:
 
 - `Unset`
-- `Ok`
 - `Error`
+- `Ok`
 
-When an exception is handled, a Span status can be set to Error. Otherwise, a
-Span status is in the Unset state. By setting a Span status to Unset, the
-back-end that processes spans can now assign a final status.
+The default value is `Unset`. A span status that is `Unset` means that the
+operation it tracked successfully completed without an error.
+
+When a span status is `Error`, then that means some error ocurred in the
+operation it tracks. For example, this could be due to an HTTP 500 error on a
+server handling a request.
+
+When a span status is `Ok`, then that means the span was explicitly marked as
+error-free by the developer of an application. Although this is unintuitive,
+it's not required to set a span status as `Ok` when a span is known to have
+completed without error, as this is covered by `Unset`. What `Ok` does is
+represent an unambiguous "final call" on the status of a span that has been
+explicitly set by a user. This is helpful in any situation where a developer
+wishes for there to be no other interpretation of a span other than
+"successful".
+
+To reiterate: `Unset` represents a span that completed without an error. `Ok`
+represents when a developer explicitly marks a span as successful. In most
+cases, it is not necessary to explicitly mark a span as `Ok`.
 
 ### Span Kind
 

content/en/docs/instrumentation/go/manual.md

@@ -223,8 +223,7 @@ span.AddEvent("Cancelled wait due to external signal", trace.WithAttributes(attr
 
 ### Set span status
 
-A status can be set on a span, typically used to specify that there was an error
-in the operation a span is tracking - .`Error`.
+{{% docs/instrumentation/span-status-preamble %}}
 
 ```go
 import (
@@ -241,9 +240,6 @@ if err != nil {
 }
 ```
 
-By default, the status for all spans is `Unset`. In rare cases, you may also
-wish to set the status to `Ok`. This should generally not be necessary, though.
-
 ### Record errors
 
 If you have an operation that failed and you wish to capture the error it

content/en/docs/instrumentation/js/manual.md

@@ -1011,11 +1011,7 @@ const someFunction = (spanToLinkFrom) => {
 
 ### Span Status
 
-A [status](/docs/concepts/signals/traces/#span-status) can be set on a span,
-typically used to specify that a span has not completed successfully -
-`SpanStatusCode.ERROR`.
-
-The status can be set at any time before the span is finished:
+{{% docs/instrumentation/span-status-preamble %}}
 
 {{< tabpane text=true >}} {{% tab TypeScript %}}
 
@@ -1061,11 +1057,6 @@ tracer.startActiveSpan('app.doWork', (span) => {
 
 {{% /tab %}} {{< /tabpane >}}
 
-By default, the status for all spans is `Unset` rather than `Ok`. It is
-typically the job of another component in your telemetry pipeline to interpret
-the `Unset` status of a span, so it's best not to override this unless you're
-explicitly tracking an error.
-
 ### Recording exceptions
 
 It can be a good idea to record exceptions when they happen. It's recommended to

content/en/docs/instrumentation/net/manual.md

@@ -364,13 +364,7 @@ using var anotherActivity =
 
 ### Set Activity status
 
-A [status](/docs/concepts/signals/traces/#span-status) can be set on an
-activity, typically used to specify that an activity has not completed
-successfully - `ActivityStatusCode.Error`. In rare scenarios, you could override
-the `Error` status with `Ok`, but don't set `Ok` on successfully-completed
-spans.
-
-The status can be set at any time before the span is finished:
+{{% docs/instrumentation/span-status-preamble %}}
 
 ```csharp
 using var myActivity = MyActivitySource.StartActivity("SayHello");

content/en/docs/instrumentation/php/manual.md

@@ -293,9 +293,7 @@ For more details how to read context from remote processes, see
 
 ### Set span status and record exceptions
 
-A [status](/docs/concepts/signals/traces/#span-status) can be set on a
-[span](/docs/concepts/signals/traces/#spans), typically used to specify that a
-span has not completed successfully - `SpanStatus::ERROR`.
+{{% docs/instrumentation/span-status-preamble %}}
 
 It can be a good idea to record exceptions when they happen. It's recommended to
 do this in conjunction with

content/en/docs/instrumentation/python/manual.md

@@ -207,13 +207,7 @@ with tracer.start_as_current_span("span-2", links=[link_from_span_1]):
 
 ### Set span status
 
-A [status](/docs/concepts/signals/traces/#span-status) can be set on a
-[span](/docs/concepts/signals/traces/#spans), typically used to specify that a
-span has not completed successfully - `StatusCode.ERROR`. In rare scenarios, you
-could override the Error status with `StatusCode.OK`, but don’t set
-`StatusCode.OK` on successfully-completed spans.
-
-The status can be set at any time before the span is finished:
+{{% docs/instrumentation/span-status-preamble %}}
 
 ```python
 from opentelemetry import trace

content/en/docs/instrumentation/ruby/manual.md

@@ -269,13 +269,7 @@ link = OpenTelemetry::Trace::Link.new(span_to_link_from.context, attributes: { "
 
 ### Set span status
 
-A [status](/docs/concepts/signals/traces#span-status) can be set on a
-[span](/docs/concepts/signals/traces#spans), typically used to specify that a
-span has not completed successfully - StatusCode.ERROR. In rare scenarios, you
-could override the Error status with StatusCode.OK, but don’t set StatusCode.OK
-on successfully-completed spans.
-
-The status can be set at any time before the span is finished:
+{{% docs/instrumentation/span-status-preamble %}}
 
 ```ruby
 require "opentelemetry/sdk"

content/en/docs/instrumentation/swift/manual.md

@@ -168,12 +168,7 @@ span.addEvent(name: "computation complete", attributes: attributes)
 
 ### Setting Span Status
 
-A [status](/docs/concepts/signals/traces/#span-status) can be set on a span,
-typically used to specify that a span has not completed successfully -
-`SpanStatus.Error`. In rare scenarios, you could override the Error status with
-OK, but don’t set OK on successfully-completed spans.
-
-The status can be set at any time before the span is finished:
+{{% docs/instrumentation/span-status-preamble %}}
 
 ```swift
 func myFunction() {

layouts/shortcodes/docs/instrumentation/span-status-preamble.md

@@ -0,0 +1,8 @@
+A [Status](/docs/concepts/signals/traces/#span-status) can be set on a
+[Span](/docs/concepts/signals/traces/#spans), typically used to specify that a
+Span has not completed successfully - `Error`. By default, all spans are
+`Unset`, which means a span completed without error. The `Ok` status is reserved
+for when you need to explicitly mark a span as successful rather than stick with
+the default of `Unset` (i.e., "without error").
+
+The status can be set at any time before the span is finished.