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

## Syntax [#syntax]

```js
newrelic.measure(name: string, options?: Object<{ customAttributes?: Object, start?: number|PerformanceMark, end?: number|PerformanceMark }>)

```

Reports a browser BrowserPerformance event.

## Requirements

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

    ```js
    import { GenericEvents } from '@newrelic/browser-agent/features/generic_events';

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

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

## Description [#description]

This API call sends a browser [`BrowserPerformance` event](https://docs.newrelic.com/docs/browser/new-relic-browser/browser-pro-features/marks-and-measures/) with your user-defined name and custom attributes. This is useful for manually creating an event as an alternative or alongside automatic marks and measures tracking.

## Parameters [#parameters]

| Parameter                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$name` _string_         | Required. Name or category of the task. Reported as the `entryName` attribute. Avoid using [reserved NRQL words](https://docs.newrelic.com/docs/insights/event-data-sources/custom-events/data-requirements-limits-custom-event-data/#reserved-words) when you name the attribute or value.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `$options` _JSON object_ | Optional. An object used for supplying configurations for the captured event. All attributes in the object are optional. `options.customAttributes` is an object of key:val pairs that assigns a top-level property and value to the created event for each attribute supplied. `options.start` can either be a floating point value of ms from origin time to reference as the start time or a valid `PerformanceMark` object. `options.start` can either be a floating point value of ms from origin time to reference as the end time or a valid `PerformanceMark` object. If `options.start` is not defined it defaults to `0`. If `options.end` is not defined it defaults to `performance.now()`. Avoid using [reserved NRQL words](https://docs.newrelic.com/docs/insights/event-data-sources/custom-events/data-requirements-limits-custom-event-data/#reserved-words) in custom attributes. |

## Return values

This method returns a JSON object with measurement details. `start` is the start time. `end` is the end time. `duration` is the length of the measurement from start to end. `customAttributes` are custom attributes passed into the measure API call. The custom attributes returned are not merged with [user-defined custom attributes](https://docs.newrelic.com/docs/data-apis/custom-data/custom-events/collect-custom-attributes/#collecting_browser), but they are merged when creating the `BrowserPerformance` event.

## Examples [#examples]

### Minimal example

```js
const myTask = newrelic.measure('checkout')
/** myTask **/
{
  start: 0, // page origin time was used since start was not supplied
  end: 1234, // performance.now() was used since end was not supplied
  duration: 1234, // end - start
  customAttributes: { } // no custom attributes were supplied
}
/** the browser agent buffers and later harvests the newly created BrowserPerformance event **/
```

### Using number arguments for start and/or end time

```js
const myTask = newrelic.measure('checkout', {
  start: 1234,
  end: 5678
})
/** myTask **/
{
  start: 1234, // options.start time was used directly
  end: 5678, // options.end time was used directly
  duration: 4444, // end - start
  customAttributes: { } // no custom attributes were supplied
}
/** the browser agent buffers and later harvests the newly created BrowserPerformance event **/
```

### Using PerformanceMark arguments

```js
const startMark = performance.mark('my-start-mark') // startTime = 1234
// later
const endMark = performance.mark('my-end-mark') // startTime = 5678
const myTask = newrelic.measure('checkout', {
  start: startMark,
  end: endMark
})
/** myTask **/
{
  start: 1234, // options.start.startTime was used since it was a BrowserPerformance entry
  end: 5678, // options.end.startTime was used since it was a BrowserPerformance entry
  duration: 4444, // end - start
  customAttributes: { } // no custom attributes were supplied
}
/** the browser agent buffers and later harvests the newly created BrowserPerformance event **/
```

### Mixed argument types

```js
const startMark = performance.mark('my-start-mark') // startTime = 1234
const myTask = newrelic.measure('checkout', {
  start: startMark,
  end: 5678
})
/** myTask **/
{
  start: 1234, // options.start.startTime was used since it was a BrowserPerformance entry
  end: 5678, // options.end time was used directly
  duration: 4444, // end - start
  customAttributes: { } // no custom attributes were supplied
}
/** the browser agent buffers and later harvests the newly created BrowserPerformance event **/
```

### Using custom attributes

```js
const myTask = newrelic.measure('checkout', {
  start: 1234,
  end: 5678,
  customAttributes: {
    foo: 'bar'
  }
})
/** myTask **/
{
  start: 1234, // options.start time was used directly
  end: 5678, // options.end time was used directly
  duration: 4444, // end - start
  customAttributes: {
    foo: 'bar'
  }
}
/** the browser agent buffers and later harvests the newly created BrowserPerformance event **/
```