Add setStatus in Span

opentelemetry-api/src/opentelemetry/trace/__init__.py

@@ -65,8 +65,23 @@
 import typing
 from contextlib import contextmanager
 
+from opentelemetry.trace.status import Status, StatusCanonicalCode
 from opentelemetry.util import loader, types
 
+__all__ = [
+    "Status",
+    "StatusCanonicalCode",
+    "Link",
+    "Event",
+    "SpanKind",
+    "Span",
+    "SpanContext",
+    "TraceOptions",
+    "TraceState",
+    "DefaultSpan",
+    "Tracer",
+]
+
 # TODO: quarantine
 ParentSpan = typing.Optional[typing.Union["Span", "SpanContext"]]
 
@@ -226,6 +241,11 @@ def is_recording_events(self) -> bool:
         events with the add_event operation and attributes using set_attribute.
         """
 
+    def set_status(self, status: Status) -> None:
+        """Sets the Status of the Span. If used, this will override the default
+        Span status, which is OK.
+        """
+
 
 class TraceOptions(int):
     """A bitmask that represents options specific to the trace.

opentelemetry-api/src/opentelemetry/trace/status.py

@@ -0,0 +1,168 @@
+# Copyright 2019, OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import enum
+import typing
+
+
+class StatusCanonicalCode(enum.Enum):
+    """Represents the canonical set of status codes of a finished Span."""
+
+    # pylint: disable=pointless-string-statement
+    """Not an error, returned on success.
+    """
+    OK = 0
+
+    """The operation was cancelled, typically by the caller. """
+    CANCELLED = 1
+
+    """Unknown error. For example, this error may be returned when a Status
+    value received from another address space belongs to an error space that
+    is not known in this address space. Also errors raised by APIs that do
+    not return enough error information may be converted to this error.
+    """
+    UNKNOWN = 2
+
+    """The client specified an invalid argument. Note that this differs from
+    FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are
+    problematic regardless of the state of the system
+    (e.g., a malformed file name).
+    """
+    INVALID_ARGUMENT = 3
+
+    """The deadline expired before the operation could complete. For
+    operations that change the state of the system, this error may be
+    returned even if the operation has completed successfully. For example,
+    a successful response from a server could have been delayed long
+    """
+    DEADLINE_EXCEEDED = 4
+
+    """Some requested entity (e.g., file or directory) was not found.
+    Note to server developers: if a request is denied for an entire class of
+    users, such as gradual feature rollout or undocumented whitelist, NOT_FOUND
+    may be used. If a request is denied for some users within a class of users,
+    such as user-based access control, PERMISSION_DENIED must be used.
+    """
+    NOT_FOUND = 5
+
+    """The entity that a client attempted to create (e.g., file or directory)
+    already exists."""
+    ALREADY_EXISTS = 6
+
+    """The caller does not have permission to execute the specified operation.
+    PERMISSION_DENIED must not be used for rejections caused by exhausting some
+    resource (use RESOURCE_EXHAUSTED instead for those errors).PERMISSION_DENIED
+    must not be used if the caller can not be identified (use UNAUTHENTICATED
+    instead for those errors). This error code does not imply the request is
+    valid or the requested entity exists or satisfies other pre-conditions.
+    """
+    PERMISSION_DENIED = 7
+
+    """Some resource has been exhausted, perhaps a per-user quota, or perhaps
+    the entire file system is out of space.
+    """
+    RESOURCE_EXHAUSTED = 8
+
+    """The operation was rejected because the system is not in a state required
+    for the operation's execution. For example, the directory to be deleted is
+    non-empty, an rmdir operation is applied to a non-directory, etc. Service
+    implementors can use the following guidelines to decide between
+    FAILED_PRECONDITION, ABORTED, and UNAVAILABLE: (a) Use UNAVAILABLE if the
+    client can retry just the failing call. (b) Use ABORTED if the client should
+    retry at a higher level (e.g., when a client-specified test-and-set fails,
+    indicating the client should restart a read-modify-write sequence). (c)
+    Use FAILED_PRECONDITION if the client should not retry until the system state
+    has been explicitly fixed. E.g., if an "rmdir" fails because the directory is
+    non-empty, FAILED_PRECONDITION should be returned since the client should not
+    retry unless the files are deleted from the directory.
+    """
+    FAILED_PRECONDITION = 9
+
+    """The operation was aborted, typically due to a concurrency issue such as a
+    sequencer check failure or transaction abort. See the guidelines above for
+    deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE."""
+    ABORTED = 10
+
+    """The operation was attempted past the valid range. E.g., seeking or reading
+    past end-of-file. Unlike INVALID_ARGUMENT, this error indicates a problem that
+    may be fixed if the system state changes. For example, a 32-bit file system
+    will generate INVALID_ARGUMENT if asked to read at an offset that is not in
+    the range [0,2^32-1],but it will generate OUT_OF_RANGE if asked to read from
+    an offset past the current file size. There is a fair bit of overlap between
+    FAILED_PRECONDITION and OUT_OF_RANGE. We recommend using OUT_OF_RANGE
+    (the more specific error) when it applies so that callers who are iterating
+    through a space can easily look for an OUT_OF_RANGE error to detect when they
+    are done.
+    """
+    OUT_OF_RANGE = 11
+
+    """The operation is not implemented or is not supported/enabled in this
+    service."""
+    UNIMPLEMENTED = 12
+
+    """Internal errors. This means that some invariants expected by the
+    underlying system have been broken. This error code is reserved for
+    serious errors.
+    """
+    INTERNAL = 13
+
+    """The service is currently unavailable. This is most likely a transient
+    condition, which can be corrected by retrying with a backoff.
+    Note that it is not always safe to retry non-idempotent operations.
+    """
+    UNAVAILABLE = 14
+
+    """Unrecoverable data loss or corruption."""
+    DATA_LOSS = 15
+
+    """The request does not have valid authentication credentials for the
+    operation.
+    """
+    UNAUTHENTICATED = 16
+
+
+class Status:
+    """Represents the status of a finished Span
+
+    Args:
+        canonical_code: Represents the canonical set of status codes of a
+        finished Span
+        description: Description of the Status.
+    """
+
+    def __init__(
+        self,
+        canonical_code: "StatusCanonicalCode" = StatusCanonicalCode.OK,
+        description: typing.Optional[str] = None,
+    ):
+        self.code = canonical_code
+        self.desc = description
+
+    @property
+    def canonical_code(self) -> StatusCanonicalCode:
+        """StatusCanonicalCode represents the canonical set of status codes
+        of a finished Span.
+        """
+        return self.code
+
+    @property
+    def description(self) -> typing.Optional[str]:
+        """Status description"""
+        return self.desc
+
+    @property
+    def is_ok(self) -> bool:
+        """Returns false if this Status represents an error, else
+        returns true"""
+        return self.canonical_code == StatusCanonicalCode.OK

