These are the essential building blocks that make SuzieQ function as a powerful modern network observability platform:

• Collector: Connects to multi-vendor network devices using SSH or REST APIs. Gathers operational and configuration data through device-specific commands or API endpoints, all without requiring agents.
• Normalizer: Transforms raw vendor-specific data into a unified, vendor-neutral schema. This makes it possible to query and analyze heterogeneous device data in a consistent and efficient manner.
• Data Store: Stores all acquired and normalized data in an optimized big-data format (commonly Apache Parquet). Supports both point-in-time and historical analysis, enabling trend tracking and robust audits.
• Query Engine: The brain of SuzieQ. Facilitates fast, flexible search and analysis across all managed network data—whether through CLI, Python, GUI, or API interfaces.
• Interfaces: Provides multiple user options (command-line, GUI, REST API, Python library) for interacting with and visualizing network data, accommodating both script-driven and visual workflows.

Before deploying or using SuzieQ, you’ll need to have the following components and configurations in place:

• Python Environment: A functioning installation of Python 3.8 or newer. It’s recommended to use a virtual environment for dependency management and isolation.
• Network Device Access: Login credentials with at least read-only privileges on all devices you want SuzieQ to monitor. Devices must support SSH or REST API access depending on the platform.
• Supported Network Platforms: Ensure that your network devices are from vendors or OS versions supported by SuzieQ (such as Arista EOS, Cisco NX-OS, Juniper Junos, Cumulus Linux, Palo Alto, and SONiC).
• Host System Requirements: A Linux-based system (Ubuntu or CentOS recommended) with minimum 2 CPU cores, 4GB RAM, and access to the internet for package installations.
• Python Packages: Required packages such as pandas, pyarrow, and rich should be installed. These are usually handled automatically through the SuzieQ installation process using pip.
• SuzieQ Installation: SuzieQ should be installed either via pip, Docker, or from source. Use the method that aligns with your operational model (development vs production).

Once SuzieQ is installed, the next step is to configure it to connect to and collect data from your network devices. Below is a step-by-step outline of what needs to be configured:

• Inventory File: Create an inventory file in YAML or JSON format defining the devices SuzieQ should connect to. This includes device names, IP addresses, operating systems, connection methods (SSH or API), user credentials, and ports.
• Authentication Credentials: Store SSH credentials or API tokens securely. SuzieQ can use environment variables, plaintext files (for testing), or more secure vault integrations to access these details during connection.
• Service Configuration (suzieqd): Set up the configuration for the SuzieQ daemon using its CLI or configuration files. This includes paths to inventory files, data storage directories, and scheduling intervals for data collection.
• Data Collection Scheduling: Define collection frequency using crontab or internal scheduling logic depending on how suzieqd is deployed. This ensures up-to-date snapshots of your network state.
• Normalization Rules (Optional): Adjust or extend the normalization logic if operating in unique environments or using custom device commands. This allows you to tailor SuzieQ behavior to specific vendor implementations.
• Log & Debug Settings: Configure logging for troubleshooting and operational visibility. Set verbosity level and log file location to capture relevant runtime information.

After configuring SuzieQ, it’s important to validate that your network state aligns with expectations and that changes have not introduced errors. Here’s a step-by-step guide to using SuzieQ for network validation:

• Pre-Change Snapshot: Before making any network changes, capture a snapshot of the network state using SuzieQ. This serves as a baseline for later comparison.
• Implement Network Changes: Apply your intended configuration updates or changes across the relevant network devices.
• Post-Change Snapshot: Run SuzieQ again to collect a fresh set of data. This allows for direct comparison with the pre-change state.
• Assertion Checks: Use SuzieQ’s built-in assertion tools (such as interface assert, bgp assert, ospf assert) to verify that the network’s operational state meets the desired conditions. These checks evaluate aspects like interface status, BGP session state, MTU consistency, and more.
• Automated Test Cases: Integrate SuzieQ queries and assertions into automation pipelines or CI/CD workflows. This enables repeatable, automated validation after every change and helps catch issues before they impact production.
• Review and Audit Results: Inspect validation outputs, focusing on any failed assertions or inconsistencies. Investigate and address anomalies as needed to ensure network health and compliance.

By following this validation workflow, you can confidently confirm that network changes are successful, safe, and aligned with operational intent.

If you encounter issues with SuzieQ or your network data collection, follow these systematic steps to identify and resolve common problems:

• Check Service Status: Ensure that all SuzieQ services and related containers are running. For Docker-based deployments, use commands like docker-compose ps to view the status, and docker-compose logs -f for real-time logs.
• Review Log Files: Examine log files located on your host system or within containers (such as /tmp/sq-poller.log) for error messages or failures during data collection.
• Verify Device Connectivity: Confirm that SuzieQ can reach all target devices via SSH or REST API, and that proper credentials are in place. Use basic network tools or SuzieQ’s CLI to test connectivity.
• Use Built-in Poller Checks: Run suzieq-cli sqpoller show --status=fail to list all failed device polls and investigate the reported reasons (such as incorrect credentials or unreachable devices).
• Diagnose Network Issues with Queries: Utilize SuzieQ commands like interface summarize, interface top what=flaps, path, and tracepath to identify and analyze interface errors, routing inconsistencies, or abnormal path selections.
• Check for Data Collection Gaps: Monitor for polling interval overruns or skipped collections in the poller summary. Look for patterns in the pollExcdPeriodCount field indicating possible systemic slowness or device overload.
• Review Recent Changes: If new errors appear shortly after a network configuration change, use before-and-after queries or assertions in SuzieQ to identify what has changed and which devices or links are affected.
• Consult Documentation and Support: Refer to the official SuzieQ documentation for advanced troubleshooting tips or use the community forums and GitHub issues page to seek assistance for complex or persistent issues.

Consistently following these steps will help you quickly detect and address common operational challenges, keeping your observability environment and network healthy.