This script addresses a specific use case of monitoring for TCAM exhaustion for networks leveraging Cisco Security Group Tags. To date Cisco's management platforms do not collect these metrics. The script retrieves TCAM stats for SGT bindings, security acls, and IP bindings.

PyATS Command Collector

Python utility to connect to Cisco switches, parse command output with PyATS/Genie, and optionally write structured JSON.

It can also write slim TCAM metrics directly into InfluxDB for use in a TIG stack.

Setup

1. Activate your virtual environment.
2. Install dependencies:

pip install -r requirements.txt

1. Create InfluxDB environment file (if using TIG integration):

cp influx.env.example influx.env
# Edit influx.env with your InfluxDB credentials and endpoint

Usage

Option 1: Existing testbed YAML

python scripts/collect_pyats_command.py \
  --testbed testbed.yaml \
  --device sw1 \
  --command "show interfaces status" \
  --output outputs/sw1_interfaces.json

Option 2: Direct host arguments

python scripts/collect_pyats_command.py \
  --host 10.10.10.10 \
  --username admin \
  --device sw1 \
  --command "show version" \
  --output outputs/sw1_version.json

Option 3: Multi-switch inventory YAML

The inventory file specifies switches with their credentials and model. Commands are determined by model from the script:

python scripts/collect_pyats_command.py \
  --inventory inventories/switches.example.yaml \
  --output outputs/tcam_multi_switch.json

• 9300 model: Uses show platform hardware fed switch active fwd-asic resource tcam utilization
• 9400 model: Uses show platform hardware fed active fwd-asic resource tcam utilization

You can override the command for all switches:

python scripts/collect_pyats_command.py \
  --inventory inventories/switches.example.yaml \
  --command "show version" \
  --output outputs/tcam_multi_switch.json

Option 4: Send directly to TIG (InfluxDB)

First, create influx.env from the example:

cp influx.env.example influx.env
# Edit influx.env with your InfluxDB v2 credentials

Then use it for InfluxDB v2:

source influx.env
python scripts/collect_pyats_command.py \
  --inventory inventories/switches.example.yaml \
  --no-output \
  --influx-write \
  --influx-url "$INFLUX_URL" \
  --influx-org "$INFLUX_ORG" \
  --influx-bucket "$INFLUX_BUCKET" \
  --influx-token "$INFLUX_TOKEN"

Or for InfluxDB v1, update influx.env with v1 credentials instead:

python scripts/collect_pyats_command.py \
  --inventory inventories/switches.example.yaml \
  --no-output \
  --influx-write \
  --influx-url http://localhost:8086 \
  --influx-db network \
  --influx-user telegraf \
  --influx-password 'replace-me'

Measurement name defaults to tcam_utilization and can be changed with --influx-measurement.

You will be prompted for password if not provided through --password.

Continuous Collection with Runner

To run collection repeatedly at a fixed interval:

./scripts/runner.sh 300

This will run collection every 300 seconds (5 minutes), continuously.
This runs in Influx-only mode and does not write local JSON files. Press Ctrl+C to stop.

The runner requires influx.env to be configured with your InfluxDB credentials.
This path is cross-platform for Unix-like systems (macOS/Linux) and does not depend on launchd.

For Windows, use python scripts/collect_pyats_command.py ... with Task Scheduler at your desired interval.

Optional: macOS launchd Scheduling

The ops/ directory is optional. It contains a macOS LaunchAgent plist for users who prefer launchd instead of running ./scripts/runner.sh directly.

If you do not use launchd, you can ignore ops/com.tcam.monitor.ingest.plist.

Notes

• Parsed output depends on Genie parser support for the specific command and platform.
• If parser support is missing, use --raw-fallback to store raw text under data.raw_output.
• Use --no-output to skip writing local JSON files.
• Parsed output is filtered to only include: CTS Cell Matrix, Security ACL, and IP Route Table (EM/TCAM) resources.
• InfluxDB points are written per device/ASIC/table/subtype/direction with numeric fields: max, used, used_percent, v4, v6, mpls, other.