Centralize attributes definition (#722)

* Centralize attributes definition Signed-off-by: Bogdan Drutu <[email protected]> * Update specification/common/common.md Co-authored-by: Christian Neumüller <[email protected]> * Update specification/common/common.md Co-authored-by: Christian Neumüller <[email protected]> * Update specification/common/common.md Co-authored-by: Christian Neumüller <[email protected]> * Update specification/common/common.md Co-authored-by: Christian Neumüller <[email protected]> * Update specification/common/common.md Co-authored-by: Christian Neumüller <[email protected]> * Update specification/common/common.md Co-authored-by: Christian Neumüller <[email protected]> * Update specification/overview.md Co-authored-by: Christian Neumüller <[email protected]> Co-authored-by: Christian Neumüller <[email protected]>
open-telemetry · Jul 22, 2020 · d2665fd · d2665fd · mkrishna-alt · Mar 11, 2024
1 parent 36a95cd
commit d2665fd
Show file tree

Hide file tree

Showing 4 changed files with 40 additions and 36 deletions.
diff --git a/specification/common/common.md b/specification/common/common.md
@@ -0,0 +1,29 @@
+# Common specification concepts
+
+<details>
+<summary>
+Table of Contents
+</summary>
+
+- [Attributes](#attribute)
+
+</details>
+
+## Attributes
+
+Attributes are a list of zero or more key-value pairs. An `Attribute` MUST have the following properties:
+
+- The attribute key, which MUST be a non-`null` and non-empty string.
+- The attribute value, which is either:
+  - A primitive type: string, boolean, double precision floating point (IEEE 754-1985) or signed 64 bit integer.
+  - An array of primitive type values. The array MUST be homogeneous,
+    i.e. it MUST NOT contain values of different types. For protocols that do
+    not natively support array values such values SHOULD be represented as JSON strings.
+
+`null` values within arrays MUST be preserved as-is (i.e., passed on to span
+processors / exporters as `null`). If exporters do not support exporting `null`
+values, they MAY replace those values by 0, `false`, or empty strings.
+This is required for map/dictionary structures represented as two arrays with
+indices that are kept in sync (e.g., two attributes `header_keys` and `header_values`,
+both containing an array of strings to represent a mapping
+`header_keys[i] -> header_values[i]`).
diff --git a/specification/overview.md b/specification/overview.md
@@ -54,11 +54,8 @@ Each **Span** encapsulates the following state:
 
 - An operation name
 - A start and finish timestamp
-- A set of zero or more key:value **Attributes**. The keys must be strings. The
-  values may be strings, bools, or numeric types.
-- A set of zero or more **Events**, each of which is itself a key:value map
-  paired with a timestamp. The keys must be strings, though the values may be of
-  the same types as Span **Attributes**.
+- [**Attributes**](./common/common.md#attributes): A list of key-value pairs.
+- A set of zero or more **Events**, each of which is itself a tuple (timestamp, name, [**Attributes**](./common/common.md#attributes)). The name must be strings.
 - Parent's **Span** identifier.
 - [**Links**](#links-between-spans) to zero or more causally-related **Spans**
   (via the **SpanContext** of those related **Spans**).
@@ -300,6 +297,4 @@ Span attributes.
 * [Metrics Conventions](metrics/semantic_conventions/README.md)
 
 The type of the attribute SHOULD be specified in the semantic convention
-for that attribute. Array values are allowed for attributes. For
-protocols that do not natively support array values such values MUST be
-represented as JSON strings.
+for that attribute. See more details about [Attributes](./common/common.md#attributes).
diff --git a/specification/resource/sdk.md b/specification/resource/sdk.md
@@ -30,14 +30,13 @@ The SDK must support two ways to instantiate new resources. Those are:
 
 ### Create
 
-The interface MUST provide a way to create a new resource, from a collection of
-attributes. Examples include a factory method or a constructor for a resource
+The interface MUST provide a way to create a new resource, from [`Attributes`](../common/common.md#attributes).
+Examples include a factory method or a constructor for a resource
 object. A factory method is recommended to enable support for cached objects.
 
 Required parameters:
 
-- a collection of name/value attributes, where name is a string and value can be one
-  of: string, int64, double, bool.
+- [`Attributes`](../common/common.md#attributes)
 
 ### Merge
 

diff --git a/specification/trace/api.md b/specification/trace/api.md
@@ -203,7 +203,7 @@ the entire operation and, optionally, one or more sub-spans for its sub-operatio
 - A [`SpanKind`](#spankind)
 - A start timestamp
 - An end timestamp
-- [`Attribute`s](#set-attributes), a collection of key-value pairs
+- [`Attributes`](../common/common.md#attributes)
 - A list of [`Link`s](#add-links) to other `Span`s
 - A list of timestamped [`Event`s](#add-events)
 - A [`Status`](#set-status).
@@ -282,8 +282,7 @@ The API MUST accept the following parameters:
   See [Determining the Parent Span from a Context](#determining-the-parent-span-from-a-context)
   for guidance on `Span` parenting from explicit and implicit `Context`s.
 - [`SpanKind`](#spankind), default to `SpanKind.Internal` if not specified.
-- `Attribute`s - A collection of key-value pairs, with the same semantics as
-  the ones settable with [Span::SetAttributes](#set-attributes). Additionally,
+- [`Attributes`](../common/common.md#attributes). Additionally,
   these attributes may be used to make a sampling decision as noted in [sampling
   description](sdk.md#sampling). An empty collection will be assumed if
   not specified.
@@ -335,8 +334,7 @@ description](../overview.md#links-between-spans).
 A `Link` is defined by the following properties:
 
 - (Required) `SpanContext` of the `Span` to link to.
-- (Optional) One or more `Attribute`s with the same restrictions as defined for
-  [Span Attributes](#set-attributes).
+- (Optional) One or more `Attribute`s as defined [here](../).
 
 The `Link` SHOULD be an immutable type.
 
@@ -394,15 +392,7 @@ propagators.
 
 #### Set Attributes
 
-A `Span` MUST have the ability to set attributes associated with it.
-
-An `Attribute` is defined by the following properties:
-
-- (Required) The attribute key, which MUST be a non-`null` and non-empty string.
-- (Required) The attribute value, which is either:
-  - A primitive type: string, boolean or numeric.
-  - An array of primitive type values. The array MUST be homogeneous,
-    i.e. it MUST NOT contain values of different types.
+A `Span` MUST have the ability to set [`Attributes`](../common/common.md#attributes) associated with it.
 
 The Span interface MUST provide:
 
@@ -421,14 +411,6 @@ that `SetAttribute` call had never been made.
 As an exception to this, if overwriting of values is supported, this results in
 clearing the previous value and dropping the attribute key from the set of attributes.
 
-`null` values within arrays MUST be preserved as-is (i.e., passed on to span
-processors / exporters as `null`). If exporters do not support exporting `null`
-values, they MAY replace those values by 0, `false`, or empty strings.
-This is required for map/dictionary structures represented as two arrays with
-indices that are kept in sync (e.g., two attributes `header_keys` and `header_values`,
-both containing an array of strings to represent a mapping
-`header_keys[i] -> header_values[i]`).
-
 Note that the OpenTelemetry project documents certain ["standard
 attributes"](semantic_conventions/README.md) that have prescribed semantic meanings.
 
@@ -440,8 +422,7 @@ with the moment when they are added to the `Span`.
 An `Event` is defined by the following properties:
 
 - (Required) Name of the event.
-- (Optional) One or more `Attribute`s with the same restrictions as defined for
-  [Span Attributes](#set-attributes).
+- (Optional) [`Attributes`](../common/common.md#attributes).
 - (Optional) Timestamp for the event.
 
 The `Event` SHOULD be an immutable type.