Logs & Diagnostics

Overview

The Logs app (id logs) is ControlBird's unified diagnostic console. It brings three distinct log streams together in one place: Service logs for core system operations, Communication logs for raw protocol TX/RX traffic, and Program logs for script console output. Each stream is written to the node's data directory, and the app reads them live with virtual scrolling, syntax highlighting, clickable entity IDs, JSON extraction, and content search.

Reach for the Logs app whenever you need to understand what a service is doing, why a device will not connect, or why a script produced an unexpected result. Because every log type is scoped per node and per service, you can drill straight to the relevant source instead of grepping files on disk. Communication logging is opt-in per endpoint, so you can enable raw byte capture only while troubleshooting and turn it off again once a connection is stable.

Key Concepts

ControlBird logs are layered by concern. Knowing which stream answers which question is the fastest way to diagnose a problem.

Files are named per service: data/{node}/{service-logs|comm-logs|program-logs}/{service-name}.log. All three stream live into the app, which polls for new content while auto-follow is active.

Log levels

Service log lines carry one of four severity levels, color-coded in the viewer:

• DEBUG: detailed diagnostic information for developers.
• INFO: normal operational events and status updates.
• WARN: potential issues that do not stop operation.
• ERROR: failures that require attention.

The log viewer

The viewer is built to handle very large files: it uses virtual scrolling to render only the lines currently on screen, so a long log stays responsive. Other behaviors to know about:

• Auto-follow watches for new content every couple of seconds and keeps the view pinned to the tail.
• Entity ID linking detects long numeric IDs in log text and makes them clickable through to the entity's details.
• JSON extraction detects JSON in a log message and offers a formatted overlay viewer with copy-to-clipboard.
• Search and time-range filters narrow the displayed lines. They apply to the content already loaded into the viewer.

Service Logs

Each ControlBird service writes structured lines to its own file under service-logs/. The format is consistent across services:

[YYYY-MM-DD HH:MM:SS.mmm LEVEL module] message

A concrete example:

[2024-01-30 15:23:45.123 INFO kernel] Store initialized with 1,247 entities

Service logs rotate automatically when a file reaches its size limit (default 10 MB), keeping up to 5 rotated files. The RUST_LOG environment variable controls verbosity (see Environment Variables).

Communication Logs

Protocol endpoints can record every transmitted (TX) and received (RX) message. This is the definitive source for diagnosing device-level issues. Binary protocols such as Modbus render the bytes in hexadecimal; text protocols such as MQTT render readable payloads.

# Binary (hex), e.g. Modbus
[2024-01-30 15:23:45.123] [TX] 01 03 00 00 00 0A C5 CD

# Text, e.g. MQTT
[2024-01-30 15:23:45.123] [RX] PUBLISH sensors/temp {"value": 72.5}

Communication logging is configured per Endpoint and is disabled by default. It only appears once the endpoint's Logging field is set to Enabled.

Endpoint

Protocol endpoint configuration for communication logging.

To turn on logging for an endpoint and retain a few rotated files:

SET Logging=Enabled, MaxLogFiles=3, MaxLogSizeMb=5

Program Logs

Scripts running in the Script Engine capture all console.log() output to a per-program file under program-logs/, and track execution status alongside the script. Each program records the result of its most recent run, when it last ran, the last error message if it failed, and running counts of total, successful, and failed executions.

Logs are scoped per node, so the selected node determines which data directory the app reads from.

Fetching Logs

The app discovers available log sources for a node and type, then fetches a window of lines for a selected source. From the command line, the kernel tail is available through cb-cli:

# Read the last 100 lines of the kernel log
cb-cli -c "LOGS cb-kernel 100"

Environment Variables

For self-hosted deployments, the following variables control logging behavior. Service and program logs have independent rotation settings.

# Verbose service logging while troubleshooting
RUST_LOG=debug

Common Patterns

• Temporary protocol capture. Set an endpoint's Logging to Enabled while bringing a device online, inspect the TX/RX bytes, then set it back to Disabled to avoid generating excess data.
• Top-down triage. Start with the relevant service log, drop to communication logs if the service looks healthy, and check program logs and execution fields for automation issues.
• Script health monitoring. Watch a script's last execution status, last error, and its total, successful, and failed execution counts to spot a misbehaving script without reading every line of output.
• Jump from log to entity. Click a detected 10+ digit entity ID in a log line to open that entity directly, instead of copying the ID into another app.

Troubleshooting & Limitations

• Rotation reloads the view. When a log file rotates, the viewer reloads the log from the start of the new file.
• Filters work on loaded content. Search and time-range filters narrow the lines already loaded into the viewer, not the entire file on disk.
• Entity ID matching is heuristic. The detector looks for long numeric IDs and may occasionally match unrelated values such as large timestamps.
• Auto-follow does not re-enable itself. Scrolling up disables auto-follow, and it does not automatically turn back on.
• Communication logs require opt-in. They only appear if the endpoint's Logging field is Enabled; it must be configured first.
• Program logs need explicit logging. They require console.log() calls; stderr is not captured.
• Endpoint retention defaults low. MaxLogFiles for endpoints defaults to 1 (a single rotated file); higher values can accumulate disk usage.
• Size limits are per-service. Log file size limits apply per service; disk space exhaustion is not handled automatically.
• Malformed lines pass filters. Timestamp parsing fails silently for malformed lines; time-range filters treat unparseable lines as included.