cisco-perfmon 1.6.1 → 2.0.0

package/.github/workflows/release.yml

@@ -10,7 +10,22 @@ permissions:
   contents: write
 
 jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install dependencies
+        run: npm ci
+
   publish:
+    needs: test
     runs-on: ubuntu-latest
     steps:
       - name: Checkout

package/README.md

@@ -1,92 +1,393 @@
-# Cisco RisPort Library
+# cisco-perfmon
 
-Simple library to pull Perfmon stats from a Cisco CUCM via SOAP.
+A library and CLI for collecting real-time performance counters from Cisco CUCM via the PerfMon SOAP API.
 
-Perfmon information can be found at
-[PerfMon API Reference](https://developer.cisco.com/docs/sxml/#!perfmon-api-reference).
+[![npm](https://img.shields.io/npm/v/cisco-perfmon)](https://www.npmjs.com/package/cisco-perfmon)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![skills.sh](https://img.shields.io/badge/skills.sh-cisco--perfmon--cli-blue)](https://skills.sh/skills/cisco-perfmon-cli)
+[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow?logo=buymeacoffee)](https://buymeacoffee.com/automatebldrs)
+
+Perfmon API reference: [Cisco PerfMon API Reference](https://developer.cisco.com/docs/sxml/#!perfmon-api-reference)
 
 ## Installation
 
-Using npm:
+### As a library
 
-```javascript
-npm i -g npm
+```bash
 npm i --save cisco-perfmon
 ```
 
-## Requirements
+### As a CLI
 
-This package uses the built in Fetch API of Node. This feature was first introduced in Node v16.15.0. You may need to enable expermential vm module. Also you can disable warnings with an optional enviromental variable.
+```bash
+npm install -g cisco-perfmon
+```
 
-Also if you are using self signed certificates on Cisco VOS products you may need to disable TLS verification. This makes TLS, and HTTPS by extension, insecure. The use of this environment variable is strongly discouraged. Please only do this in a lab enviroment.
+## Requirements
 
-Suggested enviromental variables:
+Node.js 18+ is required (uses the built-in Fetch API).
+
+If you are using self-signed certificates on Cisco VOS products you may need to disable TLS verification. **Only do this in a lab environment.**
 
 ```env
-NODE_OPTIONS=--experimental-vm-modules
-NODE_NO_WARNINGS=1
 NODE_TLS_REJECT_UNAUTHORIZED=0
 ```
 
-## Usage
+## CLI Quick Start
+
+```bash
+# Configure a cluster
+cisco-perfmon config add lab --host cucm-pub.example.com --username admin --password secret --insecure
+
+# Verify connectivity
+cisco-perfmon doctor
+
+# List available counter objects
+cisco-perfmon list-objects
+
+# Collect CallManager counters
+cisco-perfmon collect "Cisco CallManager"
+
+# Watch counters live with sparklines
+cisco-perfmon watch "Cisco CallManager" --counter CallsActive,CallsInProgress --interval 5
+```
+
+## CLI Commands
+
+### config -- Manage cluster configurations
+
+```bash
+cisco-perfmon config add <name> --host <host> --username <user> --password <pass>
+cisco-perfmon config use <name>          # switch active cluster
+cisco-perfmon config list                # list all clusters
+cisco-perfmon config show                # show active cluster details
+cisco-perfmon config remove <name>       # remove a cluster
+cisco-perfmon config test                # test connectivity
+```
+
+Supports Secret Server integration for credential management:
 
-Note: Rather than use string with backslashes i.e. "\\cucm3\Cisco CallManager\CallsActive", opted to pass these via JSON to the functions. See below:
+```bash
+cisco-perfmon config add <name> --host '<ss:ID:host>' --username '<ss:ID:username>' --password '<ss:ID:password>'
+```
+
+Or use environment variables instead of config files:
+
+```bash
+export CUCM_HOST=cucm-pub.example.com
+export CUCM_USERNAME=admin
+export CUCM_PASSWORD=secret
+```
+
+Connection precedence: CLI flags > environment variables > config file.
+
+### list-objects -- List available perfmon counter objects
+
+```bash
+cisco-perfmon list-objects                          # all objects
+cisco-perfmon list-objects --search "CallManager"   # filter by keyword
+```
+
+### list-instances -- List instances of a perfmon object
+
+```bash
+cisco-perfmon list-instances "Cisco CallManager"
+cisco-perfmon list-instances "Process" --format json
+```
+
+### describe -- Get counter descriptions
+
+```bash
+cisco-perfmon describe "Cisco CallManager"
+cisco-perfmon describe "Cisco CallManager" --counter CallsActive
+```
+
+### collect -- One-shot counter data collection
+
+```bash
+cisco-perfmon collect "Cisco CallManager"                                         # all counters
+cisco-perfmon collect "Cisco CallManager" --counter CallsActive,CallsInProgress   # specific counters
+cisco-perfmon collect "Cisco CallManager" --instance ""                            # filter by instance
+cisco-perfmon collect "Memory" --format csv > memory.csv                           # export to CSV
+```
+
+### session -- Manage perfmon polling sessions
+
+For fine-grained control over which counters to poll:
+
+```bash
+cisco-perfmon session open                                                        # get a session handle
+cisco-perfmon session add <handle> --counters '[{"host":"cucm","object":"Cisco CallManager","counter":"CallsActive"}]'
+cisco-perfmon session collect <handle>                                             # collect session data
+cisco-perfmon session remove <handle> --counters '[...]'                           # remove counters
+cisco-perfmon session close <handle>                                               # close session
+```
+
+### watch -- Continuous monitoring with live sparklines
+
+The `watch` command is the standout feature for real-time monitoring. It polls counters at a configurable interval and renders a live-updating table with sparkline visualizations showing trends over the last 12 samples.
+
+```bash
+cisco-perfmon watch "Cisco CallManager"                                           # watch all counters
+cisco-perfmon watch "Cisco CallManager" --counter CallsActive --interval 5        # 5-second polling
+cisco-perfmon watch "Processor" --counter "% CPU Time" --instance "_Total"        # CPU monitoring
+cisco-perfmon watch "Memory" --interval 30 --duration 300                         # 5-minute memory check
+```
+
+The table view displays:
+
+| Column    | Description                        |
+|-----------|------------------------------------|
+| counter   | Counter name                       |
+| instance  | Instance name                      |
+| value     | Current value                      |
+| sparkline | Visual trend (last 12 samples)     |
+| min       | Minimum observed value             |
+| max       | Maximum observed value             |
+| avg       | Average across samples             |
+
+Press `Ctrl+C` to stop. A final summary shows iteration count and total duration.
+
+### doctor -- Configuration and connectivity health check
+
+```bash
+cisco-perfmon doctor
+cisco-perfmon doctor --insecure
+```
+
+Runs checks against: active cluster config, PerfMon API connectivity, counter object availability, config file permissions, and audit trail size.
+
+## Output Formats
+
+All commands support four output formats via the `--format` flag:
+
+- `--format table` (default) -- human-readable table
+- `--format json` -- structured JSON for scripting
+- `--format toon` -- token-efficient format for AI agents
+- `--format csv` -- comma-separated values for spreadsheets
+
+## Global Flags
+
+| Flag                | Description                                    |
+|---------------------|------------------------------------------------|
+| `--host <host>`     | Override CUCM hostname                         |
+| `--username <user>` | Override CUCM username                         |
+| `--password <pass>` | Override CUCM password                         |
+| `--cluster <name>`  | Use a specific named cluster                   |
+| `--format <type>`   | Output format: table, json, toon, csv          |
+| `--insecure`        | Skip TLS certificate verification              |
+| `--no-audit`        | Disable audit logging for this command         |
+| `--debug`           | Enable debug logging                           |
+
+## Library Usage
+
+### CommonJS
+
+```javascript
+const perfMonService = require("cisco-perfmon");
+```
+
+### ESM
+
+```javascript
+import perfMonService from "cisco-perfmon";
+```
+
+### Basic example
 
 ```javascript
-const perfMonService = require("../main");
+const perfMonService = require("cisco-perfmon");
 
-// Set up new PerfMon service
-let service = new perfMonService(
-  "10.10.20.1",
-  "administrator",
-  "ciscopsdt"
-);
+const service = new perfMonService("10.10.20.1", "administrator", "ciscopsdt");
 
-var counterObj = {
-  host: cucmServerName,
+const counter = {
+  host: "cucm01-pub",
   object: "Cisco CallManager",
   instance: "",
   counter: "CallsActive",
 };
 
-console.log("Let's get a description of our counter.");
-service
-  .queryCounterDescription(counterObj)
-  .then((response) => {
-    console.log("queryCounterDescription", response.results);
-  })
-  .catch((error) => {
-    console.log(error.message);
-  });
+const result = await service.collectCounterData(counter.host, counter.object);
+console.log(result.results);
 ```
 
-## Examples
+## Constructor
 
 ```javascript
-npm run test
+new perfMonService(host, username, password, options, retry)
+```
+
+| Parameter  | Type    | Default | Description                                      |
+|------------|---------|---------|--------------------------------------------------|
+| `host`     | string  | --      | CUCM IP or FQDN                                  |
+| `username` | string  | --      | AXL/admin username (omit if using SSO cookie)    |
+| `password` | string  | --      | Password (omit if using SSO cookie)              |
+| `options`  | object  | `{}`    | See options below                                |
+| `retry`    | boolean | `true`  | Enable/disable automatic retry                   |
+
+### Options
+
+| Option       | Type   | Default | Description                                                           |
+|--------------|--------|---------|-----------------------------------------------------------------------|
+| `retries`    | number | `3`     | Max retry attempts. Falls back to `PM_RETRY` env var.                 |
+| `retryDelay` | number | `5000`  | Delay in ms between retries. Falls back to `PM_RETRY_DELAY` env var.  |
+| `Cookie`     | string | --      | Session cookie for SSO authentication                                 |
+| _any header_ | string | --      | Additional HTTP headers merged into every request                     |
+
+```javascript
+// Custom retry settings
+const service = new perfMonService("10.10.20.1", "admin", "pass", {
+  retries: 5,
+  retryDelay: 2000,
+});
+
+// SSO cookie auth (no username/password needed)
+const service = new perfMonService("10.10.20.1", "", "", {
+  Cookie: "JSESSIONIDSSO=abc123",
+});
+```
+
+## Rate Limiting
+
+CUCM enforces an 80 requests/minute limit on Perfmon. This library automatically detects that SOAP fault and applies exponential backoff (30s -> 60s -> 120s) before retrying.
+
+## Cookie Management
+
+Cookies returned by CUCM are automatically captured and reused for subsequent requests.
+
+```javascript
+// Get the current stored cookie
+const cookie = service.getCookie();
+
+// Set a cookie manually (e.g. from a prior session)
+service.setCookie("JSESSIONIDSSO=abc123");
+```
+
+## Methods
+
+### `collectCounterData(host, object)`
+
+Collect counter data without a session.
+
+```javascript
+const result = await service.collectCounterData("cucm01-pub", "Cisco CallManager");
+// result.results => [{ host, object, instance, counter, value, cstatus }, ...]
+```
+
+### `collectSessionData(sessionHandle)`
+
+Collect data for an open session.
+
+```javascript
+const result = await service.collectSessionData(sessionHandle);
+```
+
+### `listCounter(host, filtered?)`
+
+List all available counters on a host, with optional name filtering.
+
+```javascript
+const result = await service.listCounter("cucm01-pub");
+const filtered = await service.listCounter("cucm01-pub", ["Cisco CallManager", "Memory"]);
+```
+
+### `listInstance(host, object)`
+
+List instances of a perfmon object.
+
+```javascript
+const result = await service.listInstance("cucm01-pub", "Cisco CallManager");
+```
+
+### `openSession()` / `closeSession(sessionHandle)`
+
+Open and close a polling session.
+
+```javascript
+const opened = await service.openSession();
+const sessionHandle = opened.results;
+// ... collect data ...
+await service.closeSession(sessionHandle);
+```
+
+### `addCounter(sessionHandle, counter)` / `removeCounter(sessionHandle, counter)`
+
+Add or remove counters from an open session. Accepts a single counter object or an array.
+
+```javascript
+await service.addCounter(sessionHandle, {
+  host: "cucm01-pub",
+  object: "Cisco CallManager",
+  instance: "",
+  counter: "CallsActive",
+});
+```
+
+### `queryCounterDescription(counter)`
+
+Get the description of a counter.
+
+```javascript
+const result = await service.queryCounterDescription({
+  host: "cucm01-pub",
+  object: "Cisco CallManager",
+  instance: "",
+  counter: "CallsActive",
+});
 ```
 
 ## Output Examples
 
+```javascript
+// Success
+{
+  host: 'cucm01-pub',
+  object: 'Cisco CallManager',
+  instance: '',
+  counter: 'PRIChannelsActive',
+  value: '0',
+  cstatus: '1'
+}
+
+// Rate limit error (automatically retried with backoff)
+{
+  status: 500,
+  code: 'Internal Server Error',
+  host: 'cucm01-pub',
+  message: 'Exceeded allowed rate for Perfmon information. Current allowed rate for perfmon information is 80 requests per minute.'
+}
 ```
-  Success Example
-  {
-    host: 'cucm01-pub',
-    object: 'Cisco CallManager',
-    instance: '',
-    counter: 'PRIChannelsActive',
-    value: '0',
-    cstatus: '1'
-  }
 
-  Error Example
-  {
-    status: 500,
-    code: 'Internal Server Error',
-    host: 'cucm01-pub',
-    counter: 'SAML SSO',
-    message: 'Exceeded allowed rate for Perfmon information. Current allowed rate for perfmon information is 80 requests per minute.PerfmonService'
-  }
+## Environment Variables
+
+These are supported as fallbacks when constructor options are not provided:
+
+| Variable          | Description                          | Default |
+|-------------------|--------------------------------------|---------|
+| `PM_RETRY`        | Max retry attempts                   | `3`     |
+| `PM_RETRY_DELAY`  | Delay in ms between retries          | `5000`  |
+
+## Related Tools
+
+| Package | Description |
+|---------|-------------|
+| [cisco-axl](https://www.npmjs.com/package/cisco-axl) | Cisco CUCM AXL API library and CLI |
+| [cisco-risport](https://www.npmjs.com/package/cisco-risport) | Cisco CUCM RisPort70 real-time device status |
+| [cisco-ise](https://www.npmjs.com/package/cisco-ise) | Cisco ISE ERS API library and CLI |
+
+## Testing
+
+```bash
+npm test                  # run unit tests
+npm run test:integration  # run integration tests (requires CUCM)
 ```
 
-Note: Test are using Cisco's DevNet sandbox information. Find more information here: [Cisco DevNet](https://devnetsandbox.cisco.com/)
+## Funding
+
+If you find this tool useful, consider supporting development:
+
+[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow?logo=buymeacoffee&style=for-the-badge)](https://buymeacoffee.com/automatebldrs)
+
+## License
+
+MIT

package/bin/cisco-perfmon.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require("../cli/index.js");

package/cli/commands/collect.js

@@ -0,0 +1,48 @@
+const { resolveConfig } = require("../utils/connection.js");
+const { printResult, printError } = require("../utils/output.js");
+const audit = require("../utils/audit.js");
+
+module.exports = function (program) {
+  program
+    .command("collect <object>")
+    .description("Collect perfmon counter data (one-shot)")
+    .option("--counter <names>", "comma-separated counter names to filter")
+    .option("--instance <name>", "filter by instance name")
+    .action(async (object, opts, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const start = Date.now();
+      try {
+        const connConfig = resolveConfig(globalOpts);
+        if (connConfig.insecure) process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+        if (globalOpts.debug) process.env.DEBUG = "cisco-perfmon";
+
+        const PerfMon = require("../../main.js");
+        const svc = new PerfMon(connConfig.host, connConfig.username, connConfig.password);
+        const result = await svc.collectCounterData(connConfig.host, object);
+
+        let rows = Array.isArray(result.results) ? result.results : result.results ? [result.results] : [];
+
+        // Filter by counter names if specified
+        if (opts.counter) {
+          const counterNames = opts.counter.split(",").map((c) => c.trim());
+          rows = rows.filter((r) => counterNames.includes(r.counter));
+        }
+
+        // Filter by instance if specified
+        if (opts.instance) {
+          rows = rows.filter((r) => r.instance === opts.instance);
+        }
+
+        if (globalOpts.audit !== false) {
+          audit.log({ cluster: connConfig.host, command: "collect", args: object, duration_ms: Date.now() - start, status: "success", rows: rows.length });
+        }
+
+        await printResult(rows, globalOpts.format);
+      } catch (err) {
+        if (globalOpts.audit !== false) {
+          try { audit.log({ cluster: "", command: "collect", args: object, duration_ms: Date.now() - start, status: "error", message: err.message }); } catch {}
+        }
+        printError(err);
+      }
+    });
+};

package/cli/commands/config.js

@@ -0,0 +1,85 @@
+const configUtil = require("../utils/config.js");
+const { printResult, printError } = require("../utils/output.js");
+
+module.exports = function (program) {
+  const config = program.command("config").description("Manage CUCM cluster configurations");
+
+  config
+    .command("add <name>")
+    .description("Add a CUCM cluster (requires global --host, --username, --password)")
+    .option("--insecure", "skip TLS verification for this cluster")
+    .action((name, opts, cmd) => {
+      try {
+        const globalOpts = cmd.optsWithGlobals();
+        const host = globalOpts.host;
+        const username = globalOpts.username;
+        const password = globalOpts.password;
+        if (!host) throw new Error("Missing required option: --host");
+        if (!username) throw new Error("Missing required option: --username");
+        if (!password) throw new Error("Missing required option: --password");
+        const clusterOpts = { host, username, password };
+        if (opts.insecure || globalOpts.insecure) clusterOpts.insecure = true;
+        configUtil.addCluster(name, clusterOpts);
+        console.log(`Cluster "${name}" added successfully.`);
+      } catch (err) { printError(err); }
+    });
+
+  config
+    .command("use <name>")
+    .description("Set the active cluster")
+    .action((name) => {
+      try { configUtil.useCluster(name); console.log(`Active cluster set to "${name}".`); }
+      catch (err) { printError(err); }
+    });
+
+  config
+    .command("list")
+    .description("List all configured clusters")
+    .action(async () => {
+      try {
+        const { activeCluster, clusters } = configUtil.listClusters();
+        const rows = Object.entries(clusters).map(([name, c]) => ({
+          name, active: name === activeCluster ? "*" : "", host: c.host, username: c.username,
+        }));
+        if (rows.length === 0) { console.log("No clusters configured. Run: cisco-perfmon config add <name> ..."); return; }
+        await printResult(rows, program.opts().format);
+      } catch (err) { printError(err); }
+    });
+
+  config
+    .command("show")
+    .description("Show active cluster details (masks password)")
+    .action(async () => {
+      try {
+        const cluster = configUtil.getActiveCluster(program.opts().cluster);
+        if (!cluster) { console.log("No active cluster. Run: cisco-perfmon config add <name> ..."); return; }
+        await printResult({ ...cluster, password: configUtil.maskPassword(cluster.password) }, program.opts().format);
+      } catch (err) { printError(err); }
+    });
+
+  config
+    .command("remove <name>")
+    .description("Remove a cluster")
+    .action((name) => {
+      try { configUtil.removeCluster(name); console.log(`Cluster "${name}" removed.`); }
+      catch (err) { printError(err); }
+    });
+
+  config
+    .command("test")
+    .description("Test connection to the active cluster")
+    .action(async (opts, cmd) => {
+      try {
+        const globalOpts = cmd.optsWithGlobals();
+        const { resolveConfig } = require("../utils/connection.js");
+        const connConfig = resolveConfig(globalOpts);
+        if (connConfig.insecure) process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+        const PerfMon = require("../../main.js");
+        const svc = new PerfMon(connConfig.host, connConfig.username, connConfig.password);
+        const result = await svc.listCounter(connConfig.host);
+        const count = Array.isArray(result.results) ? result.results.length : 0;
+        console.log(`Connection validated. PerfMon at ${connConfig.host}:8443 is reachable.`);
+        console.log(`Counter objects available: ${count}`);
+      } catch (err) { printError(err); }
+    });
+};

package/cli/commands/describe.js

@@ -0,0 +1,43 @@
+const { resolveConfig } = require("../utils/connection.js");
+const { printResult, printError } = require("../utils/output.js");
+const audit = require("../utils/audit.js");
+
+module.exports = function (program) {
+  program
+    .command("describe <object>")
+    .description("Describe a perfmon counter")
+    .option("--counter <name>", "counter name to describe")
+    .option("--instance <name>", "instance name")
+    .action(async (object, opts, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const start = Date.now();
+      try {
+        const connConfig = resolveConfig(globalOpts);
+        if (connConfig.insecure) process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+        if (globalOpts.debug) process.env.DEBUG = "cisco-perfmon";
+
+        const PerfMon = require("../../main.js");
+        const svc = new PerfMon(connConfig.host, connConfig.username, connConfig.password);
+
+        const counterObj = {
+          host: connConfig.host,
+          object: object,
+        };
+        if (opts.counter) counterObj.counter = opts.counter;
+        if (opts.instance) counterObj.instance = opts.instance;
+
+        const result = await svc.queryCounterDescription(counterObj);
+
+        if (globalOpts.audit !== false) {
+          audit.log({ cluster: connConfig.host, command: "describe", args: `${object} ${opts.counter || ""}`.trim(), duration_ms: Date.now() - start, status: "success" });
+        }
+
+        await printResult(result.results || result, globalOpts.format);
+      } catch (err) {
+        if (globalOpts.audit !== false) {
+          try { audit.log({ cluster: "", command: "describe", args: object, duration_ms: Date.now() - start, status: "error", message: err.message }); } catch {}
+        }
+        printError(err);
+      }
+    });
+};