---
title: addToTrace
source: https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/addtotrace
---

## Syntax

```js
newrelic.addToTrace(JavaScript object $custom_object)
```

Adds a JavaScript object with a custom name, start time, etc. to an in-progress session trace.

## Requirements

-   Browser Pro or Pro+SPA agent (v593 or higher)
-   If you're installing the browser agent via npm and building a custom agent with selected features, you must enable the `session_trace` feature when creating the `Agent` instance. In the `features` array, add the following:

    ```js
    import { SessionTrace } from '@newrelic/browser-agent/features/session_trace';

    const options = {
      info: { ... },
      loader_config: { ... },
      init: { ... },
      features: [
        SessionTrace
      ]
    }
    ```

    For more information, see the [npm browser installation documentation](https://www.npmjs.com/package/@newrelic/browser-agent#new-relic-browser-agent).

## Description

Custom events within [browser session traces](https://docs.newrelic.com/docs/browser/new-relic-browser/browser-pro-features/session-traces-exploring-webpages-life-cycle) can provide context for other user actions, errors, and default events within the trace. This event will appear in the browser session trace details.

-   If a session trace currently **is** in progress, this adds an object with a user-defined name, start time, and other optional fields.
-   If you make this call and a session trace **is not** already in progress, this will not cause browser to capture a trace.

Note that the number of events shared this way is limited by the Browser agent harvest cycle. [Here is the last update on that limit](https://docs.newrelic.com/docs/release-notes/new-relic-browser-release-notes/browser-agent-release-notes/browser-agent-v1026/#:~:text=Adjusted%20PageAction%20limits,events%20per%20harvest).

## Parameters

| Parameter                            | Description                                                                                                                                                                                                                                                                         |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$custom_object` _JavaScript object_ | Required. Supply a JavaScript object with these required and optional name/value pairs: - Required name/value pairs: `name`, `start` - Optional name/value pairs: `end`, `origin` - `start` and `end` must be valid non-negative Unix timestamps and `end` cannot be before `start` |

## Examples

```js
var obj = {
  // REQUIRED
  name: 'Event Name',
  start: 1417044274239, // Time in ms since epoch

  // OPTIONAL
  end: 1417044274252,
  // Time in ms since epoch. Defaults to same as start resulting in trace object with a duration of zero.
  origin: 'Origin of event',
  // Defaults to empty string
};
```