> ## Documentation Index
> Fetch the complete documentation index at: https://globaliptv.misidev.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Logging

> How the GlobalTV Roku channel logs messages, how to enable verbose dev logging, and how to view logs from a connected Roku device.

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)

```brightscript theme={null}
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)

```brightscript theme={null}
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)

```brightscript theme={null}
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`:

```brightscript theme={null}
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:

```bash theme={null}
make install ROKU_IP=<your_roku_ip> ROKU_PASS=<your_dev_password>
```

<Note>
  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.
</Note>

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

  ```bash theme={null}
  # 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.
</Tip>

***

## Viewing logs

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

```bash theme={null}
telnet <ROKU_IP> 8085
```

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Find the Roku's IP address">
    On the Roku: **Settings → Network → About**. Note the IP address shown.
  </Step>

  <Step title="Open the debug console">
    ```bash theme={null}
    telnet <ROKU_IP> 8085
    ```

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

  <Step title="Sideload with dev logging enabled">
    To enable verbose `GTV_Log` output, set `IS_DEV_BUILD=true` in the manifest first:

    ```text manifest theme={null}
    bs_const=IS_DEV_BUILD=true
    ```

    Then sideload:

    ```bash theme={null}
    make install ROKU_IP=<ROKU_IP> ROKU_PASS=<password>
    ```

    Remember to revert to `IS_DEV_BUILD=false` before building a Channel Store package.
  </Step>
</Steps>

***

## 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.