diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 1ea1e4e0631..6bf1f6c2812 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -36,6 +36,7 @@ Table of Contents * [GetCanonicalCode](#getcanonicalcode) * [GetDescription](#getdescription) * [GetIsOk](#getisok) +* [SpanKind](#spankind) @@ -224,10 +225,11 @@ options for newly created `Span`s. The API SHOULD require the caller to provide: - The operation name -- The parent span, and whether the new `Span` should be a root `Span`. +- The parent span, and whether the new `Span` should be a root `Span` The API MUST allow users to provide the following properties, which SHOULD be empty by default: +- [`SpanKind`](#spankind) - `Attribute`s - similar API with [Span::SetAttributes](#set-attributes) - `Link`s - see API definition [here](#add-links) - `Start timestamp` @@ -464,3 +466,27 @@ Returns the description of this `Status`. ### GetIsOk Returns false if this `Status` represents an error, else returns true. + +## SpanKind + +Depending on the `Span` position in a `Trace` and application components +boundaries, it can play a different role. This role often defines how `Span` +will be processed and visualized by various backends. So it is important to +record this "hint" whenever possible to the best of the caller's knowledge. + +These are the possible SpanKinds: + +* `INTERNAL` Default value. Indicates that the span represents an internal + operation within an application, as opposed to an operations happening at the + boundaries. +* `SERVER` Indicates that the span covers server-side handling of an RPC or + other remote request. +* `CLIENT` Indicates that the span describes a request to some remote service. +* `PRODUCER` Indicates that the span describes a producer sending a message to a + broker. Unlike client and server, there is often no direct critical path + latency relationship between producer and consumer spans. A `Producer` span ends + when the message was accepted by the broker while the logical processing of the + message might span a much longer time. +* `CONSUMER` Indicates that the span describes a consumer receiving a message from + a broker. As for the `PRODUCER` kind, there is often no direct critical + path latency relationship between producer and consumer spans.