docs: document null and undefined attribute values undefined behavior (…

…#1650)
open-telemetry · Nov 11, 2020 · e78f65e · e78f65e
1 parent 894c8d8
commit e78f65e
Show file tree

Hide file tree

Showing 2 changed files with 9 additions and 1 deletion.
diff --git a/packages/opentelemetry-api/src/trace/attributes.ts b/packages/opentelemetry-api/src/trace/attributes.ts
@@ -18,6 +18,11 @@ export interface Attributes {
   [attributeKey: string]: AttributeValue | undefined;
 }
 
+/**
+ * Attribute values may be any non-nullish primitive value except an object.
+ *
+ * null or undefined attribute values are invalid and will result in undefined behavior.
+ */
 export type AttributeValue =
   | string
   | number

diff --git a/packages/opentelemetry-api/src/trace/span.ts b/packages/opentelemetry-api/src/trace/span.ts
@@ -47,14 +47,17 @@ export interface Span {
    * Sets a single Attribute with the key and value passed as arguments.
    *
    * @param key the key for this attribute.
-   * @param value the value for this attribute.
+   * @param value the value for this attribute. Setting a value null or
+   *              undefined is invalid and will result in undefined behavior.
    */
   setAttribute(key: string, value?: AttributeValue): this;
 
   /**
    * Sets attributes to the span.
    *
    * @param attributes the attributes that will be added.
+   *                   null or undefined attribute values
+   *                   are invalid and will result in undefined behavior.
    */
   setAttributes(attributes: Attributes): this;