feat(core): Add Scope::SetAttribute(s) APIs

Author: Lms24

packages/core/src/scope.ts

@@ -1,4 +1,5 @@
 /* eslint-disable max-lines */
+import { Attributes, attributeValueToTypedAttributeValue, AttributeValueType, TypedAttributeValue } from './attributes';
 import type { Client } from './client';
 import { DEBUG_BUILD } from './debug-build';
 import { updateSession } from './session';
@@ -46,6 +47,7 @@ export interface ScopeContext {
   extra: Extras;
   contexts: Contexts;
   tags: { [key: string]: Primitive };
+  attributes?: Attributes;
   fingerprint: string[];
   propagationContext: PropagationContext;
 }
@@ -71,6 +73,8 @@ export interface ScopeData {
   breadcrumbs: Breadcrumb[];
   user: User;
   tags: { [key: string]: Primitive };
+  // TODO(v11): Make this a required field (could be subtly breaking if we did it today)
+  attributes?: Attributes;
   extra: Extras;
   contexts: Contexts;
   attachments: Attachment[];
@@ -104,6 +108,9 @@ export class Scope {
   /** Tags */
   protected _tags: { [key: string]: Primitive };
 
+  /** Attributes */
+  protected _attributes: Attributes;
+
   /** Extra */
   protected _extra: Extras;
 
@@ -155,6 +162,7 @@ export class Scope {
     this._attachments = [];
     this._user = {};
     this._tags = {};
+    this._attributes = {};
     this._extra = {};
     this._contexts = {};
     this._sdkProcessingMetadata = {};
@@ -171,6 +179,7 @@ export class Scope {
     const newScope = new Scope();
     newScope._breadcrumbs = [...this._breadcrumbs];
     newScope._tags = { ...this._tags };
+    newScope._attributes = { ...this._attributes };
     newScope._extra = { ...this._extra };
     newScope._contexts = { ...this._contexts };
     if (this._contexts.flags) {
@@ -294,6 +303,59 @@ export class Scope {
     return this.setTags({ [key]: value });
   }
 
+  /**
+   * Sets attributes onto the scope.
+   *
+   * TODO:
+   * Currently, these attributes are not applied to any telemetry data but they will be in the future.
+   *
+   * @param newAttributes - The attributes to set on the scope. You can either pass in key-value pairs, or
+   * an object with a concrete type declaration and an optional unit (if applicable to your attribute).
+   * You can only pass in primitive values or arrays of primitive values.
+   *
+   * @example
+   * ```typescript
+   * scope.setAttributes({
+   *   is_admin: true,
+   *   payment_selection: 'credit_card',
+   *   clicked_products: [130, 554, 292],
+   *   render_duration: { value: 'render_duration', type: 'float', unit: 'ms' },
+   * });
+   * ```
+   */
+  public setAttributes(newAttributes: Record<string, AttributeValueType | TypedAttributeValue>): this {
+    Object.entries(newAttributes).forEach(([key, value]) => {
+      if (typeof value === 'object' && !Array.isArray(value)) {
+        this._attributes[key] = value;
+      } else {
+        this._attributes[key] = attributeValueToTypedAttributeValue(value);
+      }
+    });
+    this._notifyScopeListeners();
+    return this;
+  }
+
+  /**
+   * Sets an attribute onto the scope.
+   *
+   * TODO:
+   * Currently, these attributes are not applied to any telemetry data but they will be in the future.
+   *
+   * @param key - The attribute key.
+   * @param value - the attribute value. You can either pass in a raw value (primitive or array of primitives), or
+   * a typed attribute value object with a concrete type declaration and an optional unit (if applicable to your attribute).
+   *
+   * @example
+   * ```typescript
+   * scope.setAttribute('is_admin', true);
+   * scope.setAttribute('clicked_products', [130, 554, 292]);
+   * scope.setAttribute('render_duration', { value: 'render_duration', type: 'float', unit: 'ms' });
+   * ```
+   */
+  public setAttribute(key: string, value: AttributeValueType | TypedAttributeValue): this {
+    return this.setAttributes({ [key]: value });
+  }
+
   /**
    * Set an object that will be merged into existing extra on the scope,
    * and will be sent as extra data with the event.
@@ -409,9 +471,19 @@ export class Scope {
           ? (captureContext as ScopeContext)
           : undefined;
 
-    const { tags, extra, user, contexts, level, fingerprint = [], propagationContext } = scopeInstance || {};
+    const {
+      tags,
+      attributes,
+      extra,
+      user,
+      contexts,
+      level,
+      fingerprint = [],
+      propagationContext,
+    } = scopeInstance || {};
 
     this._tags = { ...this._tags, ...tags };
+    this._attributes = { ...this._attributes, ...attributes };
     this._extra = { ...this._extra, ...extra };
     this._contexts = { ...this._contexts, ...contexts };
 
@@ -442,6 +514,7 @@ export class Scope {
     // client is not cleared here on purpose!
     this._breadcrumbs = [];
     this._tags = {};
+    this._attributes = {};
     this._extra = {};
     this._user = {};
     this._contexts = {};
@@ -528,6 +601,7 @@ export class Scope {
       attachments: this._attachments,
       contexts: this._contexts,
       tags: this._tags,
+      attributes: this._attributes,
       extra: this._extra,
       user: this._user,
       level: this._level,

packages/core/test/lib/attributes.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+import { attributeValueToTypedAttributeValue } from '../../src/attributes';
+
+describe('attributeValueToTypedAttributeValue', () => {
+  describe('primitive values', () => {
+    it('converts a string value to a typed attribute value', () => {
+      const result = attributeValueToTypedAttributeValue('test');
+      expect(result).toEqual({
+        value: 'test',
+        type: 'string',
+      });
+    });
+
+    it('converts an interger number value to a typed attribute value', () => {
+      const result = attributeValueToTypedAttributeValue(42);
+      expect(result).toEqual({
+        value: 42,
+        type: 'integer',
+      });
+    });
+
+    it('converts a double number value to a typed attribute value', () => {
+      const result = attributeValueToTypedAttributeValue(42.34);
+      expect(result).toEqual({
+        value: 42.34,
+        type: 'double',
+      });
+    });
+
+    it('converts a boolean value to a typed attribute value', () => {
+      const result = attributeValueToTypedAttributeValue(true);
+      expect(result).toEqual({
+        value: true,
+        type: 'boolean',
+      });
+    });
+  });
+
+  describe('arrays', () => {
+    it('converts an array of strings to a typed attribute value', () => {
+      const result = attributeValueToTypedAttributeValue(['foo', 'bar']);
+      expect(result).toEqual({
+        value: ['foo', 'bar'],
+        type: 'string[]',
+      });
+    });
+
+    it('converts an array of integer numbers to a typed attribute value', () => {
+      const result = attributeValueToTypedAttributeValue([1, 2, 3]);
+      expect(result).toEqual({
+        value: [1, 2, 3],
+        type: 'integer[]',
+      });
+    });
+
+    it('converts an array of double numbers to a typed attribute value', () => {
+      const result = attributeValueToTypedAttributeValue([1.1, 2.2, 3.3]);
+      expect(result).toEqual({
+        value: [1.1, 2.2, 3.3],
+        type: 'double[]',
+      });
+    });
+
+    it('converts an array of booleans to a typed attribute value', () => {
+      const result = attributeValueToTypedAttributeValue([true, false, true]);
+      expect(result).toEqual({
+        value: [true, false, true],
+        type: 'boolean[]',
+      });
+    });
+  });
+
+  describe('disallowed value types', () => {
+    it('stringifies mixed float and integer numbers to a string attribute value', () => {
+      const result = attributeValueToTypedAttributeValue([1, 2.2, 3]);
+      expect(result).toEqual({
+        value: '[1,2.2,3]',
+        type: 'string',
+      });
+    });
+
+    it('stringifies an array of mixed types to a string attribute value', () => {
+      // @ts-expect-error - this is not allowed by types but we still test fallback behaviour
+      const result = attributeValueToTypedAttributeValue([1, 'foo', true]);
+      expect(result).toEqual({
+        value: '[1,"foo",true]',
+        type: 'string',
+      });
+    });
+
+    it('stringifies an object value to a string attribute value', () => {
+      // @ts-expect-error - this is not allowed by types but we still test fallback behaviour
+      const result = attributeValueToTypedAttributeValue({ foo: 'bar' });
+      expect(result).toEqual({
+        value: '{"foo":"bar"}',
+        type: 'string',
+      });
+    });
+  });
+});