pyATS Log: Logging Format and Utilities

Common errors

• PyATS: Cannot disable pyats log file from being created

  cause pyATS automatically generates log files for device interactions as part of its core functionality, which is not easily configurable to be disabled.
  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.

• ModuleNotFoundError: No module named 'pyats.log.utils'

  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.
  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.

• pyats logs view /path/to/my/syslog.log -> (empty browser window or parsing errors)

  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.
  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.

Warnings

• gotcha 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.
  Fix: Run pyATS on a supported operating system (Linux or macOS), or within a Linux-based virtual machine or Docker container on Windows.
• gotcha 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.
  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.
• breaking 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.
  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).
• gotcha 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.
  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).

Install

• pip install pyats-log Install pyats-log
• pip install pyats Recommended: Install full pyATS framework (includes pyats-log)

Imports

• logging

  import logging

  The primary way to interact with pyATS logging, as it wraps the standard Python logging module.
• banner
  wrong:

  import pyats.log.utils.banner

  correct:

  from pyats.log.utils import banner

  The 'banner' utility for log formatting is directly imported from `pyats.log.utils`.

Quickstart

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.

import logging
from pyats.log.utils import banner

# Get a logger instance; pyATS configures it to Cisco log format automatically
logger = logging.getLogger(__name__)

# Log some messages
logger.info('Starting a pyATS-driven task.')
logger.debug('Detailed debug information for troubleshooting.')
logger.warning('This is a warning that something might be off.')
logger.error('An error occurred during processing!')

# Use a pyATS log utility for visual separation
logger.info(banner('Task Completed'))