User Identification

The user identification API allows you to associate user information with telemetry signals, enabling user-centric analysis, debugging, and monitoring. User attributes follow OpenTelemetry semantic conventions.

Critical User Identification Behavior:

• User attributes persist across page loads within the same session
• User attributes are cleared when session expires or is terminated
• User attributes are stored as signal attributes with user.* prefix
• User attributes are included in all telemetry signals after being set
• User attributes are stored in browser storage; storage unavailability prevents persistence
• Multiple calls to identify() merge attributes; they do not replace all attributes

Capabilities

Identify User

Associates user information with telemetry signals.

/**
 * Associates user information with telemetry signals
 * @param id - User identifier (optional)
 * @param opts - Additional user information (optional)
 * @throws No errors thrown; invalid values may be ignored
 */
function identify(id?: string, opts?: IdentifyOpts): void;

interface IdentifyOpts {
  /** Short name or login/username of the user */
  name?: string;
  /** User's full name */
  fullName?: string;
  /** User email address */
  email?: string;
  /** Unique user hash for anonymized correlation */
  hash?: string;
  /** User roles */
  roles?: string[];
}

Usage Examples:

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

// Basic user identification
identify("user-12345");

// Full user identification
identify("user-12345", {
  name: "johndoe",
  fullName: "John Doe",
  email: "john@example.com",
  roles: ["admin", "user"],
});

// Anonymized identification using hash
identify(undefined, {
  hash: "a1b2c3d4e5f6",
});

// Update only specific user attributes
identify("user-12345", {
  name: "johndoe",
  email: "john.doe@example.com",
});

For IIFE (script tag) usage:

dash0("identify", "user-12345");
dash0("identify", "user-12345", {
  name: "johndoe",
  fullName: "John Doe",
  email: "john@example.com",
  roles: ["admin", "user"],
});

Critical Behavior:

• User attributes persist across page loads within the same session
• Calling identify() multiple times merges attributes (does not replace all)
• If id is undefined, only opts attributes are set
• User attributes are stored as signal attributes with user.* prefix
• Attributes are included in all telemetry signals after being set
• If SDK is not initialized, attributes may be queued or lost
• User attributes are cleared when session expires or is terminated
• Setting user attributes to undefined does not remove them; use removeSignalAttribute()
• Invalid attribute values may be ignored or converted
• Very long attribute values may be truncated or cause storage issues

User Attributes

The user information is mapped to OpenTelemetry semantic convention attributes:

Critical Behavior:

• Attribute keys follow OpenTelemetry semantic conventions
• user.roles is stored as an array of strings
• All attributes are optional and can be set independently
• Setting an attribute to undefined does not remove it (use removeSignalAttribute)
• Attribute names are case-sensitive
• Invalid role values (non-strings) in array may be filtered out
• Empty arrays for roles are valid and stored as-is

Common Use Cases

User Login

Call identify() when a user logs in:

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

async function handleLogin(username, password) {
  const user = await authenticateUser(username, password);

  // Identify user after successful login
  identify(user.id, {
    name: user.username,
    fullName: user.displayName,
    email: user.email,
    roles: user.roles,
  });
}

User Registration

Identify newly registered users:

async function handleRegistration(userData) {
  const newUser = await createUser(userData);

  identify(newUser.id, {
    name: newUser.username,
    email: newUser.email,
    roles: ["user"],
  });
}

Anonymous Users

For anonymous users, you can still track with a hash:

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

// Generate or retrieve anonymous user hash
const anonymousHash = generateAnonymousHash();

identify(undefined, {
  hash: anonymousHash,
});

User Attribute Updates

Update user attributes as they change:

// User updates their email
function handleEmailUpdate(newEmail) {
  identify(currentUserId, {
    email: newEmail,
  });
}

// User gains a new role
function handleRoleUpdate(newRoles) {
  identify(currentUserId, {
    roles: newRoles,
  });
}

Clearing User Information

To clear user identification (e.g., on logout), you need to remove the attributes manually:

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

