RUM Custom Attributes

Custom attributes enable you to enrich RUM events with application-specific data and user context. The Kloudfuse Browser SDK provides APIs to attach custom attributes at different scopes, allowing you to capture business metrics, user properties, and other contextual information alongside standard RUM telemetry.

Custom attribute APIs are available in kf-browser-sdk version 1.0.65 and later.

Custom attribute values must be strings. Nested properties are supported, but all leaf values must be strings. For numeric or boolean values, convert them to strings (e.g., policy_code: '25', hasPaid: 'true').

Use low-cardinality values to ensure optimal performance. Avoid high-cardinality values such as unique IDs, precise timestamps, or user-specific data. Instead, use categorical values, ranges, or buckets.

Global Context

Global context attributes are attached to all RUM events generated during a user session. Use global context for attributes that apply across the entire application, such as application version, feature flags, or tenant information.

Set Global Context Property

Add or update a single property in the global context:

import kfuseRumSDK from 'kf-browser-sdk';

kfuseRumSDK.setGlobalContextProperty('subscription', {
    tier: 'enterprise',
    billingCycle: 'annual',
    status: 'active'
});

javascript

Remove Global Context Property

Remove a specific property from the global context:

kfuseRumSDK.removeGlobalContextProperty('subscription');

javascript

Set Global Context

Replace the entire global context with new attributes:

kfuseRumSDK.setGlobalContext({
    releaseStage: 'stable',
    cluster: 'us-east'
});

javascript

Clear Global Context

Remove all custom attributes from the global context:

kfuseRumSDK.clearGlobalContext();

javascript

Get Global Context

Retrieve the current global context:

const context = kfuseRumSDK.getGlobalContext();
console.log(context);

javascript

View Context

View context attributes are attached to a specific view and all events generated within that view. Use view context for attributes relevant to a particular page or screen, such as page category, content type, or A/B test variant.

View context is automatically cleared when the user navigates to a new view.

Set View Context Property

Add or update a single property in the view context:

kfuseRumSDK.setViewContextProperty('page', {
    category: 'product-listing',
    department: 'electronics',
    sortOrder: 'price-asc'
});

javascript

Set View Context

Set multiple view context attributes at once:

kfuseRumSDK.setViewContext({
    pageType: 'checkout',
    checkoutStep: 'payment',
    cartSize: 'medium',
    hasPromoCode: 'true'
});

javascript

User Information

Associate user information with RUM events to understand which users are experiencing issues or specific behaviors. User information persists across views within the same session.

kfuseRumSDK.setUser({
    id: '1234',
    name: 'John Doe',
    email: 'john@doe.com',
    plan: 'premium',
    accountType: 'business'
});

javascript

You can include any custom properties beyond the standard id, name, and email fields to capture user attributes relevant to your application. Use categorical values or ranges for custom properties to maintain low cardinality.

Custom Actions

Custom actions allow you to track user interactions that aren’t automatically captured by the SDK, such as business-specific events like purchases, form submissions, or feature usage.

kfuseRumSDK.addAction('checkout-completed', {
    paymentMethod: 'credit-card',
    shippingMethod: 'express',
    discountApplied: 'true'
});

javascript

Custom actions appear as action events in RUM analytics and can be filtered and grouped like any other action.

Custom Errors

Enrich error events with custom attributes to provide additional context for debugging:

kfuseRumSDK.addError(error, {
    errorCategory: 'validation',
    component: 'checkout-form',
    userAction: 'submit'
});

javascript

Low-Cardinality Guidelines

To maintain optimal performance, use low-cardinality values for custom attributes.

Next Steps

After adding custom attributes to your RUM events, create custom facets to make these attributes searchable and visible in the RUM interface.