{"id":7680,"library":"robocorp-log","title":"Robocorp Log","description":"Robocorp Log provides automatic trace logging capabilities for Python applications, primarily used within the Robocorp automation ecosystem. It automatically captures function calls, arguments, return values, and exceptions, generating structured log data for debugging and analysis. The current version is 3.1.2. It is part of the broader Robocorp framework, with releases often aligned with other components of the Robocorp ecosystem rather than having a standalone, independent cadence.","status":"active","version":"3.1.2","language":"en","source_language":"en","source_url":"https://github.com/robocorp/robocorp/tree/master/log","tags":["logging","automation","robotic process automation","rpa","trace","structured logging"],"install":[{"cmd":"pip install robocorp-log","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"Main module for logging utilities.","symbol":"robocorp.log","correct":"import robocorp.log"},{"note":"Used to explicitly enable automatic logging if not in a Robocorp-managed environment.","symbol":"setup_auto_logging","correct":"from robocorp.log import setup_auto_logging"},{"note":"Used to direct logs to a specific output directory, primarily for file-based logs.","symbol":"add_log_output","correct":"from robocorp.log import add_log_output"}],"quickstart":{"code":"import os\nfrom robocorp.log import setup_auto_logging, add_log_output\nfrom pathlib import Path\nimport shutil\n\n# Define a directory for log output\nlog_output_dir = Path(\"temp_robocorp_log_output\")\n\n# Ensure the log directory is clean before starting\nif log_output_dir.exists():\n    shutil.rmtree(log_output_dir)\nlog_output_dir.mkdir(parents=True, exist_ok=True)\n\n# Add the log output target. This is crucial for logs to be written to a file.\nadd_log_output(log_output_dir)\n\n# Manually set up auto-logging.\n# In a Robocorp-managed run (e.g., Robocorp Lab/Assistant), this is often automatic.\nsetup_auto_logging()\n\ndef process_data(value: str, count: int):\n    \"\"\"A sample function to demonstrate automatic logging.\"\"\"\n    print(f\"Processing value: {value} for {count} times\")\n    intermediate_result = f\"Transformed_{value}\"\n    final_result = f\"{intermediate_result}_{count}\"\n    if count > 1:\n        print(\"Simulating a loop...\")\n        for i in range(count):\n            print(f\"  Iteration {i+1}\")\n    return final_result\n\nif __name__ == \"__main__\":\n    # Use environment variable for example input, common in automation\n    input_value = os.environ.get('ROBOCORP_LOG_TEST_VALUE', 'sample_item')\n    input_count = int(os.environ.get('ROBOCORP_LOG_TEST_COUNT', '1'))\n    \n    print(f\"Starting demonstration with value='{input_value}', count={input_count}\")\n    result = process_data(input_value, input_count)\n    print(f\"Demonstration finished. Result: {result}\")\n    print(f\"\\nLogs (e.g., .robocorp_log, .html) can be found in: {log_output_dir.absolute()}\")\n    print(\"To view structured logs, use Robocorp Lab or a compatible viewer.\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Extensive or deeply nested automatic logging can generate very large log files, potentially impacting performance and storage, especially for long-running or complex processes.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"`robocorp-log` was not properly initialized to write to a specific output or `setup_auto_logging()` was not called.","error":"No .robocorp_log file or log.html is generated in the output directory."},{"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.","cause":"You've upgraded to `robocorp-log` version 3.0.0 or later, which switched to the `.robocorp_log` binary format.","error":"My existing log parser for `output.xml` or custom JSON logs is failing after upgrading `robocorp-log`."},{"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.","cause":"`robocorp-log` by default captures all function arguments and return values, including potentially sensitive ones.","error":"Sensitive data (e.g., API keys, passwords) is visible in my generated logs."}]}