Track Events

Use track to record product-specific behavior: signups, workflow steps, integrations, billing milestones — anything auto-events do not cover.

Backend SDKs are stateless. Node.js and Python require the user’s distinctId / distinct_id as the first argument on every call. The browser SDK is stateful — after identify() the id is remembered in session/localStorage.

Signatures

JavaScript (browser)
Node.js
Python

Trodo.track(eventName, properties?, options?)

await trodo.track(distinctId, eventName, properties?, options?)

trodo.track(distinct_id, event_name, properties=None, category="custom")

Parameters

distinctId / distinct_id

string

required

Backend only. The end-user’s unique id. Required on every call because the server SDKs don’t persist identity.

eventName / event_name

string

required

Name of the event. Prefer snake_case, action-oriented names. Max 255 chars.

properties

object

JSON-serialisable properties for filtering and breakdowns.

options / category

object | string

Node accepts a TrackOptions object ({ category, timestamp }); Python accepts a category string positional. Both default category to "custom".

Basic call

JavaScript (browser)
Node.js
Python

Trodo.track('signup_completed', { plan: 'pro', source: 'pricing_page' });

await trodo.track('user-42', 'signup_completed', {
  plan: 'pro',
  source: 'pricing_page',
});

trodo.track(
    "user-42",
    "signup_completed",
    {"plan": "pro", "source": "pricing_page"},
)

Bind once, call many (`forUser` / `for_user`)

When you’re emitting several events for the same user in a row — a request handler, a background job — bind the distinct id once and call methods on the returned context. The browser SDK doesn’t need this because identity is already bound globally.

JavaScript (browser)
Node.js
Python

// Not needed — identity is bound globally after Trodo.identify()
Trodo.track('checkout_started');
Trodo.track('checkout_completed', { amount_cents: 9999 });

const user = trodo.forUser('user-42');

await user.track('checkout_started');
await user.track('checkout_completed', { amount_cents: 9999 });
await user.people.set({ plan: 'pro' });

user = trodo.for_user("user-42")

user.track("checkout_started")
user.track("checkout_completed", {"amount_cents": 9999})
user.people.set({"plan": "pro"})

Event category

Override the default custom category when you want to separate a class of events in the dashboard — e.g. security, billing, lifecycle.

JavaScript (browser)
Node.js
Python

Trodo.track('risk_flag_raised', { score: 0.82 }, { category: 'security' });

await trodo.track('user-42', 'risk_flag_raised', { score: 0.82 }, { category: 'security' });

trodo.track("user-42", "risk_flag_raised", {"score": 0.82}, category="security")

Batching (server only)

Enable batching at init when your backend emits thousands of events per second. Events are queued in memory and flushed on size/time/explicit flush.

Node.js
Python

trodo.init({
  siteId: process.env.TRODO_SITE_ID,
  batchEnabled: true,
  batchSize: 50,
  batchFlushIntervalMs: 5000,
});

await trodo.track('user-42', 'job_completed');
// ... many more ...
await trodo.flush();   // before shutdown

trodo.init(
    site_id=os.environ["TRODO_SITE_ID"],
    batch_enabled=True,
    batch_size=50,
    batch_flush_interval=5.0,
)

trodo.track("user-42", "job_completed")
# ... many more ...
trodo.flush()   # before shutdown

Always call shutdown() on process exit to flush the queue.

Naming best practices

Do

signup_completed
agent_run_started
integration_connected
checkout_failed

Avoid

click                # too generic
Event                # no verb
agentRunCompleted    # inconsistent casing (prefer snake_case)

Property best practices

Use typed, bounded values — strings for categoricals, numbers for metrics. Avoid free-form blobs.

// Good
Trodo.track('agent_run_completed', {
  workflow_id: 'weekly_report',
  duration_seconds: 36,
  outcome: 'success',
  surface: 'in_app',
});

// Too vague
Trodo.track('agent_run_completed', { data: 'done', value: 1 });

Reserved names

Don’t send properties that collide with auto-captured fields (page, current_url, referrer, timestamp, user_agent, screen_width, viewport_width, page_title, url, href). They may be stripped.

Error tracking

Wrap fallible code and track both outcomes so you can compute success rates as a ratio.

JavaScript (browser)
Node.js
Python

try {
  await runAgentWorkflow();
  Trodo.track('agent_run_completed', { outcome: 'success' });
} catch (err) {
  Trodo.track('agent_run_failed', {
    outcome: 'error',
    error_type: err.name,
    error_message: err.message,
  });
}

try {
  await runAgentWorkflow();
  await trodo.track('user-42', 'agent_run_completed', { outcome: 'success' });
} catch (err: any) {
  await trodo.track('user-42', 'agent_run_failed', {
    outcome: 'error',
    error_type: err.name,
    error_message: err.message,
  });
}

try:
    run_agent_workflow()
    trodo.track("user-42", "agent_run_completed", {"outcome": "success"})
except Exception as e:
    trodo.track(
        "user-42",
        "agent_run_failed",
        {
            "outcome": "error",
            "error_type": type(e).__name__,
            "error_message": str(e),
        },
    )

For uncaught backend exceptions, the SDK captures a server_error event automatically when autoEvents is on.

Identify users

Link anonymous sessions to known identities

User properties

Persistent traits that follow the user

INTRO

DATA IN

BEST PRACTICES

Track Events

Signatures

Parameters

Basic call

Bind once, call many (`forUser` / `for_user`)

Event category

Batching (server only)

Naming best practices

Do

Avoid

Property best practices

Reserved names

Error tracking

Identify users

User properties

INTRO

DATA IN

BEST PRACTICES

Documentation Index

​Signatures

​Parameters

​Basic call

​Bind once, call many (forUser / for_user)

​Event category

​Batching (server only)

​Naming best practices

​Do

​Avoid

​Property best practices

​Reserved names

​Error tracking

​Related methods

Identify users

User properties

Signatures

Parameters

Basic call

Bind once, call many (`forUser` / `for_user`)

Event category

Batching (server only)

Naming best practices

Do

Avoid

Property best practices

Reserved names

Error tracking

Related methods