From b906f223afbc1055412905bb00d4257765e1e36b Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Tue, 9 Jan 2024 08:56:35 -0800 Subject: [PATCH 1/4] Rewrite span status section and standardize preamble in manual instrumentation (#3694) Co-authored-by: Yuri Shkuro Co-authored-by: Kayla Reopelle (she/her) <87386821+kaylareopelle@users.noreply.github.com> --- content/en/docs/concepts/signals/traces.md | 28 ++++++++++++++----- content/en/docs/instrumentation/go/manual.md | 6 +--- content/en/docs/instrumentation/js/manual.md | 11 +------- content/en/docs/instrumentation/net/manual.md | 8 +----- content/en/docs/instrumentation/php/manual.md | 4 +-- .../en/docs/instrumentation/python/manual.md | 8 +----- .../en/docs/instrumentation/ruby/manual.md | 8 +----- .../en/docs/instrumentation/swift/manual.md | 7 +---- .../instrumentation/span-status-preamble.md | 8 ++++++ 9 files changed, 36 insertions(+), 52 deletions(-) create mode 100644 layouts/shortcodes/docs/instrumentation/span-status-preamble.md diff --git a/content/en/docs/concepts/signals/traces.md b/content/en/docs/concepts/signals/traces.md index 98b8d4b5cb6e..5f5fc10a95f7 100644 --- a/content/en/docs/concepts/signals/traces.md +++ b/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 diff --git a/content/en/docs/instrumentation/go/manual.md b/content/en/docs/instrumentation/go/manual.md index 6a108a334f09..e592deee8586 100644 --- a/content/en/docs/instrumentation/go/manual.md +++ b/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 diff --git a/content/en/docs/instrumentation/js/manual.md b/content/en/docs/instrumentation/js/manual.md index 07ecb768a9d4..39c15d1afcc8 100644 --- a/content/en/docs/instrumentation/js/manual.md +++ b/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 diff --git a/content/en/docs/instrumentation/net/manual.md b/content/en/docs/instrumentation/net/manual.md index 49dddf08df06..295d1f96cd05 100644 --- a/content/en/docs/instrumentation/net/manual.md +++ b/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"); diff --git a/content/en/docs/instrumentation/php/manual.md b/content/en/docs/instrumentation/php/manual.md index fc7091d57f8e..2e96c63f7bd5 100644 --- a/content/en/docs/instrumentation/php/manual.md +++ b/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 diff --git a/content/en/docs/instrumentation/python/manual.md b/content/en/docs/instrumentation/python/manual.md index 132acc301e1f..cfd16f19884f 100644 --- a/content/en/docs/instrumentation/python/manual.md +++ b/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 diff --git a/content/en/docs/instrumentation/ruby/manual.md b/content/en/docs/instrumentation/ruby/manual.md index 04cce7a53447..4aef686eec69 100644 --- a/content/en/docs/instrumentation/ruby/manual.md +++ b/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" diff --git a/content/en/docs/instrumentation/swift/manual.md b/content/en/docs/instrumentation/swift/manual.md index c655308d089d..6b2a1193f91c 100644 --- a/content/en/docs/instrumentation/swift/manual.md +++ b/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() { diff --git a/layouts/shortcodes/docs/instrumentation/span-status-preamble.md b/layouts/shortcodes/docs/instrumentation/span-status-preamble.md new file mode 100644 index 000000000000..34a4465f54bc --- /dev/null +++ b/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. From 7e040a95b4d4d9837e9d782237be395622d1b89d Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 9 Jan 2024 17:23:56 -0500 Subject: [PATCH 2/4] Bump streetsidesoftware/cspell-action from 2 to 5 (#3745) --- .github/workflows/check-spelling.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/check-spelling.yml b/.github/workflows/check-spelling.yml index 8cae1dc4b817..1c247eabffa3 100644 --- a/.github/workflows/check-spelling.yml +++ b/.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: | From 093750555eacf86722ec24b5d0396fdd03683ece Mon Sep 17 00:00:00 2001 From: developersteve Date: Thu, 11 Jan 2024 01:37:19 +1100 Subject: [PATCH 3/4] Delete data/registry/exporter-js-datadog.yml (#3750) --- data/registry/exporter-js-datadog.yml | 13 ------------- 1 file changed, 13 deletions(-) delete mode 100644 data/registry/exporter-js-datadog.yml diff --git a/data/registry/exporter-js-datadog.yml b/data/registry/exporter-js-datadog.yml deleted file mode 100644 index 8d7d4f36c111..000000000000 --- a/data/registry/exporter-js-datadog.yml +++ /dev/null @@ -1,13 +0,0 @@ -title: Datadog Exporter JS -registryType: exporter -isThirdParty: true -language: js -tags: - - Node.js - - exporter - - datadog -repo: https://github.com/DataDog/dd-opentelemetry-exporter-js -license: Apache 2.0 -description: The OpenTelemetry Datadog Exporter for Node.js. -authors: Datadog, Inc. -otVersion: latest From 6811df4d7b8f3856da9c72c9ed520fa16689b944 Mon Sep 17 00:00:00 2001 From: OpenTelemetry Bot <107717825+opentelemetrybot@users.noreply.github.com> Date: Wed, 10 Jan 2024 20:50:12 +0100 Subject: [PATCH 4/4] Update opentelemetry-collector-releases version to 0.92.0 (#3753) --- content/en/docs/collector/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/collector/_index.md b/content/en/docs/collector/_index.md index 2f237708b97d..4b9721bf3a72 100644 --- a/content/en/docs/collector/_index.md +++ b/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 ---