Logging

The logging system lives in source/utils/Logger.brs and provides three functions with distinct severity levels and different print conditions.

Logging functions

GTV_Log — debug (dev builds only)

sub GTV_Log(tag as String, msg as String)
    #if IS_DEV_BUILD
        print "[GTV][" + tag + "] " + msg
    #end if
end sub

GTV_Log is compiled out entirely when IS_DEV_BUILD = false. The #if / #end if block is a BrightScript compile-time conditional — no runtime check, no overhead in production builds. Used for: normal flow tracing, event samples, parsed counts, and anything you only need during development. Example output:

[GTV][PlaylistTask] Parsed 42 channels, 6 categories
[GTV][AuthTask] event=auth_response code=200
[GTV][MainScene] Auth OK. userId=1042

GTV_Warn — warnings (always printed)

sub GTV_Warn(tag as String, msg as String)
    print "[GTV][WARN][" + tag + "] " + msg
end sub

GTV_Warn always prints regardless of the IS_DEV_BUILD flag. Used for recoverable issues: auth retry logic, server failover, skipped parser entries, connectivity state transitions, and session check deferrals. Example output:

[GTV][WARN][MainScene] Auto-login failed: Usuario o contraseña incorrectos.
[GTV][WARN][PlaylistTask] event=failover from=http://172.17.11.2:3333 to=https://admin.globaltv.lat reason=network_error code=-1
[GTV][WARN][ConnectivityTask] No internet reachability
[GTV][WARN][LayoutDiag] screen=MainScene apply w=1920 h=1080

GTV_Error — errors (always printed)

sub GTV_Error(tag as String, msg as String)
    print "[GTV][ERROR][" + tag + "] " + msg
end sub

GTV_Error always prints. Used for unrecoverable failures: handshake failure, no reachable server, HTTP request errors. Example output:

[GTV][ERROR][HandshakeTask] event=handshake_failed code=-1 server=http://172.17.11.2:3333
[GTV][ERROR][HealthCheck] event=no_server_reachable
[GTV][ERROR][HttpClient] AsyncGetToString failed

GTV_LayoutPrint — layout diagnostics

A special diagnostic print function defined in AppConstants.brs, used when LAYOUT_DIAG = true:

sub GTV_LayoutPrint(msg as String)
    print "[GTV][WARN][LayoutDiag] " + msg
end sub

Note that GTV_LayoutPrint always uses the [GTV][WARN][LayoutDiag] prefix and prints at warn level so it appears even in production builds when enabled. It is gated by the LAYOUT_DIAG flag in AppConstants, not by IS_DEV_BUILD. Example output:

[GTV][WARN][LayoutDiag] screen=MainScene apply w=1920 h=1080
[GTV][WARN][LayoutDiag] source=node.currentDesignResolution format=array[0,1] w=1920 h=1080

Log level summary

Function	Prefix	Prints in production	Prints in dev
`GTV_Log`	`[GTV][<tag>]`	No	Yes
`GTV_Warn`	`[GTV][WARN][<tag>]`	Yes	Yes
`GTV_Error`	`[GTV][ERROR][<tag>]`	Yes	Yes
`GTV_LayoutPrint`	`[GTV][WARN][LayoutDiag]`	Only if `LAYOUT_DIAG=true`	Only if `LAYOUT_DIAG=true`

Enabling dev logging

Dev logging is controlled by the IS_DEV_BUILD bs_const in the manifest file:

bs_const=IS_DEV_BUILD=false

To enable GTV_Log output, change this to:

bs_const=IS_DEV_BUILD=true

Then rebuild and sideload:

make install ROKU_IP=<your_roku_ip> ROKU_PASS=<your_dev_password>

Setting IS_DEV_BUILD=true increases log volume significantly. Every channel sample, every HTTP response code, every layout recalculation, and every ad poll result is printed. This can affect render-thread performance on lower-end Roku devices. Use dev builds only during development, not for channel submission packages.

Combine make install with a live telnet session so you see logs immediately as the app starts:

# Terminal 1 — sideload (after setting IS_DEV_BUILD=true in manifest)
make install ROKU_IP=192.168.1.x ROKU_PASS=xxxx

# Terminal 2 — follow logs
telnet 192.168.1.x 8085

Edit IS_DEV_BUILD=true in manifest before running make install. Remember to revert to false before creating a Channel Store package.

Viewing logs

Roku exposes the BrightScript debug console over Telnet on port 8085.

telnet <ROKU_IP> 8085

All print statements from the channel — including GTV_Log, GTV_Warn, and GTV_Error — appear here in real time.

Put the Roku in developer mode

Navigate to the Roku home screen and enter the developer mode sequence: Home × 3, Up × 2, Right, Left, Right, Left, Right. Enable the developer web server and note your device password.

Find the Roku's IP address

On the Roku: Settings → Network → About. Note the IP address shown.

Open the debug console

telnet <ROKU_IP> 8085

You should see a blank console. Relaunch the channel on the Roku — output appears immediately.

Sideload with dev logging enabled

To enable verbose GTV_Log output, set IS_DEV_BUILD=true in the manifest first:

manifest

bs_const=IS_DEV_BUILD=true

Then sideload:

make install ROKU_IP=<ROKU_IP> ROKU_PASS=<password>

Remember to revert to IS_DEV_BUILD=false before building a Channel Store package.

Diagnostic flags in AppConstants

Beyond IS_DEV_BUILD, three flags in AppConstants.brs enable additional diagnostic output at runtime (they can be toggled without changing IS_DEV_BUILD):

Flag	Default	Effect
`LAYOUT_DIAG`	`false`	Enables `GTV_LayoutPrint` calls; prints layout context values on every relayout.
`MAINSCREEN_GRID_DIAG`	`false`	Enables extra logging inside the channel grid row calculations.
`ADS_FLOW_DIAG`	`false`	Enables verbose ad polling flow logging via `GTV_Warn` (always visible).

All three print at the GTV_Warn level so they appear in both dev and production console sessions.

Get Started

Architecture

Core Features

Configuration

Build & Deploy

Reference

Logging functions

GTV_Log — debug (dev builds only)

GTV_Warn — warnings (always printed)

GTV_Error — errors (always printed)

GTV_LayoutPrint — layout diagnostics

Log level summary

Enabling dev logging

Viewing logs

Diagnostic flags in AppConstants

​Logging functions

​GTV_Log — debug (dev builds only)

​GTV_Warn — warnings (always printed)

​GTV_Error — errors (always printed)

​GTV_LayoutPrint — layout diagnostics

​Log level summary

​Enabling dev logging

​Viewing logs

​Diagnostic flags in AppConstants

Logging functions

GTV_Log — debug (dev builds only)

GTV_Warn — warnings (always printed)

GTV_Error — errors (always printed)

GTV_LayoutPrint — layout diagnostics

Log level summary

Enabling dev logging

Viewing logs

Diagnostic flags in AppConstants