> ## Documentation Index
> Fetch the complete documentation index at: https://confidence.spotify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Recording Data

> Add context, tags, and measurements to recordings.

## Choose the Correct Data Type

| Data type | When to add it | Use it for |
| - | - | - |
| Context | During SDK initialization | Recording rule targeting |
| Tags | During an active recording | Labels and recording filters |
| Measurements | During an active recording | Application-specific numeric totals |

Tags and measurements cannot affect whether recording starts. Use context for policy
targeting.

## Add Context

Pass context when you initialize the SDK:

```typescript theme={null}
const recorder = initSessionRecorder({
  clientSecret: '<your-client-secret>',
  context: {
    user_id: 'user-123',
    plan: 'premium',
    checkout_version: 'one-page',
  },
});
```

Include the field selected as the targeting key in the policy for this client. For a
conditional rule, this is the **Of** field. If the policy uses `user_id`, pass a stable
`user_id` value for the same user in each session.

Keep this context aligned with the context used by the Confidence SDK for flags.

## Add Tags

Use `tag()` after recording starts:

```typescript theme={null}
if (recorder.isRecording) {
  recorder.tag('plan', 'premium');
  recorder.tag('checkout.flow', 'one-page');
  recorder.tag('checkout_started');
}
```

Tags with the same key accumulate values. A tag without a value acts as a marker.
Duplicate tag values appear only once.

<Warning>
  The SDK does not queue tags or measurements before recording starts. A call
  made while `recorder.isRecording` is `false` does not reach the recording.
</Warning>

## Add Measurements

Use `measure()` for numeric application data:

```typescript theme={null}
if (recorder.isRecording) {
  recorder.measure('checkout_items', 3);
  recorder.measure('checkout_retry');
}
```

Measurements with the same key add to one total. A call without a value adds `1`.
Measurement values must be finite numbers.

## Names and Limits

| Limit | Value |
| - | - |
| Allowed key characters | `a-z`, `A-Z`, `0-9`, `_`, `.`, and `-` |
| Key length | 128 characters |
| Tag value length | 256 characters |
| Distinct tag keys | 100 per recording |
| Values for one tag key | 1,000 per recording |
| Distinct measurement keys | 100 per recording |

The SDK drops invalid keys or values. Add a [debug logger](/docs/troubleshooting/recordings#enable-debug-logs)
to see validation messages. Additional keys or values that exceed the per-recording
limits do not appear in the recording.

## Find Custom Data in Confidence

The Recordings list supports tag-key and tag-value filters. A recording's Insights
view shows custom measurements as metrics. The Signals filter contains only the
built-in recording metrics.

## Protect Sensitive Data

The SDK sends all context, tag, and measurement data to Confidence. Do not include
direct personal identifiers, access tokens, or secrets. Use a pseudonymous identifier
only if your organization's privacy and data-handling requirements allow it. See
[Privacy and data masking](/docs/capabilities/recordings/privacy).