opentelemetry-sdk/src/opentelemetry/sdk/trace/__init__.py

@@ -143,6 +143,7 @@ def __init__(
         self.kind = kind
 
         self.span_processor = span_processor
+        self.status = trace_api.Status()
         self._lock = threading.Lock()
 
         if attributes is None:
@@ -285,6 +286,9 @@ def update_name(self, name: str) -> None:
     def is_recording_events(self) -> bool:
         return True
 
+    def set_status(self, status: trace_api.Status) -> None:
+        self.status = status
+
 
 def generate_span_id() -> int:
     """Get a new random span ID.

opentelemetry-sdk/tests/trace/test_trace.py

@@ -235,6 +235,20 @@ def test_start_span(self):
         span.start()
         self.assertEqual(start_time, span.start_time)
 
+        # default status
+        self.assertTrue(span.status.is_ok)
+        self.assertEqual(
+            span.status.canonical_code, trace_api.StatusCanonicalCode.OK
+        )
+        self.assertIs(span.status.description, None)
+
+        # status
+        new_status = trace_api.Status(
+            trace_api.StatusCanonicalCode.CANCELLED, "Test description"
+        )
+        span.set_status(new_status)
+        self.assertEqual(span.status, new_status)
+
     def test_span_override_start_and_end_time(self):
         """Span sending custom start_time and end_time values"""
         span = trace.Span("name", mock.Mock(spec=trace_api.SpanContext))