agent_based_api.v1.register

The “register” namespace contains functions to inform Checkmk about plugins.

class RuleSetType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Indicate the type of the rule set

Discovery and host label functions may either use all rules of a rule set matching the current host, or the merged rules.

agent_section(*, name, parse_function=None, parsed_section_name=None, host_label_function=None, host_label_default_parameters=None, host_label_ruleset_name=None, host_label_ruleset_type=RuleSetType.MERGED, supersedes=None)

Register an agent section to checkmk

The section marked by ‘<<<name>>>’ in the raw agent output will be processed according to the functions and options given to this function:

Parameters:

  • name (str) – The unique name of the section to be registered. It must match the section header of the agent output (‘<<<name>>>’).

  • parse_function (Optional[Callable[[List[List[str]]], Any]]) – The function responsible for parsing the raw agent data. It must accept exactly one argument by the name ‘string_table’. It may return an arbitrary object. Note that if the return value is None, no further processing will take place (just as if the agent had not sent any data). This function may raise arbitrary exceptions, which will be dealt with by the checking engine. You should expect well formatted data.

  • parsed_section_name (Optional[str]) – The name under which the parsed section will be available to the plugins. Defaults to the original name.

  • host_label_function (Optional[Callable[..., Generator[HostLabel, None, None]]]) – The function responsible for extracting host labels from the parsed data. It must accept exactly one argument by the name ‘section’. When the function is called, it will be passed the parsed data as returned by the parse function. It is expected to yield objects of type HostLabel.

  • host_label_default_parameters (Optional[Mapping[str, Any]]) – Default parameters for the host label function. Must match the ValueSpec of the corresponding WATO ruleset, if it exists.

  • host_label_ruleset_name (Optional[str]) – The name of the host label ruleset.

  • host_label_ruleset_type (RuleSetType) – The ruleset type is either RuleSetType.ALL or RuleSetType.MERGED. It describes whether this plug-in needs the merged result of the effective rules, or every individual rule matching for the current host.

  • supersedes (Optional[list[str]]) – A list of section names which are superseded by this section. If this section will be parsed to something that is not None (see above) all superseded section will not be considered at all.

Return type:

None

check_plugin(*, name, sections=None, service_name, discovery_function, discovery_default_parameters=None, discovery_ruleset_name=None, discovery_ruleset_type=RuleSetType.MERGED, check_function, check_default_parameters=None, check_ruleset_name=None, cluster_check_function=None)

Register a check plug-in to checkmk.

Parameters:

  • name (str) – The unique name of the check plug-in. It must only contain the characters ‘A-Z’, ‘a-z’, ‘0-9’ and the underscore.

  • sections (Optional[list[str]]) – An optional list of section names that this plug-in subscribes to. They correspond to the ‘parsed_section_name’ specified in agent_section() and snmp_section(). The corresponding sections are passed to the discovery and check function. The functions arguments must be called ‘section_<name1>, section_<name2>’ ect. Defaults to a list containing as only element a name equal to the name of the check plug-in.

  • service_name (str) – The template for the service name. The check function must accept ‘item’ as first argument if and only if “%s” is present in the value of “service_name”.

  • discovery_function (Callable[..., Iterable[Service]]) – The discovery_function. Arguments must be ‘params’ (if discovery parameters are defined) and ‘section’ (if the plug-in subscribes to a single section), or ‘section_<name1>, section_<name2>’ ect. corresponding to the sections. It is expected to be a generator of Service instances.

  • discovery_default_parameters (Optional[Mapping[str, Any]]) – Default parameters for the discovery function. Must match the ValueSpec of the corresponding WATO ruleset, if it exists.

  • discovery_ruleset_name (Optional[str]) – The name of the discovery ruleset.

  • discovery_ruleset_type (RuleSetType) – The ruleset type is either RuleSetType.ALL or RuleSetType.MERGED. It describes whether this plug-in needs the merged result of the effective rules, or every individual rule matching for the current host.

  • check_function (Callable[..., Iterable[IgnoreResults | Metric | Result]]) – The check_function. Arguments must be ‘item’ (if the service has an item), ‘params’ (if check default parameters are defined) and ‘section’ (if the plug-in subscribes to a single section), or ‘section_<name1>, section_<name2>’ ect. corresponding to the sections.

  • check_default_parameters (Optional[Mapping[str, Any]]) – Default parameters for the check function. Must match the ValueSpec of the corresponding WATO ruleset, if it exists.

  • check_ruleset_name (Optional[str]) – The name of the check ruleset.

  • cluster_check_function (Optional[Callable]) – The cluster check function. If this function is not specified, the corresponding services will not be available for clusters. The arguments are the same as the ones for the check function, except that the sections are dicts (node name -> node section).

