> ## Documentation Index > Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt > Use this file to discover all available pages before exploring further. # Logs Command > View and debug agent execution logs ## Overview The `lua logs` command provides an interactive interface for viewing and navigating your agent's execution logs with powerful filtering capabilities. ```bash theme={null} lua logs ``` **Looking for the canonical debug loop?** See [Debugging your agent](/cli/debugging) for the recommended push → test → check flow that uses `lua logs` as the truth source. ## When to run `lua logs` There are three moments when `lua logs` is the most valuable command in the CLI: **1. Immediately after a `lua chat -m "test"`.** A chat response can look fine while the server quietly logged a billing failure, a tool exception, or an LLM provider error. Run `lua logs --type agent_error --limit 5` after every test message — if the count is zero, the test passed cleanly. The CLI also runs a quiet `agent_error` probe automatically after each chat turn and prints a one-line warning when new errors fire (set `LUA_NO_HINTS=1` to silence it). **2. After a `lua push` to verify a new version is healthy in production.** The CLI prints a `✨ Tip:` line at the end of every push pointing at the right `lua logs --type X --limit 10` command for what you just deployed — follow it. **3. When investigating a user-reported issue.** Filter to the affected user with `--user-id ` and to the most likely component type: ```bash theme={null} lua logs --type all --user-id user_abc123 --limit 50 lua logs --type skill --name --user-id user_abc123 --limit 20 ``` ### Non-Interactive Mode ```bash theme={null} # View all logs lua logs --type all --limit 50 # Filter by type lua logs --type skill --limit 20 lua logs --type webhook --limit 20 lua logs --type job --limit 20 # Filter by specific entity lua logs --type skill --name mySkill --limit 10 # Pagination lua logs --type all --limit 20 --page 2 # JSON output for scripting lua logs --type all --json # View logs for a different agent (admin access required) lua logs --agent-id agent-abc123 lua logs --agent-id agent-abc123 --type skill --limit 10 # Voice calls lua logs --type calls # recent voice calls (table) lua logs --type calls --status failed --json # failed calls as JSON ``` | Option | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--type ` | Filter: `all`, `skill`, `job`, `webhook`, `preprocessor`, `postprocessor`, `device`, `device-trigger`, `user_message`, `agent_response`, `agent_error`, `mcp`, `rag`, `runtime`, `calls` | | `--name ` | Entity name (requires --type, not for message types) | | `--user-id ` | Filter logs by user ID | | `--agent-id ` | View logs for a specific agent (overrides the agent in `lua.config.yaml`). Requires admin access to the target agent. | | `--status ` | Filter calls by status (`completed`, `failed`, `in-progress`, etc.). Only with `--type calls`. | | `--limit ` | Number of logs (default: 20) | | `--page ` | Page number for pagination | | `--json` | Output as JSON for scripting | **`--agent-id`** is useful for inspecting logs across multiple agents you own without switching project directories. If you don't have admin access to the requested agent, the command returns an access-denied error. **Type values:** Use `runtime` for platform runtime logs (was previously `mastra`). Use `rag` for knowledge base search logs, `device-trigger` for device trigger execution logs, and `calls` for voice call records. **`agent_error` vs `runtime`:** Use `--type agent_error` to find pipeline failures (billing, validation, LLM provider errors) — these often don't surface in the chat response itself. Use `--type runtime` for agent runtime / LLM SDK / framework-level diagnostics (low-level model and orchestration logs). ## Post-deploy verification recipe ```bash theme={null} # After deploying — generate traffic FIRST lua push all --force --auto-deploy lua chat -e production -m "your test message" # ← generate traffic first lua logs --type skill --limit 10 # ← now logs exist ``` Verify pipeline errors: ```bash theme={null} lua chat -e production -m "verify deploy" -t prod-verify --clear lua logs --type agent_error --limit 5 ``` `lua logs` returns nothing immediately after deploy. You must generate traffic (via `lua chat`, a webhook call, or a job trigger) before execution logs appear. If `agent_error --limit 5` returns no entries timestamped after your deploy, the version is healthy. If it does, read the entries before walking away. See [Debugging your agent](/cli/debugging) for the complete flow. Filter logs by Skills, Jobs, Webhooks, Preprocessors, or Postprocessors View logs for all your components, including dynamically created jobs See which component generated each log, including names and IDs Easily spot errors, warnings, and different log types ## Log Types **Execution errors and failures** * Tool execution failures * API errors * Invalid configurations * Stack traces for debugging Color: Red **Warnings and potential issues** * Performance warnings * Deprecated features * Configuration warnings Color: Yellow **Debug information** * Tool inputs/outputs * Function execution status * Detailed operation info Color: Blue **General information** * Operation status * Configuration changes * General messages Color: Cyan **Operation metrics** * Operation started * Operation completed * Duration measurements Color: Green ## Interactive Flow ``` 📊 Viewing logs for agent: myAgent ? What logs do you want to view? ❯ 📋 All agent logs 🔎 Filter logs ``` ``` ? Filter by: ❯ Skills Jobs Webhooks Preprocessors Postprocessors MCP RAG (knowledge base) Runtime Agent errors Device trigger ────────────────────── 📋 All logs ← Back ``` ``` ? Select a job: ❯ All Jobs ────────────────────── Nightly User Report Daily Cleanup Task ────────────────────── ← Back ``` **All Jobs Visible**: All your jobs appear in the list, including ones created dynamically in your code. ``` All Agent Logs ──────────────────────────────────────────────────── Page 1 of 88 (872 total logs) ❌ [2/3/2025, 4:40:55 PM] ERROR Job Name: Nightly User Report Job ID: job_abc123 Error executing function: Invalid API Key ────────────────────────────────────────────────── ✅ [2/3/2025, 4:40:55 PM] COMPLETE Skill Name: customer-service Skill ID: skill_def456 Tool Name: search_products Duration: 125ms Execute function completed ────────────────────────────────────────────────── ``` ``` ? Navigation: ❯ Next Page → ← Previous Page 🔢 Go to specific page 🔄 Refresh ❌ Exit ``` ## Use Cases ### Debug Tool Errors ```bash theme={null} $ lua logs → Filter logs → Skills → Select your skill → Look for ❌ ERROR entries → Review error messages → Fix issues in your code ``` ### Monitor Performance ```bash theme={null} $ lua logs → Filter logs → Select component type → Find ✅ COMPLETE entries → Check duration metrics → Identify slow operations ``` ### Verify Tool Execution ```bash theme={null} $ lua logs → Filter logs → Skills → Select your skill → Look for 🔍 DEBUG entries → Verify tool inputs/outputs ``` ### Track Webhook Activity ```bash theme={null} $ lua logs → Filter logs → Webhooks → Select your webhook → Review webhook execution logs → Check request/response data → Debug external integrations ``` ### Monitor Job Execution ```bash theme={null} $ lua logs → Filter logs → Jobs → Select your job → View scheduled job execution logs → Check for errors or performance issues ``` ## Example Session ```bash theme={null} $ lua logs ✅ Authenticated 📊 Viewing logs for agent: myAgent ? What logs do you want to view? 🔎 Filter logs ? Filter by: Jobs ? Select a job: Nightly User Report All Agent Logs ──────────────────────────────────────────────────────────────────────────────── Page 1 of 12 (120 total logs) ▶️ [11/7/2025, 10:30:00 AM] START Job Name: Nightly User Report Job ID: job_abc123 Duration: 150ms Starting job execution... ────────────────────────────────────────────────────────────────────────────── ✅ [11/7/2025, 10:30:05 AM] COMPLETE Job Name: Nightly User Report Job ID: job_abc123 Duration: 5234ms Job execution completed successfully ────────────────────────────────────────────────────────────────────────────── ? Navigation: Next Page → [Shows page 2...] ``` ### Filtering by Skill ```bash theme={null} $ lua logs ? What logs do you want to view? 🔎 Filter logs ? Filter by: Skills ? Select a skill: customer-service All Agent Logs ──────────────────────────────────────────────────────────────────────────────── Page 1 of 25 (250 total logs) ℹ️ [11/7/2025, 10:31:15 AM] INFO Skill Name: customer-service Skill ID: skill_def456 Tool Name: search_products Fetching products matching query... ────────────────────────────────────────────────────────────────────────────── ✅ [11/7/2025, 10:31:16 AM] COMPLETE Skill Name: customer-service Skill ID: skill_def456 Tool Name: search_products Duration: 89ms Found 15 products matching "laptop" ────────────────────────────────────────────────────────────────────────────── ``` ## Log Entry Details Each log entry shows you: ### For Skill Logs * **Skill Name** - Which skill generated the log * **Skill ID** - Unique identifier for the skill * **Tool Name** - Which tool was running (if applicable) * **Timestamp** - When the log was created * **Log Type** - Error, debug, info, warn, start, or complete * **Message** - The actual log message * **Duration** - How long the operation took (for completed operations) ### For Job Logs * **Job Name** - Which job generated the log * **Job ID** - Unique identifier for the job * **Timestamp** - When the log was created * **Log Type** - Error, debug, info, warn, start, or complete * **Message** - The actual log message * **Duration** - How long the job took to run ### For Webhook, Preprocessor, and Postprocessor Logs * **Name** - Which component generated the log * **ID** - Unique identifier * **Timestamp** - When the log was created * **Log Type** - Error, debug, info, warn, start, or complete * **Message** - The actual log message * **Duration** - How long the operation took **Tool Information**: Tool names are only shown for skill logs, since tools belong to skills. ## Navigation Options View the next page of logs Disabled if on last page Go back to previous page Disabled if on first page ``` ? Enter page number (1-88): 45 ``` Jump directly to any page Reload current page with latest logs Useful for monitoring in real-time Close the logs viewer ## Best Practices ```bash theme={null} # Get overview first lua logs → All agent logs # Then filter if needed lua logs → Specific skill logs ``` ```bash theme={null} # After deploying — generate traffic FIRST lua push all --force --auto-deploy lua chat -e production -m "your test message" # ← generate traffic first lua logs --type skill --limit 10 # ← now logs exist lua logs → All agent logs → Refresh periodically ``` ```bash theme={null} # Issue with specific skill lua logs → Specific skill logs → Select problem skill # Focus on errors # Look for ❌ ERROR entries ``` ```bash theme={null} # Check operation speed lua logs → All agent logs # Note duration on ✅ COMPLETE entries # Identify slow operations (>1000ms) ``` ## Troubleshooting **Causes:** * Skills not deployed yet * Agent hasn't been used * Viewing wrong agent **Solution:** ```bash theme={null} lua push # Deploy skills lua chat # Use agent to generate logs lua logs # View logs ``` **Try:** * Navigate through pages using the navigation menu * Filter by the specific component (skill, job, etc.) * Check the most recent pages first (page 1) * Look at the timestamp to find when the error occurred **Use refresh:** ``` ? Navigation: 🔄 Refresh ``` Reloads current page with latest data ## Integration with Workflow ### During Development ```bash theme={null} # Make changes vim src/tools/MyTool.ts # Test lua chat # Check logs immediately lua logs # Look for errors or warnings ``` ### After Deployment ```bash theme={null} # Deploy lua push && lua deploy # Monitor logs lua logs # Watch for errors in production # Check performance metrics ``` ### Debugging Issues ```bash theme={null} # User reports an issue lua logs # Find the relevant error in the logs # Note the timestamp and which component had the error # Fix the issue in your code # Deploy the fix # Monitor logs again to verify the fix ``` ## Related Commands Canonical push → test → check flow Test agent (generates logs + auto agent\_error probe) Test tools locally (no remote logs) Deploy skills (required for logs) ## Next Steps Generate logs to view Push skills to generate logs Common issues and solutions Monitor production environment