function handleLogout() {
  // Remove user attributes
  removeSignalAttribute("user.id");
  removeSignalAttribute("user.name");
  removeSignalAttribute("user.full_name");
  removeSignalAttribute("user.email");
  removeSignalAttribute("user.hash");
  removeSignalAttribute("user.roles");

  // Optionally terminate the session
  // See session-management.md
}

Privacy Considerations

When using the user identification API:

1. Email addresses: Be aware that email addresses are PII and may be subject to privacy regulations
2. Anonymization: Use the hash parameter for anonymized user tracking when PII cannot be collected
3. Consent: Ensure you have appropriate user consent before collecting and transmitting user information
4. Data retention: Configure appropriate data retention policies in your Dash0 account
5. GDPR Compliance: User identification data may be subject to GDPR requirements
6. Data Scrubbing: Consider using URL scrubbers to remove sensitive user data from URLs

Edge Cases and Error Conditions

Attribute Merging

• Multiple Calls: Calling identify() multiple times merges attributes; later calls do not replace all attributes
• Partial Updates: Only provided attributes are updated; missing attributes remain unchanged
• Undefined Values: Setting an attribute to undefined in opts does not remove it; use removeSignalAttribute instead
• Null Values: Null values may be converted to undefined or ignored
• Empty Strings: Empty strings are valid and stored as-is
• Attribute Overwriting: Setting the same attribute multiple times overwrites the previous value

Type Validation

• Invalid Types: Invalid attribute types may be ignored or converted
• Array Types: roles must be an array of strings; other types may be ignored
• String Types: All string attributes accept any string value; no format validation is performed
• Number Types: Numbers passed as strings may be converted or ignored
• Boolean Types: Booleans passed as strings may be converted or ignored
• Object Types: Objects passed as attribute values may be converted or ignored
• Function Types: Functions passed as attribute values are ignored

Storage and Persistence

• Storage Unavailable: If storage is unavailable, user attributes may not persist across page loads
• Storage Quota: If storage quota is exceeded, attributes may not be saved
• Session Expiry: User 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 user attributes are lost
• Storage Race Conditions: Concurrent storage operations from multiple tabs may cause race conditions

Initialization

• Before Init: If identify() 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, user attributes persist across re-initialization
• Init Failure: If initialization fails, user attributes may be lost

Special Values

• Empty Strings: Empty strings are valid and stored as-is
• Null Values: Null values may be converted to undefined or ignored
• Very Long Strings: Very long attribute values may be truncated or cause storage issues
• Special Characters: Special characters in attribute values are preserved
• Unicode Characters: Unicode characters in attribute values are preserved
• Emoji: Emoji in attribute values are preserved
• Control Characters: Control characters in attribute values may be filtered or preserved

Multiple Tabs

• Shared Attributes: User 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 user attributes in other tabs

Network and Transmission

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

Performance

• Attribute Size: Very large attribute values may impact storage and transmission performance
• Many Attributes: Having many user attributes may impact performance
• Frequent Updates: Frequently updating user attributes may impact performance
• Storage Operations: Storage operations are synchronous and may block if storage is slow

Security

• Sensitive Data: Be careful not to include sensitive data (passwords, tokens) in user attributes
• PII: User attributes may contain PII; ensure appropriate security measures
• Data Encryption: User attributes are stored in browser storage; consider encryption for sensitive data
• Access Control: User attributes are accessible via browser storage; consider access control

Email Validation

• Email Format: No email format validation is performed; invalid emails are stored as-is
• Email Uniqueness: No email uniqueness validation is performed
• Email Length: Very long email addresses may be truncated or cause storage issues
• Email Special Characters: Special characters in emails are preserved

Role Management

• Role Format: Roles must be strings; other types may be ignored
• Role Uniqueness: No role uniqueness validation is performed
• Role Ordering: Role order is preserved as provided
• Empty Roles: Empty role arrays are valid and stored as-is
• Very Many Roles: Very many roles may impact storage and transmission performance
• Duplicate Roles: Duplicate roles in array are preserved