Return type:

None

inventory_plugin(*, name, sections=None, inventory_function, inventory_default_parameters=None, inventory_ruleset_name=None)

Register an inventory plug-in to checkmk.

Parameters:

  • name (str) – The unique name of the check plug-in. It must only contain the characters ‘A-Z’, ‘a-z’, ‘0-9’ and the underscore.

  • sections (Optional[list[str]]) – An optional list of section names that this plug-in subscribes to. They correspond to the ‘parsed_section_name’ specified in agent_section() and snmp_section(). The corresponding sections are passed to the discovery and check function. The functions arguments must be called ‘section_<name1>, section_<name2>’ ect. Defaults to a list containing as only element a name equal to the name of the inventory plug-in.

  • inventory_function (Callable[..., Iterable[Attributes | TableRow]]) – The inventory_function. Arguments must be ‘params’ (if inventory parameters are defined) and ‘section’ (if the plug-in subscribes to a single section), or ‘section_<name1>, section_<name2>’ ect. corresponding to the sections. It is expected to be a generator of Attributes or TableRow instances.

  • inventory_default_parameters (Optional[Mapping[str, Any]]) – Default parameters for the inventory function. Must match the ValueSpec of the corresponding WATO ruleset, if it exists.

  • inventory_ruleset_name (Optional[str]) – The name of the inventory ruleset.

Return type:

None

snmp_section(*, name, detect, fetch, parse_function=None, parsed_section_name=None, host_label_function=None, host_label_default_parameters=None, host_label_ruleset_name=None, host_label_ruleset_type=RuleSetType.MERGED, supersedes=None)

Register an snmp section to checkmk

The snmp information will be gathered and parsed according to the functions and options given to this function:

Parameters:

  • name (str) – The unique name of the section to be registered.

  • detect (SNMPDetectSpecification) – The conditions on single OIDs that will result in the attempt to fetch snmp data and discover services. This should only match devices to which the section is applicable. It is highly recommended to check the system description OID at the very first, as this will make the discovery much more responsive and consume less resources.

  • fetch (SNMPTree | list[SNMPTree]) – The specification of snmp data that should be fetched from the device. It must be an SNMPTree object, or a non-empty list of them. The parse function will be passed a single StringTable or a list of them accordingly.

  • parse_function (UnionType[Callable[[List[List[str]]], object], Callable[[List[List[Union[str, List[int]]]]], object], Callable[[list[List[List[str]]]], object], Callable[[list[List[List[Union[str, List[int]]]]]], object], None]) – The function responsible for parsing the raw snmp data. It must accept exactly one argument by the name ‘string_table’. It will be passed either a single StringTable, or a list of them, depending on the value type of the fetch argument. It may return an arbitrary object. Note that if the return value is None, no further processing will take place (just as if the agent had not sent any data). This function may raise arbitrary exceptions, which will be dealt with by the checking engine. You should expect well formatted data.

  • parsed_section_name (Optional[str]) – The name under which the parsed section will be available to the plugins. Defaults to the original name.

  • host_label_function (Optional[Callable[..., Generator[HostLabel, None, None]]]) – The function responsible for extracting host labels from the parsed data. It must accept exactly one argument by the name ‘section’. When the function is called, it will be passed the parsed data as returned by the parse function. It is expected to yield objects of type HostLabel.

  • host_label_default_parameters (Optional[Mapping[str, Any]]) – Default parameters for the host label function. Must match the ValueSpec of the corresponding WATO ruleset, if it exists.

  • host_label_ruleset_name (Optional[str]) – The name of the host label ruleset.

  • host_label_ruleset_type (RuleSetType) – The ruleset type is either RuleSetType.ALL or RuleSetType.MERGED. It describes whether this plug-in needs the merged result of the effective rules, or every individual rule matching for the current host.

  • supersedes (Optional[list[str]]) – A list of section names which are superseded by this section. If this section will be parsed to something that is not None (see above) all superseded section will not be considered at all.

Return type:

None