Send logs to Datadog from your Roku channel with Datadog’s dd-sdk-roku logging library and leverage the following features:

• Log to Datadog in JSON format natively.
• Add context and extra custom attributes to each log sent.
• Record real client IP addresses and User-Agents.
• Optimized network usage with automatic bulk posts.

Setup

1. Add the dependency to your project using ROPM, or download the latest zip archive and extract it to your project.

   ropm install datadog-roku
   

2. Initialize the library with your Datadog client token and Application ID generated when you create a new RUM application in the Datadog UI (see Getting Started with Roku RUM Collection for more information). For security reasons, you must use a client token: you cannot use Datadog API keys to configure the dd-sdk-roku library as they would be exposed client-side in the Roku channel’s package.

   For more information about setting up a client token, see the client token documentation.

   sub RunUserInterface(args as dynamic)
       screen = CreateObject("roSGScreen")
       scene = screen.CreateScene("MyScene")
       screen.show()
   
       datadogroku_initialize({
           clientToken: "<CLIENT_TOKEN>",
           applicationId: "<APPLICATION_ID>"
           site: "us1",
           env: "<ENV_NAME>",
           sessionSampleRate: 100, ' the percentage (integer) of sessions to track
           launchArgs: args
       })
   
       ' complete your channel setup here
   end sub
   

   sub RunUserInterface(args as dynamic)
       screen = CreateObject("roSGScreen")
       scene = screen.CreateScene("MyScene")
       screen.show()
   
       datadogroku_initialize({
           clientToken: "<CLIENT_TOKEN>",
           applicationId: "<APPLICATION_ID>"
           site: "eu1",
           env: "<ENV_NAME>",
           sessionSampleRate: 100, ' the percentage (integer) of sessions to track
           launchArgs: args
       })
   
       ' complete your channel setup here
   end sub
   

   sub RunUserInterface(args as dynamic)
       screen = CreateObject("roSGScreen")
       scene = screen.CreateScene("MyScene")
       screen.show()
   
       datadogroku_initialize({
           clientToken: "<CLIENT_TOKEN>",
           applicationId: "<APPLICATION_ID>"
           site: "us3",
           env: "<ENV_NAME>",
           sessionSampleRate: 100, ' the percentage (integer) of sessions to track
           launchArgs: args
       })
   
       ' complete your channel setup here
   end sub
   

   sub RunUserInterface(args as dynamic)
       screen = CreateObject("roSGScreen")
       scene = screen.CreateScene("MyScene")
       screen.show()
   
       datadogroku_initialize({
           clientToken: "<CLIENT_TOKEN>",
           applicationId: "<APPLICATION_ID>"
           site: "us5",
           env: "<ENV_NAME>",
           sessionSampleRate: 100, ' the percentage (integer) of sessions to track
           launchArgs: args
       })
   
       ' complete your channel setup here
   end sub
   

   sub RunUserInterface(args as dynamic)
       screen = CreateObject("roSGScreen")
       scene = screen.CreateScene("MyScene")
       screen.show()
   
       datadogroku_initialize({
           clientToken: "<CLIENT_TOKEN>",
           applicationId: "<APPLICATION_ID>"
           site: "ap1",
           env: "<ENV_NAME>",
           sessionSampleRate: 100, ' the percentage (integer) of sessions to track
          launchArgs: args
       })
   
       ' complete your channel setup here
   end sub
   

3. (Optional) When writing your application, you can enable development logs by setting the datadogVerbosity attribute on the global node. All internal messages in the library with a priority equal to or higher than the provided level are then logged to your Roku device’s telnet output:

   ' 0 = none; 1 = error; 2 = warning; 3 = info; 4 = verbose;
   m.globalNode.addFields({ datadogVerbosity: 2 }) 
   

4. Send a custom log entry directly to Datadog with one of the following functions:

   msg = "A log message"
   m.global.datadogLogsAgent.callfunc("logOk", msg, {})
   m.global.datadogLogsAgent.callfunc("logDebug", msg, {})
   m.global.datadogLogsAgent.callfunc("logInfo", msg, {})
   m.global.datadogLogsAgent.callfunc("logNotice", msg, {})
   m.global.datadogLogsAgent.callfunc("logWarn", msg, {})
   m.global.datadogLogsAgent.callfunc("logError", msg, {})
   m.global.datadogLogsAgent.callfunc("logCritical", msg, {})
   m.global.datadogLogsAgent.callfunc("logAlert", msg, {})
   m.global.datadogLogsAgent.callfunc("logEmergency", msg, {})
   

5. (Optional) Provide an Associative Array alongside your log message to add attributes to the emitted log. Each entry of the AssocArray is added as an attribute.

    m.global.datadogLogsAgent.callfunc(
        "logInfo", 
        "Video started", 
        { video_id: 42, video_type: "advert"}
    )
   

Batch collection

All the logs are first stored on the local device in batches. Each batch follows the intake specification. They are sent as soon as network is available. If the network is not available while your channel is opened, or if an upload of data fails, the batch is kept until it can be sent successfully.

To ensure the SDK doesn’t use too much disk space, the data on the disk is automatically discarded if it gets too old.

Note: Before data is uploaded to Datadog, it is stored in cleartext in your channel’s cache directory, meaning that this data can’t be read by other applications. The OS can evict the data at any time, which may result in data loss in some rare cases.

Further Reading

Additional helpful documentation, links, and articles:

Source code for dd-sdk-rokuSOURCE CODE Learn how to explore your logsDOCUMENTATION