Identification

A distinct ID is the identifier of the end user whose action triggered a run. Pass it and every run for that user becomes filterable in the dashboard, attributable in the user timeline, and groupable for cohorts.

Set the user on a run

Pass distinctId / distinct_id to wrapAgent (or startRun).

await trodo.wrapAgent('support', fn, { distinctId: 'user-42' });

with trodo.wrap_agent('support', distinct_id='user-42') as run:
    ...

Merge anonymous and identified

Call identify with a stable identifier (an email, a database ID) to link an anonymous distinctId to a known user. Use the same value on the browser and the server, and all events and runs merge under one profile.

const user = await trodo.identify('user@example.com');
// distinctId is now user@example.com — browser + server events merge
await user.track('login');

user = trodo.identify('user@example.com')
# distinct_id is now user@example.com — browser + server events merge
user.track('login')

Create a user without a run

users.upsert creates the user if they don't exist and is idempotent, so you can call it at signup — before they've triggered any agent — or on every request:

await trodo.users.upsert('user-42');                       // ensure only
await trodo.users.upsert('user-42', { properties: { plan: 'pro' } });

trodo.upsert_user('user-42')                               # ensure only
trodo.upsert_user('user-42', properties={'plan': 'pro'})

Why it matters

• Filter every run by user.
• See a user's full timeline of runs and events.
• Build cohorts and segment agent behaviour by who the user is.
• Because agent runs and product events share the same identity, you can move between them. Attach traits with Custom Properties.

Next

• Custom Properties for persistent user traits
• Conversations to group a user's runs into sessions