Guides
Start typing to search…

Debugging

Monitor, debug, and verify content displayed on devices

TelemetryOS provides a range of debugging tools. The browser-based Web Preview sandbox simulates device resolutions, orientations, and hardware events so you can iterate without deploying to a device. Isolated app runtimes (display, settings, background workers) with secure message-passing make it easy to inspect inter-component state and hardware calls. Background workers and serverless functions support independent execution and testing to trace data flows and scheduling logic.

On TelemetryOS Edge devices, optional Docker side-cars run local helpers or model services alongside the TOS Player for edge behavior reproduction. Scoped storage (device/instance/app/account) with real-time subscriptions enables configuration and sync issue observation. The SDK's web-centric tooling (React/TypeScript and Studio) supports standard browser devtools and logging workflows during development.

Debugging in TelemetryOS

Core Approach
  • Reproduce reliably in the Sandbox/Preview (local dev or CI preview) before hitting devices.
  • Narrow scope: is it app (React), OS/Player, network, or content pipeline?
Primary Tools
  • Sandbox Preview — run the app locally via the TelemetryOS dev sandbox to reproduce UI/logic issues.
  • Device Inspector / Remote Console — view realtime logs, stdout/stderr, and console messages from a Node Pro.
  • System Logs — TelemetryOS Edge logs (systemd/journald, TOS Player runtime logs). Pull via remote shell or support bundle.
  • Network Tools — ping, traceroute, proxying (Charles/Fiddler) to inspect API calls and resource loads.
  • CI/CD Preview (Git-to-Screen) — check deployment artifacts and build logs for pipeline failures.
  • SDK Debug Flags — enable verbose logging in TelemetryOS SDK (use TELEMETRYOS_LOG_LEVEL=debug or equivalent).
  • Browser DevTools — when running web apps in the sandbox or remote webview.
Common Workflows
  • Reproduce locally in Sandbox -> enable SDK verbose logs -> run through failing flow -> capture console + network traces.
  • If device-only: reproduce, collect Device Inspector logs + TelemetryOS Edge logs, capture screenshot/video, include timestamp and device ID.
  • For intermittent failures: enable persistent verbose logging and collect a support bundle after the failure window.
  • For content/render issues: validate assets via CDN (URL, MIME type, CORS), check caching headers and player cache behavior.
What to Collect for Support
  1. Exact timestamps (UTC), device ID/serial, player software version, app commit SHA, and plan/environment.
  2. Logs: app console, TOS Player runtime, TelemetryOS Edge system logs.
  3. Network captures or failing API responses.
  4. Repro steps and minimal repro (Sandbox link or repo/commit).
Typical Failure Modes and Quick Checks
  • App crash/unresponsive — check runtime stack trace, memory usage, and CPU; reproduce in Sandbox.
  • Asset not showing — confirm URL, headers, content-type, and CDN caching.
  • Deployment failing — inspect CI logs, build step errors, and Git webhook payloads.
  • Device provisioning/heartbeat missing — check network, device time sync, firewall rules, and device certificates.
  • Playback stutter — inspect hardware utilization and media encoding bitrate vs player capabilities.
Best Practices
  • Add structured logging (contextual fields: deviceId, user, requestId).
  • Use feature flags and staged rollouts through Git-to-Screen.
  • Write small reproducible test pages/components for isolating UI issues.
  • Automate smoke tests in CI that run in Sandbox preview.

Updated about 1 month ago

What’s Next