Robocorp Log

Common errors

• No .robocorp_log file or log.html is generated in the output directory.

  cause `robocorp-log` was not properly initialized to write to a specific output or `setup_auto_logging()` was not called.
  fix Ensure you call `from robocorp.log import add_log_output, setup_auto_logging` and then `add_log_output(Path('your_log_directory'))` and `setup_auto_logging()` at the start of your script, especially when running outside the Robocorp environment.

• My existing log parser for `output.xml` or custom JSON logs is failing after upgrading `robocorp-log`.

  cause You've upgraded to `robocorp-log` version 3.0.0 or later, which switched to the `.robocorp_log` binary format.
  fix Your old log parsing logic is incompatible. You need to update your parsers to handle the new `.robocorp_log` format. Consult Robocorp's documentation for tools or libraries that can read this new format, or rely on Robocorp's own log viewing tools.

• Sensitive data (e.g., API keys, passwords) is visible in my generated logs.

  cause `robocorp-log` by default captures all function arguments and return values, including potentially sensitive ones.
  fix Use `robocorp.log.omit_secrets(value)` to redact specific values or `robocorp.log.add_sensitive_variables(variable_names)` to declare variables whose contents should be hidden in logs.

Warnings

• breaking robocorp-log version 3.0.0 introduced a new structured log format (`.robocorp_log`) replacing older custom JSON or `output.xml` formats. Custom log parsers written for pre-3.0.0 versions will break.
  Fix: Update any custom log parsing logic to read the new `.robocorp_log` binary format. Robocorp tools like Robocorp Lab or Assistant automatically handle this format. Consider using `robocorp-log`'s own log viewing capabilities or converting to HTML for easier inspection.
• gotcha When running outside a Robocorp-managed environment (e.g., Robocorp Lab, Assistant, Control Room), automatic logging needs explicit setup. Without `setup_auto_logging()` and `add_log_output()`, no log files will be generated.
  Fix: Always call `from robocorp.log import setup_auto_logging, add_log_output` and then `add_log_output(Path('your_log_dir'))` and `setup_auto_logging()` at the start of your script if you expect file-based logs outside of a Robocorp run.
• gotcha By default, `robocorp-log` captures all function arguments and return values. This can lead to sensitive information (e.g., API keys, passwords) being recorded in the logs.
  Fix: Use `robocorp.log.omit_secrets` as a context manager or `robocorp.log.add_sensitive_variables` to mark specific variables or function arguments for redaction in the logs.
• gotcha Extensive or deeply nested automatic logging can generate very large log files, potentially impacting performance and storage, especially for long-running or complex processes.
  Fix: Consider disabling auto-logging for specific functions or modules using `robocorp.log.exclude_methods_from_auto_logging` or tuning the level of detail if log file size becomes an issue. Only enable auto-logging for critical paths.

Install

• pip install robocorp-log Install latest version

Imports

• robocorp.log

  import robocorp.log

  Main module for logging utilities.
• setup_auto_logging

  from robocorp.log import setup_auto_logging

  Used to explicitly enable automatic logging if not in a Robocorp-managed environment.
• add_log_output

  from robocorp.log import add_log_output

  Used to direct logs to a specific output directory, primarily for file-based logs.

Quickstart

This quickstart demonstrates how to manually set up `robocorp-log` to capture execution traces of Python functions. It configures a temporary directory for log output and explicitly calls `setup_auto_logging()` to enable the automatic instrumentation. Run this script, then inspect the generated files (e.g., `.robocorp_log`, `log.html`) in the `temp_robocorp_log_output` directory.

import os
from robocorp.log import setup_auto_logging, add_log_output
from pathlib import Path
import shutil

# Define a directory for log output
log_output_dir = Path("temp_robocorp_log_output")

# Ensure the log directory is clean before starting
if log_output_dir.exists():
    shutil.rmtree(log_output_dir)
log_output_dir.mkdir(parents=True, exist_ok=True)

# Add the log output target. This is crucial for logs to be written to a file.
add_log_output(log_output_dir)

# Manually set up auto-logging.
# In a Robocorp-managed run (e.g., Robocorp Lab/Assistant), this is often automatic.
setup_auto_logging()

def process_data(value: str, count: int):
    """A sample function to demonstrate automatic logging."""
    print(f"Processing value: {value} for {count} times")
    intermediate_result = f"Transformed_{value}"
    final_result = f"{intermediate_result}_{count}"
    if count > 1:
        print("Simulating a loop...")
        for i in range(count):
            print(f"  Iteration {i+1}")
    return final_result

if __name__ == "__main__":
    # Use environment variable for example input, common in automation
    input_value = os.environ.get('ROBOCORP_LOG_TEST_VALUE', 'sample_item')
    input_count = int(os.environ.get('ROBOCORP_LOG_TEST_COUNT', '1'))
    
    print(f"Starting demonstration with value='{input_value}', count={input_count}")
    result = process_data(input_value, input_count)
    print(f"Demonstration finished. Result: {result}")
    print(f"\nLogs (e.g., .robocorp_log, .html) can be found in: {log_output_dir.absolute()}")
    print("To view structured logs, use Robocorp Lab or a compatible viewer.")