Logs
Logs help diagnose runtime issues in Device Agent creation, device access, chat control, scheduled tasks, IM access, voice, and vision workflows. Use each feature's status or Run history for routine verification, then use logs when you need lower-level runtime context. Both local mode and the platform support console viewing and filtering. Local mode also supports reading log files directly.
Open the Logs Page
In the console sidebar, click Logs, or open /workspace/logs. The page has two main areas:
| Area | Purpose |
|---|---|
| Log files | Lists available files or platform archives, usually named like device-agent-2026-05-11.log. The platform also shows the service source and instance. |
| Log records | Shows records from the selected file. The page loads the latest 200 records by default. |
In local mode, if the page shows that file logging is disabled, open Logging configuration in the top-right corner, enable file logging, and save. New records start writing to files after file logging is enabled; earlier history is not backfilled. Deployment administrators manage platform archiving and retention; the platform page does not provide local file logging configuration.
Platform Logs
Platform runtime services archive structured logs in the shared database. View them through the same Logs entry point. After a runtime instance is replaced, archived records remain readable within the retention period; you do not need to locate files inside its container.
Sources in the file list look like worker/instance-001/device-agent-2026-05-11.log: service role, instance identifier, and file name. This identifies an archive source, not a server file path. api, worker, and ingress identify request services, Agent execution services, and device access services. Different instances may have files with the same date and name. Use request or device identifiers to correlate the relevant sources.
New records may take a short time to appear in the archive; refresh after an operation. If the list is empty or the archive is unavailable, check the selected source and date, then ask an administrator to inspect log collection and database connectivity.
Platform logs are removed according to the retention policy. Download important incident records promptly. Administrators maintain retention and collection settings through the procedure in Operations. The local directories, commands, and file settings below apply only to local mode.
Local Log Files
File logs are written to the logs subdirectory under the runtime home by default:
| Runtime | Default directory |
|---|---|
| Source checkout | <repo>/.device_agent/logs |
| Installed production binary | ~/.device_agent/logs |
Agent Gateway prints Runtime Home during startup. LOG_DIR=logs is resolved relative to that directory; if LOG_DIR is an absolute path, logs are written directly there. The directory name is .device_agent.
Same-day logs are split by size:
device-agent-2026-05-11.log
device-agent-2026-05-11.001.log
device-agent-2026-05-11.002.logdevice-agent-YYYY-MM-DD.log is the first file for the day. After it exceeds LOG_MAX_SIZE_MB, new records continue in .001.log, .002.log, and later segments. The Logs page only lists files that match this naming pattern.
Log Record Format
Log files use JSON Lines. Each line is one complete JSON record.
{
"time": "2026-05-11T05:20:12.123Z",
"level": "info",
"module": "MQTT",
"msg": "device connected",
"requestId": "req-...",
"productId": "product-001",
"deviceId": "device-001",
"topic": "device-agent/product-001/device/device-001/out",
"args": [{ "durationMs": 18 }]
}Common fields:
| Field | Description |
|---|---|
time | ISO timestamp, always written in UTC. |
level | debug, info, warn, or error. |
module | Backend module that emitted the record, such as Gateway, HTTP, MQTT, Agent, Timer, Workflow, Tools, Skills, Voice, NTP, or A2A-Channel. |
msg | Log message. |
requestId / sessionId / traceId | Connect one request, conversation, or tool call. |
namespace / productId / deviceId / topic | Locate a tenant, device, or MQTT topic. |
method / path / statusCode / durationMs | HTTP or service-call context. |
provider / tool | Model provider, voice provider, or tool execution context. |
args / error | Extra context and exception details, sanitized and truncated. |
Fields whose names imply secrets, such as apiKey, authorization, cookie, password, secret, token, or privateKey, are written as [redacted]. Business data is not removed automatically, so check device IDs, topics, state values, and third-party user IDs before sharing logs.
Local Troubleshooting Commands
In a source checkout, run these from the repository root:
ls -lh .device_agent/logs
tail -n 200 .device_agent/logs/device-agent-2026-05-11.log
jq 'select(.level == "error")' .device_agent/logs/device-agent-2026-05-11.log
jq 'select(.deviceId == "device-001") | {time, level, module, msg, topic}' \
.device_agent/logs/device-agent-2026-05-11.log
jq 'select(.requestId == "req-...")' .device_agent/logs/device-agent-2026-05-11.logThe Logs page uses these local endpoints:
| Endpoint | Purpose |
|---|---|
GET /api/logs/files | List readable log files. |
GET /api/logs/tail?file=device-agent-2026-05-11.log&lines=200 | Read records from the end of a file. lines is capped at 1000. |
GET /api/logs/tail?file=device-agent-2026-05-11.log&before=<offset> | Read earlier records. Use nextBeforeOffset from the previous response as before. |
GET /api/logs/download?file=device-agent-2026-05-11.log | Download one log file. |
View and Filter Records
After selecting a log file, use these controls to locate a problem:
| Action | Best for |
|---|---|
| Refresh | Check new records after a device comes online, a command is sent, or a conversation finishes. |
| Show earlier records | Load older records when the latest 200 are not enough. |
| Filter by level | Focus on warn or error records. |
| Search message | Search error keywords, platform names, MQTT topics, or model service responses. |
| Filter by module | Inspect a capability area such as MQTT, HTTP, Timer, Workflow, Voice, Tools, or A2A. |
| Search request ID | Trace one HTTP request, conversation, or tool call. |
| Search device ID | Inspect reports, commands, and responses for one device. |
Each record can be expanded to show the full JSON payload. Use the copy button to share one entry, or the download button to export the selected log file.
Filters apply only to loaded records. Load earlier records or switch files to inspect an earlier time or another runtime instance. Platform read and download requests also require the source role and instance identifier; see API Reference.
Log Levels
| Level | Description |
|---|---|
debug | Most detailed. Use temporarily for difficult issues. It can generate many records. |
info | Recommended default. Records startup, connections, requests, and main runtime status. |
warn | Records issues that may affect behavior but do not always fail the workflow. |
error | Records failures and exceptions only. |
For daily use, keep info. If a problem is hard to reproduce, switch to debug temporarily, reproduce the issue, then switch back to info. In local mode, use logging configuration. On the platform, a deployment administrator follows the runtime configuration procedure and checks whether a restart is required.
Configure Logging
In local mode, click Logging configuration on the Logs page to adjust:
| Setting | Purpose |
|---|---|
| Level | Controls how much information is recorded. |
| Console logging | Writes logs to the terminal where the service is running. |
| File logging | Writes logs to files that can be viewed and downloaded from the Logs page. |
| Log directory | Where log files are stored. Relative paths are placed under the Device Agent data directory. |
| Max file size | Splits a log file after it reaches the limit. |
| Retention days | Removes old log files after the retention window. |
| Max total size | Removes older files first when all logs exceed the total size limit. |
| File date timezone | Uses either system time or UTC when generating log file names. |
Saved logging settings are written to local configuration. Matching .env values still override saved settings when the service starts.
Common .env settings:
LOG_LEVEL=info
LOG_CONSOLE_ENABLED=true
LOG_FILE_ENABLED=true
LOG_DIR=logs
LOG_MAX_SIZE_MB=50
LOG_RETENTION_DAYS=14
LOG_MAX_TOTAL_SIZE_MB=1024
LOG_TIMEZONE=systemSee Configuration for other configuration sources.
Common Troubleshooting Paths
| Issue | What to check |
|---|---|
| A device does not appear in the list | Search by device ID and confirm MQTT connection, online status, or telemetry reports. |
| Chat control does not take effect | Search by device ID or request ID to see whether a command was sent and whether the device responded. |
| A scheduled task fails or appears not to run | Check Scheduled Tasks Run history first. For more detail, search the task ID or filter by the Timer module, then correlate any device action with device or MQTT records. |
| An IM bot does not reply | Search by module or platform name to inspect credentials, allow lists, message receiving, and reply delivery. |
| Voice recognition or playback fails | Filter by voice-related modules and inspect voice service, session, and recognition records. |
| A tool or skill does not run | Filter by tool-related modules and inspect tool loading, permissions, and execution results. |
| A model service returns an error | Search by error or model provider name to inspect request failure, authentication failure, or timeout information. |
Before downloading or sharing logs, check sensitive business data as described in Log Record Format.