Signal Attributes

Signal attributes are custom key-value pairs that are automatically included with every telemetry signal (spans, logs, events) transmitted by the SDK. They provide a way to add contextual information to all telemetry data.

Critical Signal Attribute Behavior:

• Attributes persist across page loads within the same session
• Attributes are included with all signals (spans, logs, events) after being set
• Attributes are stored in browser storage; storage unavailability prevents persistence
• Attributes are cleared when session expires or is terminated
• Attributes set before init() may be queued or lost if SDK initialization fails
• Adding an attribute with the same name overwrites the previous value

Capabilities

Add Signal Attribute

Adds a signal attribute to be transmitted with every signal.

/**
 * Adds a signal attribute to be transmitted with every signal
 * @param name - The attribute name
 * @param value - The attribute value
 * @throws No errors thrown; invalid values may be ignored
 */
function addSignalAttribute(name: string, value: AttributeValueType | AnyValue): void;

Usage Examples:

import { addSignalAttribute } from "@dash0/sdk-web";

// Add string attribute
addSignalAttribute("environment", "production");

// Add numeric attribute
addSignalAttribute("version.number", 1.2);

// Add boolean attribute
addSignalAttribute("feature.enabled", true);

// Add array attribute
addSignalAttribute("supported.locales", ["en", "es", "fr"]);

// Add object attribute
addSignalAttribute("config", {
  theme: "dark",
  notifications: true,
});

For IIFE (script tag) usage:

dash0("addSignalAttribute", "environment", "production");
dash0("addSignalAttribute", "version.number", 1.2);

Note: If you need to ensure attributes are included with signals transmitted on initial page load, use the additionalSignalAttributes property in the init() call instead:

import { init } from "@dash0/sdk-web";

init({
  serviceName: "my-website",
  endpoint: { url: "...", authToken: "..." },
  additionalSignalAttributes: {
    "environment": "production",
    "version.number": 1.2,
  },
});

Critical Behavior:

• Attributes persist across page loads within the same session
• Attributes are included with all signals (spans, logs, events) after being set
• Adding an attribute with the same name overwrites the previous value
• Attributes are stored in browser storage and persist across page loads
• If SDK is not initialized, attributes may be queued or lost
• Attributes set via additionalSignalAttributes in init() are available immediately
• Invalid attribute values may be ignored or converted
• Very large attribute values may cause storage quota issues

Remove Signal Attribute

Removes a previously added signal attribute.

/**
 * Removes a previously added signal attribute
 * @param name - The attribute name to remove
 * @throws No errors thrown; removing non-existent attribute is a no-op
 */
function removeSignalAttribute(name: string): void;

Usage Examples:

import { removeSignalAttribute } from "@dash0/sdk-web";

// Remove an attribute
removeSignalAttribute("environment");

For IIFE (script tag) usage:

dash0("removeSignalAttribute", "environment");

Critical Behavior:

• Removing a non-existent attribute is a no-op (no error thrown)
• Removal takes effect immediately for subsequent signals
• Removal persists across page loads (stored in browser storage)
• Removing an attribute that was set via additionalSignalAttributes in init() removes it from all signals
• Removal does not affect attributes that were never added
• Removing and re-adding an attribute with the same name creates a new attribute

Attribute Value Types

type AttributeValueType =
  | string
  | number
  | boolean
  | Array<string | number | boolean>
  | Record<string, string | number | boolean>;

The SDK also supports the OpenTelemetry AnyValue type for more complex data structures:

interface AnyValue {
  stringValue?: string;
  boolValue?: boolean;
  intValue?: string;
  doubleValue?: number;
  arrayValue?: { values: AnyValue[] };
  kvlistValue?: { values: Array<{ key: string; value: AnyValue }> };
  bytesValue?: string;
}

Critical Behavior:

• AttributeValueType is the simplified type for most use cases
• AnyValue is the OpenTelemetry-compatible type for complex structures
• Arrays and objects in AttributeValueType must contain only primitive values
• AnyValue supports nested structures and byte arrays
• Invalid types may be ignored or converted
• Null values may be converted to undefined or ignored
• Undefined values may be ignored or cause errors
• Circular references in objects may cause serialization errors

Common Use Cases

Feature Flags

Track which features are enabled for debugging and analytics:

addSignalAttribute("feature.new_checkout", true);
addSignalAttribute("feature.ab_test_variant", "B");

User Context

Add user-level context (use identify() for standard user attributes):

addSignalAttribute("user.subscription_tier", "premium");
addSignalAttribute("user.account_age_days", 365);

Application State

