Logs, errors, and crashes

Open in ChatGPTOpen in Claude

The SDK can record logs you write yourself, errors your channel catches, and crashes it did not survive. This page covers all three, and how to stop the SDK reporting errors you already expect.

Custom logs

Report a line of your own at a chosen severity level. Each level has its own method, from reportDebug through reportCritical. For example, reportInfo records at Info severity:

m.global.cxRum.callfunc("reportInfo", "playback started", {
    data: { asset_id: "movie-8842", bitrate: 4500 },
    labels: { feature: "playback" }
})

Method	Severity	Use it for
reportDebug	Debug	Detail useful only while developing the channel
reportVerbose	Verbose	High-volume tracing you would not keep on in production
reportInfo	Info	Ordinary milestones, such as a screen shown or content loaded
reportWarn	Warning	Something recoverable that a viewer may have noticed
reportErrorLog	Error	A failure worth investigating, recorded as a log
reportCritical	Critical	A failure that stops the channel doing its job

Each takes a message and optional { data, labels }.

Note

The SDK truncates a message longer than 2048 characters, keeping the first 2048 characters. However, when a data block has a size of over 3584 characters, the SDK drops the whole block. In both cases, it emits a warning in the console.

When the level is a variable, use reportLog with a value from getSeverity:

severity = m.global.cxRum.callfunc("getSeverity")
m.global.cxRum.callfunc("reportLog", severity.WARN, "cache miss", { data: { key: "home" } })

Note

BrightScript lowercases associative-array keys, so data: { assetId: 1 } arrives in Coralogix as assetid. Use snake_case keys, or build the object case-sensitive before adding any keys:

data = CreateObject("roAssociativeArray")
data.SetModeCaseSensitive()
data["assetId"] = 1

SetModeCaseSensitive() works only on a new object, before you add keys, and doesn't carry into nested objects: set it on each level. The same applies to labels.

Error reporting

Pass a caught error to reportError from your try/catch. The SDK sends the message, error code and stack trace:

try
    startPlayback(asset)
catch e
    m.global.cxRum.callfunc("reportError", e, {
        data: { asset_id: asset.id },
        labels: { feature: "playback" }
    })
end try

Report a failure that didn't throw, as an object or a message:

m.global.cxRum.callfunc("reportError", { message: "no payment method on file", errorType: "PaymentError" })
m.global.cxRum.callfunc("reportError", "playlist arrived empty")

Set a short errorType for each kind of failure, such as PaymentError, and give thrown errors one too: throw { message: "checkout failed", errorType: "PaymentError" }.

Note

An error's data block is limited to 2048 characters, tighter than a log's. Over the limit the SDK drops the block whole, keeping none of it.

Ignore errors

ignoreErrors drops errors whose message matches. A string matches anywhere in the message; a regular expression is written between slashes, with the flags i, m, s and x. Set it in coralogix_roku_initialize(), as with every option:

coralogix_roku_initialize({
    ' ...
    ignoreErrors: ["expected timeout", "/^Network error/i"]
}, screen.getGlobalNode())

Crashes

Crash reporting requires Roku OS 13 or later. The SDK reports crashes automatically on the next launch, with the exit code, the last 20 console lines before the crash, and the view that was open when the channel crashed (see View tracking). It doesn't report a crash followed by a device restart, or a crash when the channel isn't opened again within 24 hours.

If sending the report fails because of a server error or no network, the SDK tries again after 30 seconds and then after 2 minutes. If those fail too, it keeps the report and tries again on later launches, until 24 hours after the crash.

Warning

The SDK sends these console lines to Coralogix. Keep tokens and personal data out of your console output.

error_type	Meaning
BrightScriptCrash	The channel's code crashed
OutOfMemory	The channel ran out of memory
SystemKill	The OS closed the channel
Crash	Any other unexpected exit