Roku DataDog error tracker

A tool to track your Roku application errors.

Requirements

• NODE.js
• ROPM

Installation

Use following command to get the package to your application

ropm install roku-data-dog

The package should be stored in /components directory

How to use DataDogTracker:

• Create your RUM application in DataDog
• Create a try-catch block where you expect any error to occure

Used with a SceneGraph project:

• Inside the CATCH:
• Create dataDogTracker component
• Create and set the DataDog configuration
• Send the error to DataDog
• In the following example you can observe how to set up what was explained above:

dataDogTracker = CreateObject("roSGNode", "TrackerComponent")
dataDogConfigurationObject = {applicationID: "[application_id]", clientToken: "[application_token]"}
dataDogTracker.callFunc("setConfiguration", ConfigurationObject)
dataDogTracker.callFunc("sendError", error)

Used with BrightScript project:

• Inside the xml file of your component you have to include the scripts for the following components:

<script type="text/brightscript" uri="pkg:/[path_to_project]/dataDogTracker/viewSample.brs" />
<script type="text/brightscript" uri="pkg:/[path_to_project]/dataDogTracker/errorSample.brs" />
<script type="text/brightscript" uri="pkg:/[path_to_project]/dataDogTracker/dataDogConfig.brs" />
<script type="text/brightscript" uri="pkg:/[path_to_project]/dataDogTracker/dataDogConfiguration.brs" />
<script type="text/brightscript" uri="pkg:/[path_to_project]/dataDogTracker/dataDogTracker.brs" />

• Inside the CATCH:
• Set the DataDog configuration
• Send the error to DataDog
• In the following example you can observe how to set up what was explained above:

dataDogConfigurationObject = {applicationID: "[application_id]", clientToken: "[application_token]"}
dataDogTrackerConfiguration = Configuration(dataDogConfigurationObject)
dataDogTracker = Tracker(dataDogTrackerConfiguration)
dataDogTracker.sendError(error)

Keep in mind that in the examples, the methods are called without any prefixes, so if you install the package with prefixes, use them for the package methods.

The following fields can be set inside the DataDog configuration:

| Field | Type | Default Value | | :------------ | :------------ | :------------ | | applicationID | STRING | "" | | clientToken | STRING | "" | | site | STRING | "" | | service | STRING | "" | | sampleRate | INTEGER | 100 | | trackInteractions | BOOLEAN | TRUE |

Custom data (optional)

Call setCustomData after setConfiguration and before sendError to attach additional data to the events. The object is merged into the top level of both the view and the error event, so any RUM event field can be set. When the tracker is used without calling setCustomData, the events are sent normally.

To make the data searchable in DataDog, nest custom attributes under context and user identity under usr:

• context fields can be searched and filtered as @context.[field_name] (create a facet for them once in the RUM Explorer)
• usr follows the DataDog RUM user schema (id, name, email) and is searchable through the built-in @usr.* facets

customData = {
    context: { screen: "MainScene", custom_attribute: "value" },
    usr: { id: "[user_id]", email: "[user_email]" }
}
dataDogTracker.setCustomData(customData)

When used as a SceneGraph component:

dataDogTracker.callFunc("setCustomData", customData)

How to use the Test Project

• Download test-project file to your machine
• Note that in the scene component there are 2 ways of the DataDog tracker implementation:
• BrightScript implementation (currently used)
• SceneGraph implementation (commented inside the code)
• Replace [application_id] with your application id
• Replace [application_token] with your application token
• Archive the project and run it on your device
• Look in DataDog RUM application to see the view with one error in it

Data recieved by DataDog RUM application

Currently the application is sending a view event and one error event, both sharing same ids.

What you can see inside the error

• date
• country
• application ID
• application version
• device model
• device OS version
• message
• backtrace

License

This library is licensed under the Apache 2.0 License. See the LICENSE for details.