Track application-wide state:

addSignalAttribute("app.mode", "demo");
addSignalAttribute("app.locale", "en-US");
addSignalAttribute("app.theme", "dark");

Business Context

Add business-level information:

addSignalAttribute("tenant.id", "acme-corp");
addSignalAttribute("region", "us-west-2");

Dynamic Attributes

Update attributes as application state changes:

// On user login
addSignalAttribute("auth.status", "authenticated");

// On user logout
removeSignalAttribute("auth.status");
addSignalAttribute("auth.status", "anonymous");

Edge Cases and Error Conditions

Attribute Naming

• Reserved Names: Some attribute names may be reserved by the SDK (e.g., session.id, user.id)
• Special Characters: Attribute names with special characters are preserved as-is
• Empty Names: Empty attribute names may be ignored or cause errors
• Very Long Names: Very long attribute names may be truncated or cause storage issues
• Case Sensitivity: Attribute names are case-sensitive
• Unicode Characters: Unicode characters in attribute names are preserved
• Control Characters: Control characters in attribute names may be filtered or preserved

Attribute Values

• Null Values: Null values may be converted to undefined or ignored
• Undefined Values: Undefined values may be ignored or cause errors
• Invalid Types: Invalid attribute types may be ignored or converted
• Very Large Values: Very large attribute values may be truncated or cause storage issues
• Circular References: Objects with circular references may cause errors
• Nested Structures: Very deeply nested structures may cause serialization issues
• Array Limits: Very large arrays may cause storage or transmission issues
• Object Limits: Very large objects may cause storage or transmission issues

Storage and Persistence

• Storage Unavailable: If storage is unavailable, attributes may not persist across page loads
• Storage Quota: If storage quota is exceeded, attributes may not be saved
• Session Expiry: Attributes are cleared when session expires or is terminated
• Storage Corruption: If stored attribute data is corrupted, attributes may be reset
• Storage Clearing: If user clears browser storage, all attributes are lost
• Storage Race Conditions: Concurrent storage operations from multiple tabs may cause race conditions
• Storage Performance: Very slow storage operations may impact performance

Initialization

• Before Init: If addSignalAttribute() is called before init(), attributes may be queued or lost
• After Init: Attributes set after initialization are immediately available for telemetry
• Multiple Init: If init() is called multiple times, additionalSignalAttributes from the last call are used
• Init Failure: If initialization fails, attributes may be lost

Attribute Overwriting

• Same Name: Adding an attribute with the same name overwrites the previous value
• Type Changes: Changing the type of an attribute (e.g., string to number) overwrites the value
• Removal and Re-add: Removing and re-adding an attribute with the same name creates a new attribute
• Partial Updates: Partial updates to object attributes are not supported; entire object must be replaced

Multiple Tabs

• Shared Attributes: Attributes are shared across tabs on the same domain (via storage)
• Tab Isolation: Some browsers isolate storage, causing separate attributes per tab
• Synchronization: Attribute changes may not be immediately visible in other tabs
• Concurrent Updates: Concurrent updates from multiple tabs may cause race conditions
• Tab Closing: Closing a tab does not affect attributes in other tabs

Network and Transmission

• Offline Mode: Attributes are stored locally and included in telemetry when online
• Transmission Failures: Attributes are included in telemetry even if transmission fails
• Attribute Scrubbing: Attributes may be scrubbed by URL scrubbers or other filters
• Multiple Endpoints: Attributes are sent to all configured endpoints
• Transmission Delays: Attributes are included in telemetry even if transmission is delayed

Performance

• Many Attributes: Having many attributes may impact performance and storage
• Large Values: Large attribute values may impact transmission performance
• Frequent Updates: Frequently updating attributes may impact performance
• Storage Operations: Storage operations are synchronous and may block if storage is slow
• Serialization: Serializing many or large attributes may impact performance

Type-Specific Edge Cases

• String Attributes: Very long strings may be truncated or cause storage issues
• Number Attributes: Very large numbers may lose precision or cause serialization issues
• Boolean Attributes: Boolean values are preserved as-is
• Array Attributes: Very large arrays may cause storage or transmission issues
• Object Attributes: Very large objects may cause storage or transmission issues
• Nested Structures: Very deeply nested structures may cause serialization issues

Reserved Attribute Names

While not strictly enforced, the following attribute name patterns are used by the SDK:

• session.* - Session-related attributes
• user.* - User identification attributes
• event.* - Event-related attributes
• url.* - URL-related attributes
• http.* - HTTP request attributes

Using these patterns may cause conflicts or unexpected behavior.