Specify error.type on OpenTelemetry command spans

ExportXMLWordPrintableJSON

    • Type: Task
    • Resolution: Unresolved
    • Priority: Minor - P4
    • None
    • Component/s: Observability
    • None
    • Needed
    • Hide

      Summary of necessary driver changes

      • Add `error.type` (string) to command spans: MUST set it when the command fails, MUST NOT set it when the command succeeds, and SHOULD keep the cardinality of values low.
      • Value: SHOULD match `db.response.status_code` when the command failed with a server error. Otherwise, SHOULD be the name of the exception class associated with that command's failure, whether or not the operation ultimately raises it to the application (a retry of the same operation may still succeed).
      • Operation spans: MUST NOT carry `error.type` when the operation succeeds, even if a command within it failed. MUST carry it when the operation itself fails; the value SHOULD be the name of the exception class raised to the application, matching the span's `exception.type`.

      Commits for syncing spec/prose tests
      (and/or refer to an existing language POC if needed)

      • Spec merge commit: https://github.com/mongodb/specifications/commit/9cfe388c7d2ce1e02b24b53606e97ce7b73ebb7d (PR mongodb/specifications#1974)
      • New unified fixture source/open-telemetry/tests/operation/error_type.yml (+ generated error_type.json) covering: a server error, a connection failure falling back to the class name, a successful command, a failed retried command whose retry succeeds, and a failed retried non-server command whose exception never reaches the application.
      • New prose tests 5 and 6 in source/open-telemetry/tests/README.md (former tests 5-7 renumbered to 7-9), asserting `error.type` equals `exception.type` where the unified fixture cannot compare two observed attributes.
      • Python POC: https://github.com/mongodb/mongo-python-driver/pull/3000 (PYTHON-6045).

      Context for other referenced/linked tickets

      • Purely additive to other tickets in the Client Side Tracing epic.
      Show
      Summary of necessary driver changes Add `error.type` (string) to command spans: MUST set it when the command fails, MUST NOT set it when the command succeeds, and SHOULD keep the cardinality of values low. Value: SHOULD match `db.response.status_code` when the command failed with a server error. Otherwise, SHOULD be the name of the exception class associated with that command's failure, whether or not the operation ultimately raises it to the application (a retry of the same operation may still succeed). Operation spans: MUST NOT carry `error.type` when the operation succeeds, even if a command within it failed. MUST carry it when the operation itself fails; the value SHOULD be the name of the exception class raised to the application, matching the span's `exception.type`. Commits for syncing spec/prose tests (and/or refer to an existing language POC if needed) Spec merge commit: https://github.com/mongodb/specifications/commit/9cfe388c7d2ce1e02b24b53606e97ce7b73ebb7d (PR mongodb/specifications#1974) New unified fixture source/open-telemetry/tests/operation/error_type.yml (+ generated error_type.json) covering: a server error, a connection failure falling back to the class name, a successful command, a failed retried command whose retry succeeds, and a failed retried non-server command whose exception never reaches the application. New prose tests 5 and 6 in source/open-telemetry/tests/README.md (former tests 5-7 renumbered to 7-9), asserting `error.type` equals `exception.type` where the unified fixture cannot compare two observed attributes. Python POC: https://github.com/mongodb/mongo-python-driver/pull/3000 ( PYTHON-6045 ). Context for other referenced/linked tickets Purely additive to other tickets in the Client Side Tracing epic.
    • $i18n.getText("admin.common.words.hide")
      Key Status/Resolution FixVersion
      CDRIVER-6434 Backlog
      CXX-3561 Backlog
      CSHARP-6196 Backlog
      GODRIVER-4100 Backlog
      JAVA-6289 Backlog
      NODE-7777 Backlog
      PYTHON-6045 In Code Review
      PHPLIB-1934 Backlog
      RUBY-3945 Ready for Work
      RUST-2480 Investigating
      $i18n.getText("admin.common.words.show")
      #scriptField, #scriptField *{ border: 1px solid black; } #scriptField{ border-collapse: collapse; } #scriptField td { text-align: center; /* Center-align text in table cells */ } #scriptField td.key { text-align: left; /* Left-align text in the Key column */ } #scriptField a { text-decoration: none; /* Remove underlines from links */ border: none; /* Remove border from links */ } /* Add green background color to cells with FixVersion */ #scriptField td.hasFixVersion { background-color: #00FF00; /* Green color code */ } #scriptField td.willNotDo { background-color: #FF0000; /* Red color code */ } /* Center-align the first row headers */ #scriptField th { text-align: center; } Key Status/Resolution FixVersion CDRIVER-6434 Backlog CXX-3561 Backlog CSHARP-6196 Backlog GODRIVER-4100 Backlog JAVA-6289 Backlog NODE-7777 Backlog PYTHON-6045 In Code Review PHPLIB-1934 Backlog RUBY-3945 Ready for Work RUST-2480 Investigating

      Specify error.type on OpenTelemetry command spans

      Summary

      The spec defines db.response.status_code on command spans but not error.type, which the technical design lists alongside it at the same requirement level. Leaving it out was deliberate, because it duplicates exception.type. However the two are different kinds of thing: exception.type is an attribute on the exception event, while error.type is a span attribute. Following the OpenTelemetry semantic conventions verbatim means adding error.type and accepting that duplication.

      Motivation

      Who is the affected end user?

      Driver teams implementing the spec, and application developers who filter or aggregate traces by error class.

      How does this affect the end user?

      error.type is the dimension OpenTelemetry backends group and alert on for failures. Carried only as an exception-event attribute, it cannot be queried at the span level. Drivers that emit it anyway have no shared definition of its value, so the same failure is labelled differently per language.

      How likely is it that this problem or use case will occur?

      Every failed command.

      If the problem does occur, what are the consequences and how severe are they?

      Moderate. No data or availability risk. Failure dashboards and alerting behave differently per driver, and a driver that adds the attribute later changes the shape of its traces.

      Is this issue urgent?

      No.

      Is this ticket required by a downstream team?

      No.

      Is this ticket only for tests?

      No. The attribute and its value have to be specified; a test alone would make one reading normative.

      Acceptance Criteria

      • The Command Span Attributes table lists error.type as a string, required if an error happens, matching how db.response.status_code is listed.
      • The spec states the value: error.type SHOULD match db.response.status_code when the command failed with a server error, and otherwise SHOULD be the class name of the exception.
      • The spec states that error.type MUST NOT be set when the command succeeds, and SHOULD have a low number of distinct values, per the semantic conventions.
      • The spec states that error.type is a span attribute that deliberately duplicates information carried by exception.type on the exception event, and why: backends query the span dimension rather than the event.
      • The spec states whether error.type applies to operation spans as well as command spans.
      • A test covers a failing command carrying the attribute. In the server-error case the value is assertable, since it matches db.response.status_code; in the non-server-error case it is language specific, so only presence and type can be asserted.
      • open-telemetry.md has a dated changelog entry.

            Assignee:
            Steve Silvester
            Reporter:
            Steve Silvester
            Nabil Hachicha Nabil Hachicha
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Created:
              Updated: