Logs

Logs are detailed records of every time an action runs. They show you exactly what happened during each execution, helping you understand what your agents are doing and troubleshoot any issues.

What are Logs?

A log is a record of a single execution of an action. Each log tracks execution progress step-by-step, records timing information, captures errors, links to outputs (documents created), and shows status. Logs are created automatically when an action starts running. As the action executes, log entries are added in real-time using app.log() calls in your action code.

Understanding Log States

Logs can be in one of four states: running (action is currently executing, log updates in real-time), done (action completed successfully), error (action encountered an error and stopped), or stopped (action was manually stopped).

Creating Log Entries in Actions

Logs are created by your action code using the app.log() function. There are three types: step logs (app.log(step="...") for major milestones, shown in bold), info logs (app.log("...") for detailed progress messages), and error logs (app.log(error="...") for error messages). Only use step in the run() method for high-level phases. Each step should be followed by at least one info message.

When you create a document with app.doc(), it's automatically linked in the log.

Reading Logs

Logs are organized into step groups (each major step shown as a heading with progress messages underneath), progress messages (detailed info messages within each step), timing information (timestamps for each log entry), document links (when actions create documents), and error messages (clearly displayed if something goes wrong).

Real-Time Updates

When an action is running, its log updates in real-time as your code calls app.log(). Log entries appear immediately, steps and messages update live, you can see exactly where the action is in its workflow, and errors appear instantly. This real-time visibility helps you understand what's happening and catch issues early.

Using Logs Effectively

Monitoring Active Actions: Watch logs update in real-time to see which step it's on, what progress it's making, and whether it's encountering issues.

Troubleshooting Problems: If an action fails, the log shows what failed (error message), where it failed (step and message), and context (previous steps and messages).

Understanding Performance: Logs help you see execution time, identify slowest steps by comparing timestamps, and track how often actions run successfully.

Reviewing History: By reviewing past logs, you can verify actions are running as expected, track changes in execution time or behavior, and identify patterns or recurring issues.

Log Features

Logs update in real-time as app.log() is called. You can filter logs by action, agent, status (running, done, error, stopped), or date. Click on any log to see complete step-by-step execution, all progress messages, timing for each log entry, links to created documents, and error details.

Best Practices for Logging

When writing action code: use steps for major phases (app.log(step="...")), add info messages (at least one app.log("...") per step), be descriptive (write clear, non-technical messages), log progress for pagination (e.g., "Loading companies 15%..."), and group by steps (every step should have associated info messages).

Troubleshooting

Log shows "Error" state: Check the error message, look at the step where the error occurred, review previous steps for context, use chat to ask for help fixing the error.

Action seems stuck in "Running" state: Check if logs are updating, look at the last log entry, stop manually if needed, check for infinite loops or blocking operations.

Log entries are unclear: Improve logging in your action code, use chat to ask for better logging messages, add more app.log() calls.

Can't find a specific log: Use filters to narrow down by action, agent, or date, check if the action actually ran, look at the action's log history page.

Log Retention

Logs are retained so you can review historical execution data, track changes over time, debug issues that occurred in the past, and audit what actions have been doing.

Next Steps

Now that you understand logs, view recent logs, monitor running actions, review error logs, improve logging in your actions, and analyze performance using timing information.

Logs are your window into what your agents are doing. They provide transparency, help you troubleshoot issues, and give you confidence that your automated workflows are running correctly.