{"id":7542,"library":"pyats-log","title":"pyATS Log: Logging Format and Utilities","description":"pyATS Log is a sub-component of the Cisco pyATS (Python Automated Test System) ecosystem, providing logging format and utilities. It configures the standard Python logging module to output in a Cisco log format, integral for network automation and testing workflows. The library is currently at version 26.3 and follows a frequent, often monthly or bi-monthly, release cadence as part of the broader pyATS framework.","status":"active","version":"26.3","language":"en","source_language":"en","source_url":"https://github.com/CiscoTestAutomation/pyats","tags":["logging","network-automation","cisco","pyats","testing"],"install":[{"cmd":"pip install pyats-log","lang":"bash","label":"Install pyats-log"},{"cmd":"pip install pyats","lang":"bash","label":"Recommended: Install full pyATS framework (includes pyats-log)"}],"dependencies":[{"reason":"Core framework that pyats-log integrates with and extends. When installing `pyats-log` directly, `pyats` is typically a dependency.","package":"pyats","optional":false}],"imports":[{"note":"The primary way to interact with pyATS logging, as it wraps the standard Python logging module.","symbol":"logging","correct":"import logging"},{"note":"The 'banner' utility for log formatting is directly imported from `pyats.log.utils`.","wrong":"import pyats.log.utils.banner","symbol":"banner","correct":"from pyats.log.utils import banner"}],"quickstart":{"code":"import logging\nfrom pyats.log.utils import banner\n\n# Get a logger instance; pyATS configures it to Cisco log format automatically\nlogger = logging.getLogger(__name__)\n\n# Log some messages\nlogger.info('Starting a pyATS-driven task.')\nlogger.debug('Detailed debug information for troubleshooting.')\nlogger.warning('This is a warning that something might be off.')\nlogger.error('An error occurred during processing!')\n\n# Use a pyATS log utility for visual separation\nlogger.info(banner('Task Completed'))","lang":"python","description":"This quickstart demonstrates how to obtain a standard Python logger instance, which `pyATS` automatically configures for Cisco log format output. It also shows the use of a specific `pyats.log.utils` helper, `banner`, for improved log readability."},"warnings":[{"fix":"Run pyATS on a supported operating system (Linux or macOS), or within a Linux-based virtual machine or Docker container on Windows.","message":"pyATS and its sub-components, including `pyats-log`, officially support Python 3.8+ on Linux and Mac systems. Windows platforms are explicitly not supported, which can lead to unexpected behavior or installation failures.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of automatic log generation. Manage generated log files through cleanup scripts or direct deletion. For specific cases, consult the latest pyATS documentation or GitHub issues for potential configuration options to reduce logging verbosity or location, though full disabling may not be available.","message":"When running pyATS scripts, particularly those involving device connections, the framework automatically generates log files (e.g., `[device]-cli-[timestamp].log`) in the script directory. This behavior cannot always be easily disabled and might be unexpected, leading to numerous log files accumulating.","severity":"gotcha","affected_versions":"All versions, including 25.7 where it was a known issue."},{"fix":"Upgrade your Python environment to Python 3.10 or a later supported version (e.g., Python 3.11, 3.12, 3.13 as pyATS prepares for their support).","message":"pyATS has ceased official support for Python 3.9. Projects still running on Python 3.9 will not receive updates or fixes and may encounter compatibility issues with newer pyATS versions.","severity":"breaking","affected_versions":"Versions 25.11 and later (from November 2025 onwards)"},{"fix":"Use `pyats logs view` exclusively for logs produced by pyATS jobs. For parsing general syslog or other formatted text logs, utilize dedicated parsing libraries or custom scripts (e.g., using `Genie` parsers within the pyATS ecosystem if the logs are from Cisco devices).","message":"The `pyats logs view` CLI command is designed to view logs *generated by pyATS runs*, not for parsing arbitrary syslog files or general text log files. Attempting to use it on non-pyATS logs will often result in an empty display or parsing errors.","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":"This is a known behavior of the pyATS framework. There is no direct configuration to completely disable these files. Implement post-execution cleanup scripts to remove unwanted log files or configure your `pyats run job` command to output to a specific, temporary directory that can be cleared.","cause":"pyATS automatically generates log files for device interactions as part of its core functionality, which is not easily configurable to be disabled.","error":"PyATS: Cannot disable pyats log file from being created"},{"fix":"Ensure `pyats` is installed in your active Python environment using `pip install pyats` (recommended for full functionality) or `pip install pyats-log` if you only need the logging component. Activate the correct virtual environment if one is being used.","cause":"The `pyats-log` package or the broader `pyats` framework is either not installed, or the Python environment where the script is run does not have access to the installed package.","error":"ModuleNotFoundError: No module named 'pyats.log.utils'"},{"fix":"Only use `pyats logs view` for log archives created by `pyats run job`. For parsing network device syslog or debug outputs, leverage `Genie` parsers, which are part of the pyATS ecosystem, or write custom Python parsing logic.","cause":"The `pyats logs view` command is intended for viewing logs generated by pyATS's internal execution engine, not for general syslog files or arbitrary text logs.","error":"pyats logs view /path/to/my/syslog.log -> (empty browser window or parsing errors)"}]}