Skip to content

Commit

Permalink
Add Status to the Tracing section. (open-telemetry#150)
Browse files Browse the repository at this point in the history
* Add Status to the Tracing section.

* Mention that canonical codes follow the GRPC ones.
  • Loading branch information
carlosalberto authored and SergeyKanzhelev committed Jun 21, 2019
1 parent 6a050cf commit 1495cb7
Showing 1 changed file with 118 additions and 0 deletions.
118 changes: 118 additions & 0 deletions specification/tracing-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,12 @@ Table of Content
* [Link creation](#link-creation)
* [GetContext](#getcontext-1)
* [GetAttributes](#getattributes)
* [Status](#status)
* [StatusCanonicalCode](#statuscanonicalcode)
* [Status creation](#status-creation)
* [GetCanonicalCode](#getcanonicalcode)
* [GetDescription](#getdescription)
* [GetIsOk](#getisok)
* [SpanData](#spandata)
* [Constructing SpanData](#constructing-spandata)
* [Getters](#getters)
Expand Down Expand Up @@ -394,6 +400,118 @@ Returns the `SpanContext` of a linked span.
Returns the immutable collection of attributes associated with this `Link`.
Order of attributes is not significant.

## Status

`Status` interface represents the status of a finished `Span`. It's composed of
a canonical code in conjuction with an optional descriptive message.

### StatusCanonicalCode

`StatusCanonicalCode` represents the canonical set of status codes of a finished `Span`, following the [Standard GRPC codes](https://github.com/grpc/grpc/blob/master/doc/statuscodes.md).

#### Ok

The operation completed successfully.

#### Cancelled

The operation was cancelled (typically by the caller).

#### UnknownError

An unknown error.

#### InvalidArgument

Client specified an invalid argument. Note that this differs from `FailedPrecondition`.
`InvalidArgument` indicates arguments that are problematic regardless of the state of the
system.

#### DeadlineExceeded

Deadline expired before operation could complete. For operations that change the state
of the system, this error may be returned even if the operation has completed successfully.

#### NotFound

Some requested entity (e.g., file or directory) was not found.

#### AlreadyExists

Some entity that we attempted to create (e.g., file or directory) already exists.

#### PermissionDenied

The caller does not have permission to execute the specified operation.
`PermissionDenied` must not be used if the caller cannot be
identified (use `Unauthenticated1` instead for those errors).

#### ResourceExhausted

Some resource has been exhausted, perhaps a per-user quota, or perhaps
the entire file system is out of space.

#### FailedPrecondition

Operation was rejected because the system is not in a state required for the operation's
execution.

#### Aborted

The operation was aborted, typically due to a concurrency issue like sequencer check
failures, transaction aborts, etc.

#### OutOfRange

Operation was attempted past the valid range. E.g., seeking or reading past end of file.
Unlike `InvalidArgument`, this error indicates a problem that may be fixed if the system
state changes.

#### Unimplemented

Operation is not implemented or not supported/enabled in this service.

#### InternalError

Internal errors. Means some invariants expected by underlying system has been broken.

#### Unavailable

The service is currently unavailable. This is a most likely a transient condition
and may be corrected by retrying with a backoff.

#### DataLoss

Unrecoverable data loss or corruption.

#### Unauthenticated

The request does not have valid authentication credentials for the operation.

### Status creation

API MUST provide a way to create a new `Status`.

Required parameters

- `StatusCanonicalCode` of this `Status`.

Optional parameters

- Description of this `Status`.

### GetCanonicalCode

Returns the `StatusCanonicalCode` of this `Status`.

### GetDescription

Returns the description of this `Status`.

### GetIsOk

Returns false if this `Status` represents an error, else returns true.

## SpanData

`SpanData` is an immutable and final class. All getters of `SpanData` are thread
Expand Down

0 comments on commit 1495cb7

Please sign in to comment.