PerfMon Client

The PerfMonClient provides performance counter collection from UCM servers via the PerfMon SXML API. Counters can be collected in session-based mode (open → add → collect → close) or via one-shot queries.

Quick Example

from axltoolkit import PerfMonClient

pm = PerfMonClient(
    username="admin",
    password="secret",
    server_ip="ucm-pub.example.com",
    tls_verify=True,
)

session = pm.open_session()
pm.add_counters(session, [r"\\cm-pub\Cisco CallManager\CallsCompleted"])
data = pm.collect_session_data(session)
pm.close_session(session)

Class Reference

axltoolkit.perfmon.PerfMonClient

PerfMonClient(username: str, password: str, server_ip: str, *, tls_verify: Union[bool, str] = True, timeout: int = 30, max_retries: int = 3)

Bases: BaseClient

Client for the Cisco UCM PerfMon SXML API.

The PerfMon service provides performance counter data from UCM servers. Counters can be collected in two modes:

1. Session-based: Open a session, add counters, collect data periodically, then close the session.
2. One-shot: List available counters or instances.

Parameters:

Name	Type	Description	Default
username	str	AXL/CCMAdministrator user name.	required
password	str	Password.	required
server_ip	str	UCM publisher IP address or FQDN.	required
tls_verify	Union[bool, str]	TLS verification setting (default True).	True
timeout	int	Request timeout in seconds (default 30).	30
max_retries	int	Retry count for transient failures (default 3).	3

service property

service

Direct access to the underlying zeep service proxy.

decode_counter_name staticmethod

decode_counter_name(counter_name_string: str) -> Optional[Dict[str, Optional[str]]]

Parse a perfmon counter name string into components.

Converts a string like \\\\host\\ObjectName(Instance)\\CounterName into a structured dict.

Parameters:

Name	Type	Description	Default
counter_name_string	str	The raw counter name from PerfMon.	required

Returns:

Type	Description
Optional[Dict[str, Optional[str]]]	A dict with host, object, instance (may be None
Optional[Dict[str, Optional[str]]]	for single-instance objects), and counter keys.
Optional[Dict[str, Optional[str]]]	Returns None if the string cannot be parsed.

Example::

result = PerfMonClient.decode_counter_name(
    r"\\cm-pub\Cisco CallManager\CallsCompleted"
)
# {'host': 'cm-pub', 'object': 'Cisco CallManager',
#  'instance': None, 'counter': 'CallsCompleted'}

open_session

open_session() -> str

Open a new PerfMon collection session.

Returns:

Type	Description
str	A session handle string to use with :meth:add_counters,
str	meth:collect_session_data, and :meth:close_session.

Raises:

Type	Description
PerfMonError	If the session cannot be opened.

close_session

close_session(session_handle: str) -> None

Close a PerfMon collection session.

Parameters:

Name	Type	Description	Default
session_handle	str	The session handle from :meth:open_session.	required

Raises:

Type	Description
PerfMonError	If the session cannot be closed.

add_counters

add_counters(session_handle: str, counters: Union[str, Sequence[str]]) -> None

Add counters to a PerfMon session.

Parameters:

Name	Type	Description	Default
session_handle	str	The session handle from :meth:open_session.	required
counters	Union[str, Sequence[str]]	A single counter name string or a list of counter name strings. Each must be in the PerfMon format:: \\\\hostname\\ObjectName(Instance)\\CounterName	required

Raises:

Type	Description
PerfMonError	If the counters cannot be added.

Example::

client.add_counters(session, [
    r"\\cm-pub\Cisco CallManager\CallsCompleted",
    r"\\cm-pub\Cisco CallManager\CallsActive",
])

remove_counters

remove_counters(session_handle: str, counters: Union[str, Sequence[str]]) -> None

Remove counters from a PerfMon session.

Parameters:

Name	Type	Description	Default
session_handle	str	The session handle from :meth:open_session.	required
counters	Union[str, Sequence[str]]	A single counter name string or a list of counter name strings to remove.	required

Raises:

Type	Description
PerfMonError	If the counters cannot be removed.

collect_session_data

collect_session_data(session_handle: str) -> Optional[Dict[str, Dict[str, Any]]]

Collect current counter values from a PerfMon session.

Parameters:

Name	Type	Description	Default
session_handle	str	The session handle from :meth:open_session.	required

Returns:

Type	Description
Optional[Dict[str, Dict[str, Any]]]	A nested dict structured as:: { "hostname": { "ObjectName": { "multi_instance": True/False, "counters": {"CounterName": value}, # single-instance "instances": { # multi-instance "InstanceName": {"CounterName": value} } } } }
Optional[Dict[str, Dict[str, Any]]]	Returns None if no data is available.

Raises:

Type	Description
PerfMonError	If data collection fails.

list_counters

list_counters(host: str) -> Optional[Dict[str, Dict[str, Any]]]

List all available PerfMon counters on a host.

Parameters:

Name	Type	Description	Default
host	str	The UCM server hostname or FQDN.	required

Returns:

Type	Description
Optional[Dict[str, Dict[str, Any]]]	A dict keyed by object name. Each value has
Optional[Dict[str, Dict[str, Any]]]	multi_instance (bool) and counters (list of counter
Optional[Dict[str, Dict[str, Any]]]	name strings). Returns None on failure.

Raises:

Type	Description
PerfMonError	If the query fails.

Example::

counters = client.list_counters("cm-pub.example.com")
for obj_name, info in counters.items():
    print(f"{obj_name}: {len(info['counters'])} counters")

list_instances

list_instances(host: str, object_name: str) -> Optional[List[str]]

List instances for a multi-instance PerfMon object.

Parameters:

Name	Type	Description	Default
host	str	The UCM server hostname or FQDN.	required
object_name	str	The PerfMon object name (e.g. "Cisco Lines", "Cisco SIP").	required

Returns:

Type	Description
Optional[List[str]]	A list of instance name strings, or None if no instances.

Raises:

Type	Description
PerfMonError	If the query fails.

Example::

instances = client.list_instances("cm-pub", "Cisco Lines")
for inst in instances:
    print(inst)

collect_counter_data

collect_counter_data(host: str, object_name: str) -> Optional[List[Dict[str, Any]]]

Collect counter values for one PerfMon object without a session.

perfmonCollectCounterData is the session-less alternative to :meth:collect_session_data. It returns the current values of every counter for a single PerfMon object on a single host. Useful for ad-hoc reads when you don't need change tracking or a long-lived collection session.

Parameters:

Name	Type	Description	Default
host	str	The UCM server hostname or FQDN.	required
object_name	str	The PerfMon object name (e.g. "Cisco CallManager", "Cisco Lines").	required

Returns:

Type	Description
Optional[List[Dict[str, Any]]]	A list of dicts, each with name (full counter name string),
Optional[List[Dict[str, Any]]]	value (numeric value), and cstatus (counter status,
Optional[List[Dict[str, Any]]]	0 = ok) keys. Returns None if no data is available.

Raises:

Type	Description
PerfMonError	If the query fails.

Example::

counters = client.collect_counter_data("cm-pub", "Cisco CallManager")
for c in counters:
    print(c["name"], "=", c["value"])