From 02944233ec28133c92516e137e46fef71026f6bb Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 4 Nov 2020 11:52:46 -0500 Subject: [PATCH] docs: document null and undefined attribute values undefined behavior --- packages/opentelemetry-api/src/trace/attributes.ts | 5 +++++ packages/opentelemetry-api/src/trace/span.ts | 5 ++++- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/packages/opentelemetry-api/src/trace/attributes.ts b/packages/opentelemetry-api/src/trace/attributes.ts index ea45f96131..f892f2491a 100644 --- 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 index 59cafea2df..a6c968c4f3 100644 --- a/packages/opentelemetry-api/src/trace/span.ts +++ b/packages/opentelemetry-api/src/trace/span.ts @@ -47,7 +47,8 @@ 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; @@ -55,6 +56,8 @@ export interface Span { * 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;