`performance.mark` with metadata is useful for Real user monitoring
Tags: javascript, performance
Published: 2017-11-17 02:14:56

---
title: "`performance.mark` with metadata is useful for Real user monitoring"
published: true
description: "`performance.mark` with metadata is useful for Real user monitoring"
tags: 
- JavaScript
- performance
---

I've created [performance-mark-metadata](https://github.com/azu/performance-mark-metadata "performance-mark-metadata").
This library provide `performance.mark` with custom meta data.

This library inspired by [User Timing API Level 3](https://docs.google.com/presentation/d/1d64Y4rtLCxobGgljVySU2CJpMPK5ksaiZuv3ka1dCVA/edit#slide=id.p "User Timing L3") proposal.
This proposal will add `details` as metadata to `performance.mark`.

Currently, [Performance.mark()](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark "Performance.mark()") API can not add metadata to marking.

## Supports

- Modern browser and Node.js >= 8.5.0
- They are supported [Performance.mark()](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark "Performance.mark()") API.
- [Performance Timing API | Node.js v9.2.0 Documentation](https://nodejs.org/api/perf_hooks.html "Performance Timing API | Node.js v9.2.0 Documentation")

Old browser need to `Performance.mark()` polyfill.

- [nicjansma/usertiming.js: UserTiming polyfill](https://github.com/nicjansma/usertiming.js "nicjansma/usertiming.js: UserTiming polyfill")

## Install

Install with [npm](https://www.npmjs.com/):

    npm install performance-mark-metadata

## Example

```js
import { PerformanceMetadataMarker } from "performance-mark-metadata";
const marker = new PerformanceMetadataMarker();
const metadata = {
    details: { key: "value" }
};
const markerName = "name";
// mark with metadata
marker.mark(markerName, metadata);
performance.getEntriesByName(markerName).forEach(entry => {
    // get metadata for entry
    const result = marker.getEntryMetadata(entry);
    /*
    {
        details: { key: "value" }
    };
    */
    assert.strictEqual(result, metadata, "should get same metadata");
});
```

### Usage in Node.js

Node.js 8.5.0 introduce [`perf_hooks`](https://nodejs.org/api/perf_hooks.html) module.
You can use this library by passing `require("perf_hooks").performance` to `PerformanceMetadataMarker` constructor arguments.

```js
import { PerformanceMetadataMarker } from "performance-mark-metadata";
const nodePerformanceHook = require("perf_hooks");
const performance = nodePerformanceHook.performance;
const marker = new PerformanceMetadataMarker({
    performance
});
marker.mark("name", {
    details: { key: "value" }
});
```

### UseCase

This example show actual usage.

[![Example](https://cdn.rawgit.com/azu/performance-mark-metadata/f79fe225/docs/example.png)](https://azu.github.io/performance-mark-metadata)

- See <https://azu.github.io/performance-mark-metadata>
 
You want to found performance problem on viewing the site.
You can analyze the problem by using `performance-mark-metadata`.

It is useful for [Real user monitoring](https://en.wikipedia.org/wiki/Real_user_monitoring "Real user monitoring")(RUM).
In development, you can use browser's development tools, but it is difficult about RUM.

#### Mark points

- Mark current Frame Per Seconds(FPS)
- Mark each action like "onClick"

Record FPS

```js
const { PerformanceMetadataMarker } = require("performance-mark-metadata");
const marker = new PerformanceMetadataMarker();

const FpsEmitter = require("fps-emitter");
const fps = new FpsEmitter();
fps.on("update", function(FPS) {
    // mark current FPS
    marker.mark("FPS", {
        details: {
            FPS: FPS
        }
    });
});
```

and record action

```js
// heavy task
const heavyTaskButton = document.getElementById("js-button");
heavyTaskButton.addEventListener("click", () => {
    marker.mark("Heavy Action");

    // ... heavy task ...
})
```

After that, you can get FPS and action logs.

```js
const logData = performance.getEntriesByType("mark").map(entry => {
    const meta = marker.getEntryMetadata(entry);
    return {
        type: entry.name,
        timeStamp: entry.startTime,
        meta: meta
    };
});
```

#### Analytics

You can get the log data and analyze the log data.

For example, visualize the log data by using [C3.js](http://c3js.org/ "C3.js").

![example.gif](https://cdn.rawgit.com/azu/performance-mark-metadata/f79fe225/docs/example.gif)

You can found the relationship  between "FPS" and "Heavy Task".
As a result, You can found that the performance problem is caused by "Heavy Task".

## Repository

- Example source code: [performance-mark-metadata/docs/](https://github.com/azu/performance-mark-metadata/tree/master/docs)
- [azu/performance-mark-metadata: `performance.mark` with custom meta data.](https://github.com/azu/performance-mark-metadata "azu/performance-mark-metadata: `performance.mark` with custom meta data.")

Welcome to ⭐️ and Pull Request!