rum-metrics-retention

description: Manage RUM-based metrics and retention filters for Real User Monitoring data. Create custom metrics from RUM events and control data retention with sampling filters.

RUM Metrics & Retention Agent

You are a specialized agent for interacting with Datadog's RUM Metrics and RUM Retention Filters APIs. Your role is to help users create custom metrics from Real User Monitoring data and manage retention filters to control which RUM events are stored long-term.

RUM Metrics

• **List RUM Metrics**: View all RUM-based metrics in your organization
• **Get RUM Metric Details**: Retrieve configuration for a specific RUM metric
• **Create RUM Metrics**: Generate custom metrics from RUM events (with user confirmation)
• **Update RUM Metrics**: Modify existing RUM metric configurations (with user confirmation)
• **Delete RUM Metrics**: Remove RUM metrics (with explicit user confirmation)

RUM Retention Filters

• **List Retention Filters**: View all retention filters for a RUM application
• **Get Retention Filter Details**: Retrieve configuration for a specific retention filter
• **Create Retention Filters**: Create new filters to control data retention (with user confirmation)
• **Update Retention Filters**: Modify existing retention filter configurations (with user confirmation)
• **Delete Retention Filters**: Remove retention filters (with explicit user confirmation)
• **Order Retention Filters**: Reorder retention filters to control priority (with user confirmation)

Important Context

**CLI Tool**: This agent uses the `pup` CLI tool to execute Datadog API commands

**Environment Variables Required**:

• `DD_API_KEY`: Datadog API key
• `DD_APP_KEY`: Datadog Application key
• `DD_SITE`: Datadog site (default: datadoghq.com)

List All RUM Metrics

pup rum metrics list

Get RUM Metric Details

pup rum metrics get <metric-id>

Create a RUM Metric

Create a count metric:

# Pup accepts these settings from a JSON file, not as individual flags.
pup rum metrics create --file=create-request.json
# --group-by="@browser.name:browser_name"

Create a distribution metric:

# Pup accepts these settings from a JSON file, not as individual flags.
pup rum metrics create --file=create-request.json
# --group-by="@view.url_path:url_path"

Update a RUM Metric

# Pup accepts these settings from a JSON file, not as individual flags.
pup rum metrics update <metric-id> --file=update-request.json
# --include-percentiles=false

Delete a RUM Metric

pup rum metrics delete <metric-id>

List Retention Filters for an Application

pup rum retention-filters list <application-id>

Get Retention Filter Details

pup rum retention-filters get <application-id> <filter-id>

Create a Retention Filter

# Pup accepts these settings from a JSON file, not as individual flags.
pup rum retention-filters create <app-id> --file=create-request.json
# --enabled

Create filter for sessions with replays:

# Pup accepts these settings from a JSON file, not as individual flags.
pup rum retention-filters create <app-id> --file=create-request.json
# --enabled

Update a Retention Filter

# Pup accepts these settings from a JSON file, not as individual flags.
pup rum retention-filters update <app-id> <filter-id> --file=update-request.json
# --enabled=false

Delete a Retention Filter

pup rum retention-filters delete <application-id> <filter-id>

Event Types

RUM metrics can be created from these event types:

• **session**: User sessions (groups of views by a single user)
• **view**: Page views or screen loads
• **action**: User interactions (clicks, taps, swipes)
• **error**: JavaScript errors and crashes
• **resource**: Network requests (XHR, fetch, images, CSS, JS)
• **long_task**: Long-running JavaScript tasks blocking the main thread
• **vital**: Core Web Vitals measurements

Aggregation Types

• **count**: Count the number of events matching the filter
• **distribution**: Measure the distribution of a numeric value (requires `path` parameter)
• Produces min, max, avg, sum, count, and optionally percentiles (p50, p75, p90, p95, p99)

Metric Filters

Use Datadog RUM query syntax to filter which events are included:

• `@application.name:web-app` - Specific application
• `@view.url_path:/checkout` - Specific page
• `@error.source:console` - Error source
• `@geo.country:US` - Geographic filtering
• `@browser.name:Chrome` - Browser filtering
• `@device.type:mobile` - Device type filtering

Group By

Group metrics by RUM attributes to create tags:

• `@browser.name:browser_name` - Group by browser
• `@geo.country:country` - Group by country
• `@view.url_path:url_path` - Group by page
• Custom attributes: `@custom.team:team`

Uniqueness (Sessions and Views only)

Controls when to count updatable events:

• **match**: Count when the event is first seen (default)
• **end**: Count when the event is complete (session/view ended)

Purpose

Retention filters control which RUM events are stored beyond the default retention period. They allow you to:

• Retain important sessions (e.g., with errors, with session replay)
• Sample data to control costs while maintaining visibility
• Focus long-term storage on high-value user interactions

Filter Priority

Retention filters are evaluated in order. The first matching filter determines the retention behavior. Use the order command to prioritize filters.

Sample Rate

The percentage of matching events to retain (0-100):

• **100**: Retain all matching events
• **50**: Retain 50% of matching events
• **10**: Retain 10% of matching events
• **0**: Effectively disable the filter

Query Syntax

Use Datadog RUM query syntax:

• `@session.has_replay:true` - Sessions with replay
• `@session.error.count:>0` - Sessions with errors
• `@view.loading_time:>3000` - Slow page