Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Standardising event types, introducing new attributes and updating documentation #76

Open
wants to merge 16 commits into
base: master
Choose a base branch
from
Open

Standardising event types, introducing new attributes and updating documentation #76

Show file tree
Hide file tree
Changes from 15 commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
de8e9cb
divided rokuVideo to videoAction and videoAdAction and rokuSystem to …
bmendiratta137 Nov 28, 2024
ef416c4
replaced videoCustomAction with RokuSystem and added a function for v…
bmendiratta137 Dec 2, 2024
f2cb932
updated videoCustomAction function
bmendiratta137 Dec 2, 2024
a1fb67c
added a condition for videoCustomAction
bmendiratta137 Dec 3, 2024
30d6389
switching attributes
bmendiratta137 Dec 10, 2024
6baf594
minor fix
bmendiratta137 Dec 10, 2024
63d64ad
revert some changes for testing
bmendiratta137 Dec 13, 2024
3e200fb
minor fix
bmendiratta137 Dec 13, 2024
c900a00
adding capability of setting user id
bmendiratta137 Dec 14, 2024
9dd805a
renamed userId to enduser.id
bmendiratta137 Dec 17, 2024
c1af25e
updated readme.md
bmendiratta137 Dec 17, 2024
4586d3d
update datamodel.md
bmendiratta137 Dec 17, 2024
cf08555
adding userId in readme.md
bmendiratta137 Dec 18, 2024
479d77e
minor fix
bmendiratta137 Dec 18, 2024
6e5eb13
update datamodel.md
bmendiratta137 Dec 19, 2024
3af34aa
minor fix
bmendiratta137 Dec 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
290 changes: 290 additions & 0 deletions DATAMODEL.md
View file
Open in desktop

Large diffs are not rendered by default.

286 changes: 29 additions & 257 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,16 @@

The New Relic Roku Agent tracks the behavior of a Roku App. It contains two parts, one to monitor general system level events and one to monitor video related events, for apps that use a video player.

Internally, it uses the Event API to send events using the REST interface. It sends two types of events: RokuSystem for system events and RokuVideo for video events. After the agent has sent some data it will be accessible in NR One Dashboards with a simple NRQL request like:
Internally, it uses the Event API to send events using the REST interface. It sends five types of events:
- RokuSystem for system events
- VideoAction for video events.
- VideoErrorAction for errors.
- VideoAdAction for ads.
- VideoCustomAction for custom actions.
After the agent has sent some data it will be accessible in NR One Dashboards with a simple NRQL request like:

```
SELECT * FROM RokuSystem, RokuVideo
SELECT * FROM RokuSystem, VideoAction, VideoErrorAction, VideoAdAction, VideoCustomAction
```
Will result in something like the following:

Expand All @@ -18,10 +24,7 @@ Will result in something like the following:
* [Installation](#installation)
* [Usage](#usage)
* [Agent API](#api)
* [Data Model](#data-model)
   * [Roku System](#roku-system)
   * [Roku Video](#roku-video)
   * [Metrics](#metrics)
* [Data Model](#data-model)
* [Ad Tracking](#ad-track)
* [Testing](#testing)
* [Open Source License](#open-source)
Expand Down Expand Up @@ -416,7 +419,7 @@ Example:
nrSendVideoEvent(nr as Object, actionName as String, attr = invalid) as Void

Description:
Send a video event, type RokuVideo.
Send a video event, type VideoAction.

Arguments:
nr: New Relic Agent object.
Expand Down Expand Up @@ -801,215 +804,27 @@ Example:
nrSendSummaryMetric(m.nr, "test", 2000, 5, 1000, 100, 200)
```

<a name="data-model"></a>
**setUserId**

### Data Model
```
setUserId(userId as String) as Void

Description:
Sets userId.

Arguments:
userId: attribute

Return:
Nothing.

Example:
setUserId("TEST_USER")
```

The agent generates two different event types: `RokuSystem` and `RokuVideo`.

<a name="roku-system"></a>

#### 1. RokuSystem

This event groups all actions related to system tracking.

#### 1.1 Actions

| Action Name | Description |
|---|---|
| `BANDWIDTH_MINUTE` | Report the bandwidth every minute. |
| `HTTP_CONNECT` | An HTTP request, generated by roSystemLog. |
| `HTTP_COMPLETE` | An HTTP response, generated by roSystemLog. |
| `HTTP_ERROR` | An HTTP error, generated by roSystemLog. |
| `HTTP_REQUEST` | An HTTP request. Generated by nrSendHttpRequest function. |
| `HTTP_RESPONSE` | An HTTP response. Generated by nrSendHttpResponse function. |
| `APP_STARTED` | The app did start. Generated by nrAppStarted function. |
| `SCENE_LOADED` | A scene did load. Generated by nrSceneLoaded function. |

#### 1.2 Attributes

There is a set of attributes common to all actions sent over a `RokuSystem` and others are specific to a certain action.

#### 1.2.1 Common Attributes

| Attribute Name | Description |
|---|---|
| `instrumentation.provider` | Always “media”. |
| `instrumentation.name` | Always “roku”. |
| `instrumentation.version` | Agent’s version. |
| `newRelicAgent` | Always “RokuAgent”. |
| `newRelicVersion` | Agent’s version. |
| `sessionId` | Session ID, a hash that is generated every time the Roku app starts. |
| `hdmiIsConnected` | Boolean. HDMI is connected or not. |
| `hdmiHdcpVersion` | HDCP version. |
| `uuid` | Roku Device UUID. |
| `device` | Roku device name. |
| `deviceGroup` | Always “Roku”. |
| `deviceManufacturer` | Always “Roku”. |
| `deviceModel` | Roku model. |
| `deviceType` | Roku model type. |
| `vendorName` | Roku model vendor. |
| `modelNumber` | Roku model number. |
| `vendorUsbName` | USB vendor. |
| `screenSize` | Size of the Roku TV. |
| `osName` | Always “RokuOS”. |
| `osVersion` | Firmware version. |
| `countryCode` | Country from where the current user is connected. |
| `timeZone` | Current user’s timezone. |
| `locale` | Current user’s locale. |
| `memoryLevel` | Device memory level. |
| `memLimitPercent` | Usage percentage of memory limit for the channel. Only reported if the memory monitor is enabled. |
| `channelAvailMem` | Estimated kilobytes of memory available for the channel. Only reported if the memory monitor is enabled. |
| `connectionType` | Network connection type (WiFi, etc). |
| `displayType` | Type of display, screen, TV, etc. |
| `displayMode` | Display mode. |
| `displayAspectRatio` | Aspect ratio. |
| `videoMode` | Video mode. |
| `graphicsPlatform` | Graphics platform (OpenGL, etc). |
| `timeSinceLastKeyPress` | Time since last keypress in the remote. Milliseconds. |
| `appId` | Application ID. |
| `appVersion` | Application version. |
| `appName` | Application name. |
| `appDevId` | Developer ID. |
| `appBuild` | Application build number. |
| `timeSinceLoad` | Time since NewRelic function call. Seconds. |
| `uptime` | Uptime of the system since the last reboot. Seconds. |

#### 1.2.2 Action Specific Attributes

| Attribute Name | Description | Actions |
|---|---|---|
| `httpCode` | Response code. | `HTTP_COMPLETE`, `HTTP_CONNECT`, `HTTP_ERROR`, `HTTP_RESPONSE` |
| `method` | HTTP method. | `HTTP_COMPLETE`, `HTTP_CONNECT`, `HTTP_ERROR`, `HTTP_REQUEST ` |
| `origUrl` | Original URL of request. | `HTTP_COMPLETE`, `HTTP_CONNECT`, `HTTP_ERROR`, `HTTP_REQUEST`, `HTTP_RESPONSE` |
| `domain` | Host part of `origUrl`. | `HTTP_COMPLETE`, `HTTP_CONNECT`, `HTTP_ERROR`, `HTTP_REQUEST`, `HTTP_RESPONSE` |
| `status` | Current request status. | `HTTP_COMPLETE`, `HTTP_CONNECT`, `HTTP_ERROR` |
| `targetIp` | Target IP address of request. | `HTTP_COMPLETE`, `HTTP_CONNECT`, `HTTP_ERROR` |
| `url` | Actual URL of request. | `HTTP_COMPLETE`, `HTTP_CONNECT`, `HTTP_ERROR` |
| `bytesDownloaded` | Number of bytes downloaded. | `HTTP_COMPLETE` |
| `bytesUploaded` | Number of bytes uploaded. | `HTTP_COMPLETE` |
| `connectTime` | Total connection time. | `HTTP_COMPLETE` |
| `contentType` | Mime type of response body. | `HTTP_COMPLETE` |
| `dnsLookupTime` | DNS lookup time. | `HTTP_COMPLETE` |
| `downloadSpeed` | Download speed. | `HTTP_COMPLETE` |
| `firstByteTime` | Time elapsed until the first bytes arrived. | `HTTP_COMPLETE` |
| `transferTime` | Total transfer time. | `HTTP_COMPLETE` |
| `uploadSpeed` | Upload speed. | `HTTP_COMPLETE` |
| `bandwidth` | Bandwidth. | `BANDWIDTH_MINUTE` |
| `lastExitOrTerminationReason` | The reason for the last app exit / termination. | `APP_STARTED` |
| `splashTime` | The splash time in ms. | `APP_STARTED` |
| `instantOnRunMode` | Value of `instant_on_run_mode` property sent to Main. | `APP_STARTED` |
| `launchSource ` | Value of `source` property sent to Main. | `APP_STARTED` |
| `httpResult` | Request final status. | `HTTP_RESPONSE` |
| `http*` | Multiple attributes. All the header keys. | `HTTP_RESPONSE` |
| `transferIdentity` | HTTP request identificator. | `HTTP_REQUEST`, `HTTP_RESPONSE` |
| `sceneName` | Identifier of the scene. | `SCENE_LOADED` |
| `timeSinceHttpRequest` | Time since `HTTP_REQUEST` in milliseconds. | `HTTP_RESPONSE` |

<a name="roku-video"></a>

#### 2. RokuVideo

This event groups all actions related to video tracking.

#### 2.1 Actions

| Action Name | Description |
|---|---|
| `PLAYER_READY` | Player is ready to start working. It happens when the video agent is started. |
| `CONTENT_REQUEST` | “Play” button pressed or autoplay activated. |
| `CONTENT_START` | Video just started playing. |
| `CONTENT_END` | Video ended playing. |
| `CONTENT_PAUSE` | Video paused. |
| `CONTENT_RESUME` | Video resumed. |
| `CONTENT_BUFFER_START` | Video started buffering. |
| `CONTENT_BUFFER_END` | Video ended buffering. |
| `CONTENT_ERROR` | Video error happened. |
| `CONTENT_HEARTBEAT` | Sent every 30 seconds between video start and video end. |
| `LICENSE_STATUS` | Video has received a DRM license response |

#### 2.2 Attributes

There is a set of attributes common to all actions sent over a `RokuVideo` and others are specific to a certain action.

#### 2.2.1 Common Attributes

For video events, the common attributes include all `RokuSystem` common attributes (1.2.1) plus the video event ones. Here we will describe only the video common attributes.

| Attribute Name | Description |
|---|---|
| `contentDuration` | Total video duration in milliseconds. |
| `contentPlayhead` | Current video position in milliseconds. |
| `contentIsMuted` | Video is muted or not. |
| `contentSrc` | Video URL. |
| `contentId` | Content ID, a CRC32 of contentSrc. |
| `contentBitrate` | Video manifest bitrate. |
| `contentMeasuredBitrate` | Video measured bitrate. |
| `contentSegmentBitrate` | In case of segmented video sources (HLS, DASH), the current segment’s bitrate. |
| `playerName` | Always “RokuVideoPlayer”. |
| `playerVersion` | Current firmware version. |
| `sessionDuration` | Time since the session started. |
| `viewId` | sessionId + “-“ + video counter. |
| `viewSession` | Copy of sessionId. |
| `trackerName` | Always “rokutracker”. |
| `trackerVersion` | Agent version. |
| `numberOfVideos` | Number of videos played. |
| `numberOfErrors` | Number of errors happened. |
| `timeSinceLastHeartbeat` | Time since last heartbeat, in milliseconds. |
| `timeSinceRequested` | Time since the video requested, in milliseconds. |
| `timeSinceStarted` | Time since the video started, in milliseconds. |
| `timeSinceTrackerReady` | Time since `PLAYER_READY`, in milliseconds. |
| `totalPlaytime` | Total time the user spend seeing the video. |
| `playtimeSinceLastEvent` | Total time the user spend seeing the video since last video event. |
| `timeToStartStreaming` | The time in milliseconds from playback being started until the video actually began playing. |
| `isPlaylist` | Content is a playlist. Boolean. |
| `videoFormat` | Video format, a mime type. |

#### 2.2.2 Action Specific Attributes

| Attribute Name | Description | Actions |
|---|---|---|
| `timeSinceBufferBegin` | Time since video last video buffering began, in milliseconds. | `CONTENT_BUFFER_END` |
| `timeSincePaused` | Time since the video was paused, in milliseconds. | `CONTENT_RESUME` |
| `errorMessage` | Descriptive error message. | `CONTENT_ERROR` |
| `errorCode` | Numeric error code. | `CONTENT_ERROR` |
| `errorStr` | Detailed error message. | `CONTENT_ERROR` |
| `errorClipId` | Property `clip_id` from Video object errorInfo. | `CONTENT_ERROR` |
| `errorIgnored` | Property `ignored` from Video object errorInfo. | `CONTENT_ERROR` |
| `errorSource` | Property `source` from Video object errorInfo. | `CONTENT_ERROR` |
| `errorCategory` | Property `category` from Video object errorInfo. | `CONTENT_ERROR` |
| `errorInfoCode` | Property `error_code` from Video object errorInfo. | `CONTENT_ERROR` |
| `errorDebugMsg` | Property `dbgmsg` from Video object errorInfo. | `CONTENT_ERROR` |
| `errorAttributes` | Property `error_attributes` from Video object errorInfo. | `CONTENT_ERROR` |
| `licenseStatusDuration` | Property `duration` from Video object licenseStatus. | `CONTENT_ERROR`, `LICENSE_STATUS` |
| `licenseStatusKeySystem` | Property `keySystem` from Video object licenseStatus. | `CONTENT_ERROR`, `LICENSE_STATUS` |
| `licenseStatusResponse` | Property `response` from Video object licenseStatus. | `CONTENT_ERROR`, `LICENSE_STATUS` |
| `licenseStatusStatus` | Property `status` from Video object licenseStatus. | `CONTENT_ERROR`, `LICENSE_STATUS` |
| `isInitialBuffering` | Is the initial buffering event, and not a rebuffering. In playlists it only happens at the beginning, and not on every video. | `CONTENT_BUFFER_*` |

<a name="metrics"></a>
#### 3. Metrics

The Roku agent generates the following metrics OOTB:

| Metric Name | Associated event | Metric type | Description |
|---|---|---|---|
| `roku.http.connect.count` | `HTTP_CONNECT` | count | Number of `HTTP_CONNECT` events generated in a period of time. |
| `roku.http.complete.count` | `HTTP_COMPLETE` | count | Number of `HTTP_COMPLETE` events generated in a period of time. |
| `roku.http.complete.connectTime` | `HTTP_COMPLETE` | gauge | Time taken to connect to the server in seconds. |
| `roku.http.complete.dnsTime` | `HTTP_COMPLETE` | gauge | DNS name resolution time in seconds. |
| `roku.http.complete.downSpeed` | `HTTP_COMPLETE` | gauge | Transfer download speed in bytes per second. |
| `roku.http.complete.firstByteTime` | `HTTP_COMPLETE` | gauge | Time taken to receive the first byte from the server in seconds. |
| `roku.http.complete.upSpeed` | `HTTP_COMPLETE` | gauge | Transfer upload speed in bytes per second. |
| `roku.http.error.count` | `HTTP_ERROR` | count | Number of `HTTP_ERROR` events generated in a period of time. |
| `roku.http.request.count` | `HTTP_REQUEST` | count | Number of `HTTP_REQUEST` events generated in a period of time. |
| `roku.http.response.count` | `HTTP_RESPONSE` | count | Number of `HTTP_RESPONSE` events generated in a period of time. |
| `roku.http.response.error.count` | `HTTP_RESPONSE` | count | Number of `HTTP_REQUEST` events generated in a period of time, that returned an error. |
| `roku.http.response.time` | `HTTP_RESPONSE` | gauge | Time since request in milliseconds. |

Each metric is associated with an event generated by the agent.

All metrics include the attribute `domain`, that is the host of the HTTP request.
<a name="data-model"></a>
### Data Model
To understand which actions and attributes are captured and emitted by the Dash Player under different event types, see [DataModel.md](./DATAMODEL.md).

<a name="ad-track"></a>
### Ad Tracking
Expand Down Expand Up @@ -1114,49 +929,6 @@ Where `m.top.tracker` is the tracker object passed to the task.

For a complete usage example, checkout files `VideoScene.brs` (function `setupVideoWithIMA()`) and `imasdk.brs` in the present repo.

#### Data Model

**Actions**

| Action Name | Description |
|---|---|
| `AD_BREAK_START` | An Ad Break has started. |
| `AD_BREAK_END` | An Ad Break has ended. |
| `AD_REQUEST` | Ad requested. |
| `AD_START` | Ad started. |
| `AD_PAUSE` | Ad paused. |
| `AD_RESUME` | Ad resumed. |
| `AD_END` | Ad ended. |
| `AD_QUARTILE` | Ad quartile happened. There are 3 quartile events during the ad playback. First happens after 25% of the ad is played. Second after 50% and third after 75%. |
| `AD_SKIP` | Ad skipped. |
| `AD_ERROR` | An error happened. |

**Attributes**

| Attribute Name | Description | Actions |
|---|---|---|
| `timeSinceAdBreakBegin` | Time since `AD_BREAK_START` happened, in milliseconds. | `AD_BREAK_END` |
| `timeSinceAdStarted` | Time since `AD_START` happened, in milliseconds. | All `AD_` events. |
| `timeSinceAdRequested` | Time since `AD_REQUEST` happened, in milliseconds. | All `AD_` events. |
| `timeSinceAdPaused` | Time since `AD_PAUSE` happened, in milliseconds. | `AD_RESUME` |
| `adTitle` | Title of current ad. | All `AD_` events. |
| `adId` | ID of current Ad. | All `AD_` events. |
| `adSystem` | Ad System of current Ad. | All `AD_` events. |
| `adDuration` | Ad duration in milliseconds. | All `AD_` events. |
| `adPosition` | Ad break position, "pre", "mid", "post" or "live". | All `AD_` events. |
| `adSrc` | Stream source of current Ad. | All `AD_` events. |
| `adCreativeId` | Creative ID of current Ad. | All `AD_` events. |
| `adPartner` | Partner of current Ad. | All `AD_` events. |
| `numberOfAds` | Number of started ads. | All `AD_` events. |
| `adQuartile` | Quartile number: 1, 2 or 3. | `AD_QUARTILE`. |
| `adErrorType` | Error type. | `AD_ERROR`. |
| `adErrorCode` | Error code. | `AD_ERROR`. |
| `adErrorMsg` | Error message. | `AD_ERROR`. |

Not all events and attributes are supported in all Ad trackers.

<a name="testing"></a>

### Testing

To run the unit tests, first copy the file `UnitTestFramework.brs` from [unit-testing-framework](https://github.com/rokudev/unit-testing-framework) to `source/testFramework/`. Then install the demo channel provided in the present repo and from a terminal run:
Expand Down
Loading