rulesets.v1.form_specs

class FormSpec(*, title=None, help_text=None, migrate=None, custom_validate=None)

Common base class for FormSpecs.

This encapsulates some properties that all form specs have in common. Even if the migrate and custom_validate arguments do not always make sense, all form specs have them for consistency.

Every form spec has a configuration model and a consumer model. The configuration model is the type of the value that is expected to be stored in the configuration. This type is the generic parameter of this class.

The consumer model is the type of the value that is expected to be passed to the consumer of the ruleset. It will be the same as the configuration model in most cases, but there are exceptions.

The consumer model is not part of the form spec, but it is important to keep it in mind when implementing the consumer of the ruleset.

Example:

A form spec that represents a single choice will have a configuration model of str and a consumer model of str. A form spec that represents predictive levels will have a configuration model containing the metric name and information on how to compute the predictive levels and a consumer model containing the metric name and the predictive levels themselves.

Common arguments:

title: Title | None = None: A human readable title.

help_text: Help | None = None: Description to help the user with the configuration.

migrate: Callable[[object], TypeVar(ModelT)] | None = None

A function to change the value every time it is loaded into the form spec.

You can add a migration function to a form spec to update the value from an old version to be compatible with the current definition. This function is executed every time a stored value is loaded into the form spec, so it is important that it is idem potent. In other words: The function should change values only once, and in subsequent calls leave the value alone. Counter example: Simply multiplying a value by 10 will increase it during every (patch) upgrade and also every time the surprised user looks at their configuration. By default the value remains unchanged.

custom_validate: Sequence[Callable[[TypeVar(ModelT)], object]] | None = None

Optional additional validators.

After the validation of the specific form spec is successful, these function are executed. They must raise a ValidationError in case validation fails. The return value of the functions will not be used.

class DefaultValue(value)

Defines a default value for the form spec.

Note that the default value will be part of the created configuration, unless the user changes it before hitting the save button. See also InputHint.

class InputHint(value)

Defines an input hint for the form spec.

Note that an input hint will not be part of the created configuration, unless the user enters a value before hitting the save button. See also DefaultValue.

Atomic Form Specifications

Here is a list of all atomic form specifications that are available in Checkmk. These are the basic building blocks for creating forms.

iskeyword(): x.__contains__(y) <==> y in x.

class BooleanChoice(*, title=None, help_text=None, migrate=None, custom_validate=None, label=None, prefill=DefaultValue(value=False))

Specifies a form for configuring a choice between boolean values.

Consumer model:

Type: bool

Arguments:

label: Label | None = None: Text displayed as an extension to the input field.

prefill: DefaultValue[bool] = DefaultValue(value=False): Value to pre-populate the form field with.

custom_validate: Sequence[Callable[[ModelT], object]] | None = None

Optional additional validators.

After the validation of the specific form spec is successful, these function are executed. They must raise a ValidationError in case validation fails. The return value of the functions will not be used.

help_text: Help | None = None: Description to help the user with the configuration.

migrate: Callable[[object], ModelT] | None = None

A function to change the value every time it is loaded into the form spec.

You can add a migration function to a form spec to update the value from an old version to be compatible with the current definition. This function is executed every time a stored value is loaded into the form spec, so it is important that it is idem potent. In other words: The function should change values only once, and in subsequent calls leave the value alone. Counter example: Simply multiplying a value by 10 will increase it during every (patch) upgrade and also every time the surprised user looks at their configuration. By default the value remains unchanged.

title: Title | None = None: A human readable title.

class SIMagnitude(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None): SI magnitudes for data storage capacity. These scale the value using powers of 1000.

class IECMagnitude(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None): IEC magnitudes for memory capacity. These scale the value using powers of 1024.

class DataSize(*, title=None, help_text=None, migrate=None, custom_validate=None, label=None, displayed_magnitudes, prefill=InputHint(value=0))

Specifies an input field for data storage capacity

Consumer model:

Type: int

Arguments:

label: Label | None = None: Text displayed as an extension to the input field

displayed_magnitudes: Sequence[SIMagnitude] | Sequence[IECMagnitude]: Magnitudes of data that can be entered in the UI

prefill: Union[DefaultValue[int], InputHint[int]] = InputHint(value=0): Value in bytes to pre-populate the form field with.

custom_validate: Sequence[Callable[[ModelT], object]] | None = None

Optional additional validators.

After the validation of the specific form spec is successful, these function are executed. They must raise a ValidationError in case validation fails. The return value of the functions will not be used.

help_text: Help | None = None: Description to help the user with the configuration.

migrate: Callable[[object], ModelT] | None = None

A function to change the value every time it is loaded into the form spec.

You can add a migration function to a form spec to update the value from an old version to be compatible with the current definition. This function is executed every time a stored value is loaded into the form spec, so it is important that it is idem potent. In other words: The function should change values only once, and in subsequent calls leave the value alone. Counter example: Simply multiplying a value by 10 will increase it during every (patch) upgrade and also every time the surprised user looks at their configuration. By default the value remains unchanged.

title: Title | None = None: A human readable title.

class FileUpload(*, title=None, help_text=None, migrate=None, custom_validate=None, extensions=None, mime_types=None)

Specifies a file upload form.

Consumer model:

The configured value will be presented as a 3-tuple consisting of the name of the uploaded file, its mime type, and the files content as bytes.

Type: tuple[str, str, bytes]

Example: Choosing a pem file to upload would result in:

(
     "my_cert.pem",
     "application/octet-stream",
     b"-----BEGIN CERTIFICATE-----\n....",
 )

Arguments:

extensions: tuple[str, ...] | None = None: The extensions of the files to choose from. If set to None, all extensions are selectable.

mime_types: tuple[str, ...] | None = None: The allowed mime types of uploaded files. If set to None, all mime types will be uploadable.

custom_validate: Sequence[Callable[[ModelT], object]] | None = None

Optional additional validators.

After the validation of the specific form spec is successful, these function are executed. They must raise a ValidationError in case validation fails. The return value of the functions will not be used.

help_text: Help | None = None: Description to help the user with the configuration.

migrate: Callable[[object], ModelT] | None = None

A function to change the value every time it is loaded into the form spec.

You can add a migration function to a form spec to update the value from an old version to be compatible with the current definition. This function is executed every time a stored value is loaded into the form spec, so it is important that it is idem potent. In other words: The function should change values only once, and in subsequent calls leave the value alone. Counter example: Simply multiplying a value by 10 will increase it during every (patch) upgrade and also every time the surprised user looks at their configuration. By default the value remains unchanged.

title: Title | None = None: A human readable title.

class FixedValue(*, title=None, help_text=None, migrate=None, custom_validate=None, value, label=None)

Specifies a fixed non-editable value.

Can be used in a CascadingSingleChoice and Dictionary to represent a fixed value option.

Consumer model:

The consumer model is equal to the configuration model, i.e. the value that it contains.

Arguments:

value: TypeVar(_FixedValueT, int, float, str, bool, None): Atomic value produced by the form spec

label: Label | None = None: Text displayed underneath the title.

custom_validate: Sequence[Callable[[ModelT], object]] | None = None

Optional additional validators.

After the validation of the specific form spec is successful, these function are executed. They must raise a ValidationError in case validation fails. The return value of the functions will not be used.

help_text: Help | None = None: Description to help the user with the configuration.

migrate: Callable[[object], ModelT] | None = None

A function to change the value every time it is loaded into the form spec.

You can add a migration function to a form spec to update the value from an old version to be compatible with the current definition. This function is executed every time a stored value is loaded into the form spec, so it is important that it is idem potent. In other words: The function should change values only once, and in subsequent calls leave the value alone. Counter example: Simply multiplying a value by 10 will increase it during every (patch) upgrade and also every time the surprised user looks at their configuration. By default the value remains unchanged.

title: Title | None = None: A human readable title.

class Float(*, title=None, help_text=None, migrate=None, custom_validate=None, label=None, unit_symbol='', prefill=InputHint(value=0.0))

Specifies an input field for floating point numbers.

Consumer model:

Type: float

Arguments:

label: Label | None = None: Text displayed as an extension to the input field.

unit_symbol: str = '': Unit symbol to add to the input field.

prefill: Union[DefaultValue[float], InputHint[float]] = InputHint(value=0.0): Value to pre-populate the form field with.

custom_validate: Sequence[Callable[[ModelT], object]] | None = None

Optional additional validators.

After the validation of the specific form spec is successful, these function are executed. They must raise a ValidationError in case validation fails. The return value of the functions will not be used.

help_text: Help | None = None: Description to help the user with the configuration.

migrate: Callable[[object], ModelT] | None = None

A function to change the value every time it is loaded into the form spec.

You can add a migration function to a form spec to update the value from an old version to be compatible with the current definition. This function is executed every time a stored value is loaded into the form spec, so it is important that it is idem potent. In other words: The function should change values only once, and in subsequent calls leave the value alone. Counter example: Simply multiplying a value by 10 will increase it during every (patch) upgrade and also every time the surprised user looks at their configuration. By default the value remains unchanged.

title: Title | None = None: A human readable title.

class HostState(*, title=None, help_text=None, migrate=None, custom_validate=None, prefill=DefaultValue(value=0))

Specifies the configuration of a host state.

Consumer model:

Type: Literal[0, 1, 2]

Example:

>>> state_form_spec = HostState(
...     title=Title("Host state"),
...     prefill=DefaultValue(HostState.UP),
... )

Arguments:

prefill: DefaultValue[Literal[0, 1, 2]] = DefaultValue(value=0): Value to pre-populate the form field with.

custom_validate: Sequence[Callable[[ModelT], object]] | None = None

Optional additional validators.

After the validation of the specific form spec is successful, these function are executed. They must raise a ValidationError in case validation fails. The return value of the functions will not be used.

help_text: Help | None = None: Description to help the user with the configuration.

migrate: Callable[[object], ModelT] | None = None

A function to change the value every time it is loaded into the form spec.

You can add a migration function to a form spec to update the value from an old version to be compatible with the current definition. This function is executed every time a stored value is loaded into the form spec, so it is important that it is idem potent. In other words: The function should change values only once, and in subsequent calls leave the value alone. Counter example: Simply multiplying a value by 10 will increase it during every (patch) upgrade and also every time the surprised user looks at their configuration. By default the value remains unchanged.

title: Title | None = None: A human readable title.

class Integer(*, title=None, help_text=None, migrate=None, custom_validate=None, label=None, unit_symbol='', prefill=InputHint(value=0))

Specifies an input field for whole numbers.

Consumer model:

Type: int

Arguments:

label: Label | None = None: Text displayed as an extension to the input field.

unit_symbol: str = '': Unit symbol to add to the input field.

prefill: Union[DefaultValue[int], InputHint[int]] = InputHint(value=0): Value to pre-populate the form field with.

custom_validate: Sequence[Callable[[ModelT], object]] | None = None

Optional additional validators.

After the validation of the specific form spec is successful, these function are executed. They must raise a ValidationError in case validation fails. The return value of the functions will not be used.

help_text: Help | None = None: Description to help the user with the configuration.

migrate: Callable[[object], ModelT] | None = None

A function to change the value every time it is loaded into the form spec.

You can add a migration function to a form spec to update the value from an old version to be compatible with the current definition. This function is executed every time a stored value is loaded into the form spec, so it is important that it is idem potent. In other words: The function should change values only once, and in subsequent calls leave the value alone. Counter example: Simply multiplying a value by 10 will increase it during every (patch) upgrade and also every time the surprised user looks at their configuration. By default the value remains unchanged.

title: Title | None = None: A human readable title.

class MultilineText(*, title=None, help_text=None, migrate=None, custom_validate=None, monospaced=False, macro_support=False, label=None, prefill=InputHint(value=''))

Specifies a multiline text form.

Consumer model:

Type: str

Example: Inputting “some text” in a MultilineText form would result in:

"some text\n"

Arguments:

monospaced: bool = False: Display text in the form as monospaced.

macro_support: bool = False: Hint in the UI that macros can be used in the field. Replacing the macros in the plug-in is a responsibility of the plug-in developer.

label: Label | None = None: Text displayed in front of the input field.

prefill: Union[DefaultValue[str], InputHint[str]] = InputHint(value=''): Value to pre-populate the form field with.

custom_validate: Sequence[Callable[[ModelT], object]] | None = None

Optional additional validators.

After the validation of the specific form spec is successful, these function are executed. They must raise a ValidationError in case validation fails. The return value of the functions will not be used.

help_text: Help | None = None: Description to help the user with the configuration.

migrate: Callable[[object], ModelT] | None = None

A function to change the value every time it is loaded into the form spec.

You can add a migration function to a form spec to update the value from an old version to be compatible with the current definition. This function is executed every time a stored value is loaded into the form spec, so it is important that it is idem potent. In other words: The function should change values only once, and in subsequent calls leave the value alone. Counter example: Simply multiplying a value by 10 will increase it during every (patch) upgrade and also every time the surprised user looks at their configuration. By default the value remains unchanged.

title: Title | None = None: A human readable title.

class Percentage(*, title=None, help_text=None, migrate=None, custom_validate=None, label=None, prefill=InputHint(value=0.0))

Specifies an input field for percentages.

Consumer model:

Type: float

Arguments:

label: Label | None = None: Text displayed in front of the input field.

prefill: Union[DefaultValue[float], InputHint[float]] = InputHint(value=0.0): Value to pre-populate the form field with.

custom_validate: Sequence[Callable[[ModelT], object]] | None = None

Optional additional validators.

After the validation of the specific form spec is successful, these function are executed. They must raise a ValidationError in case validation fails. The return value of the functions will not be used.

help_text: Help | None = None: Description to help the user with the configuration.

migrate: Callable[[object], ModelT] | None = None

A function to change the value every time it is loaded into the form spec.

You can add a migration function to a form spec to update the value from an old version to be compatible with the current definition. This function is executed every time a stored value is loaded into the form spec, so it is important that it is idem potent. In other words: The function should change values only once, and in subsequent calls leave the value alone. Counter example: Simply multiplying a value by 10 will increase it during every (patch) upgrade and also every time the surprised user looks at their configuration. By default the value remains unchanged.

title: Title | None = None: A human readable title.

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

class RegularExpression(*, title=None, help_text=None, migrate=None, custom_validate=None, predefined_help_text, label=None, prefill=InputHint(value=''))

Specifies an input field for regular expressions.

Consumer model:

Type: str

Arguments:

predefined_help_text: MatchingScope: Adds pre-formulated help text. For commonly used matching behavior you can choose from predefined help texts to describe how the pattern will be used to match. Implementing it in a way that fulfills this promise is a responsibility of the plug-in developer.

label: Label | None = None: Text displayed in front of the input field.

prefill: Union[DefaultValue[str], InputHint[str]] = InputHint(value=''): Value to pre-populate the form field with.

custom_validate: Sequence[Callable[[ModelT], object]] | None = None

Optional additional validators.

After the validation of the specific form spec is successful, these function are executed. They must raise a ValidationError in case validation fails. The return value of the functions will not be used.

help_text: Help | None = None: Description to help the user with the configuration.

migrate: Callable[[object], ModelT] | None = None

A function to change the value every time it is loaded into the form spec.

You can add a migration function to a form spec to update the value from an old version to be compatible with the current definition. This function is executed every time a stored value is loaded into the form spec, so it is important that it is idem potent. In other words: The function should change values only once, and in subsequent calls leave the value alone. Counter example: Simply multiplying a value by 10 will increase it during every (patch) upgrade and also every time the surprised user looks at their configuration. By default the value remains unchanged.

title: Title | None = None: A human readable title.

class ServiceState(*, title=None, help_text=None, migrate=None, custom_validate=None, prefill=DefaultValue(value=0))

Specifies the configuration of a service state.

Consumer model:

Type: Literal[0, 1, 2, 3]

Example:

>>> state_form_spec = ServiceState(
...     title=Title("State if something happens"),
...     prefill=DefaultValue(ServiceState.WARN),
... )

Arguments:

prefill: DefaultValue[Literal[0, 1, 2, 3]] = DefaultValue(value=0): Value to pre-populate the form field with.

custom_validate: Sequence[Callable[[ModelT], object]] | None = None

Optional additional validators.

After the validation of the specific form spec is successful, these function are executed. They must raise a ValidationError in case validation fails. The return value of the functions will not be used.

help_text: Help | None = None: Description to help the user with the configuration.

migrate: Callable[[object], ModelT] | None = None

A function to change the value every time it is loaded into the form spec.

You can add a migration function to a form spec to update the value from an old version to be compatible with the current definition. This function is executed every time a stored value is loaded into the form spec, so it is important that it is idem potent. In other words: The function should change values only once, and in subsequent calls leave the value alone. Counter example: Simply multiplying a value by 10 will increase it during every (patch) upgrade and also every time the surprised user looks at their configuration. By default the value remains unchanged.

title: Title | None = None: A human readable title.

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

class String(*, title=None, help_text=None, migrate=None, custom_validate=None, label=None, macro_support=False, prefill=InputHint(value=''), field_size=FieldSize.MEDIUM)

Specifies an input field for single line text.

Consumer model:

Type: str

Arguments:

label: Label | None = None: Text displayed in front of the input field.

macro_support: bool = False: Hint in the UI that macros can be used in the field. Replacing the macros in the plug-in is a responsibility of the plug-in developer.

prefill: Union[DefaultValue[str], InputHint[str]] = InputHint(value=''): Value to pre-populate the form field with.

field_size: FieldSize = 2: Size setting of the input field.

custom_validate: Sequence[Callable[[ModelT], object]] | None = None

Optional additional validators.

After the validation of the specific form spec is successful, these function are executed. They must raise a ValidationError in case validation fails. The return value of the functions will not be used.

help_text: Help | None = None: Description to help the user with the configuration.

migrate: Callable[[object], ModelT] | None = None

A function to change the value every time it is loaded into the form spec.

You can add a migration function to a form spec to update the value from an old version to be compatible with the current definition. This function is executed every time a stored value is loaded into the form spec, so it is important that it is idem potent. In other words: The function should change values only once, and in subsequent calls leave the value alone. Counter example: Simply multiplying a value by 10 will increase it during every (patch) upgrade and also every time the surprised user looks at their configuration. By default the value remains unchanged.

title: Title | None = None: A human readable title.

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

class TimeSpan(*, title=None, help_text=None, migrate=None, custom_validate=None, label=None, displayed_magnitudes, prefill=InputHint(value=0.0))

Specifies an input field for time span.

Consumer model:

Type: float

Example:

>>> time_span_form_spec = TimeSpan(
...     title=Title("Time span"),
...     displayed_magnitudes=[TimeMagnitude.SECOND, TimeMagnitude.MINUTE],
...     prefill=DefaultValue(60.0),
... )

The above example would allow the user to configure a time span by entering “3 minutes 20 seconds”, resulting in a value of 200.0.

Arguments:

custom_validate: Sequence[Callable[[ModelT], object]] | None = None

Optional additional validators.

After the validation of the specific form spec is successful, these function are executed. They must raise a ValidationError in case validation fails. The return value of the functions will not be used.

help_text: Help | None = None: Description to help the user with the configuration.

migrate: Callable[[object], ModelT] | None = None

A function to change the value every time it is loaded into the form spec.

You can add a migration function to a form spec to update the value from an old version to be compatible with the current definition. This function is executed every time a stored value is loaded into the form spec, so it is important that it is idem potent. In other words: The function should change values only once, and in subsequent calls leave the value alone. Counter example: Simply multiplying a value by 10 will increase it during every (patch) upgrade and also every time the surprised user looks at their configuration. By default the value remains unchanged.

title: Title | None = None: A human readable title.

label: Label | None = None: Text displayed as an extension to the input field.

displayed_magnitudes: Sequence[TimeMagnitude]

Magnitudes that can be entered in the UI.

All of the listed magnitudes can be used to configure the desired time span, which will be the sum of the configured fields in seconds.

prefill: Union[DefaultValue[float], InputHint[float]] = InputHint(value=0.0): Value to pre-populate the form field with.

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

class InvalidElementValidator(mode=InvalidElementMode.COMPLAIN, display=None, error_msg=None)

class SingleChoiceElement(name, title)

Specifies an element of a single choice form.

Arguments:

name: str: Identifier of the SingleChoiceElement. Must be a valid Python identifier.

title: Title: Human readable title that will be shown in the UI.

class SingleChoice(*, title=None, help_text=None, migrate=None, custom_validate=None, elements, no_elements_text=None, frozen=False, label=None, prefill=InputHint(value=Title('Please choose')), ignored_elements=(), invalid_element_validation=None)

Specification for a (single-)selection from multiple options.

Consumer model:

Type: str

Arguments:

custom_validate: Sequence[Callable[[ModelT], object]] | None = None

Optional additional validators.

After the validation of the specific form spec is successful, these function are executed. They must raise a ValidationError in case validation fails. The return value of the functions will not be used.

help_text: Help | None = None: Description to help the user with the configuration.

migrate: Callable[[object], ModelT] | None = None

A function to change the value every time it is loaded into the form spec.

You can add a migration function to a form spec to update the value from an old version to be compatible with the current definition. This function is executed every time a stored value is loaded into the form spec, so it is important that it is idem potent. In other words: The function should change values only once, and in subsequent calls leave the value alone. Counter example: Simply multiplying a value by 10 will increase it during every (patch) upgrade and also every time the surprised user looks at their configuration. By default the value remains unchanged.

title: Title | None = None: A human readable title.

elements: Sequence[SingleChoiceElement]: Elements to choose from.

no_elements_text: Message | None = None: Text to show if no elements are given.

frozen: bool = False: Set to True to prevent the value from being changed after initial configuration, e.g. for identifiers.

label: Label | None = None: Text displayed in front of the input field.

prefill: Union[DefaultValue[str], InputHint[Title]] = InputHint(value=Title('Please choose'))

Pre-selected choice.

If a DefaultValue is used, it must be one of the elements names. If an InputHint is used, its title will be shown as a placeholder in the input field, requiring the user to make a choice.

ignored_elements: tuple[str, ...] = (): Elements that can not be configured, but aren’t removed from rules if they are present. They might be ignored when rendering the ruleset. You can use these to deprecate elements, to avoid breaking the old configurations.

invalid_element_validation: InvalidElementValidator | None = None: Validate if the selected value is still offered as a choice.

Levels Form Specifications

Here is a list of all levels form specifications that are available in Checkmk. These should be used whenever you want to create a form that is used to configure levels for a metric that will result in a warning or critical state of a service.

class PredictiveLevels(*, reference_metric, prefill_abs_diff, prefill_rel_diff=DefaultValue(value=(10.0, 20.0)), prefill_stdev_diff=DefaultValue(value=(2.0, 4.0)))

Definition for levels based on a prediction of the monitored value.

Usable only in conjunction with Levels.

Example:

>>> predictive = PredictiveLevels(
...     reference_metric="mem_used_percent",
...     prefill_abs_diff=DefaultValue((5.0, 10.0)),
...     prefill_rel_diff=DefaultValue((10.0, 20.0)),
...     prefill_stdev_diff=DefaultValue((2.0, 4.0)),
... )

Arguments:

reference_metric: str

The name of the metric that should be used to compute the prediction.

This value is hardcoded by you, the developer. It is your responsibility to make sure that all plug-ins subscribing to the ruleset actually create this metric. Failing to do so will prevent the backend from providing a prediction, currently leading to an always OK service.

prefill_abs_diff: Union[DefaultValue[tuple[TypeVar(_NumberT, int, float), TypeVar(_NumberT, int, float)]], InputHint[tuple[TypeVar(_NumberT, int, float), TypeVar(_NumberT, int, float)]]]: Value to pre-populate the form fields with when the levels depend on the absolute difference to the predicted value. If None, the backend will decide whether to leave the field empty or to prefill it with a canonical value.

prefill_rel_diff: Union[DefaultValue[tuple[float, float]], InputHint[tuple[float, float]]] = DefaultValue(value=(10.0, 20.0)): Value to pre-populate the form fields with when the levels depend on the relative difference to the predicted value. If None, the backend will decide whether to leave the field empty or to prefill it with a canonical value.

prefill_stdev_diff: Union[DefaultValue[tuple[float, float]], InputHint[tuple[float, float]]] = DefaultValue(value=(2.0, 4.0)): Value to pre-populate the form fields with when the levels depend on the relation of the predicted value to the standard deviation. If None, the backend will decide whether to leave the field empty or to prefill it with a canonical value.

class LevelDirection(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None): Specifies a type of bound the levels represents

class LevelsType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None): Type of levels configuration

class SimpleLevels(*, title=None, help_text=None, migrate=None, custom_validate=None, form_spec_template, level_direction, prefill_levels_type=DefaultValue(value=<LevelsType.FIXED: 2>), prefill_fixed_levels)

Specifies a form for configuring levels without predictive levels.

This creates a FormSpec that allows to configure simple levels, i.e. either configure to not use levels at all, or to configure fixed levels.

Consumer model:

Type: _NoLevels | _FixedLevels.

The value presented to consumers will be crafted in a way that makes it a suitable argument for the check_levels function of the agent based API v2. They either represent that no levels should be applied, or they contain a 2-tuple of numbers representing the warning and critical levels. Here Number can be either float or int, depending on the consumer model of the used form spec:

_NoLevels = tuple[
    Literal["no_levels"],
    None,
]

_FixedLevels = tuple[
    Literal["fixed"],
    tuple[Number, Number],
]

Example: SimpleLevels used to configure no levels will look like ("no_levels", None), levels used to configure fixed upper levels might be ("fixed", (5.0, 10.0)).

Arguments:

title: Title | None = None: A human readable title.

help_text: Help | None = None: Description to help the user with the configuration.

migrate: Callable[[object], Union[tuple[Literal['no_levels'], None], tuple[Literal['fixed'], tuple[TypeVar(_NumberT, int, float), TypeVar(_NumberT, int, float)]]]] | None = None

A function to change the value every time it is loaded into the form spec.

You can add a migration function to a form spec to update the value from an old version to be compatible with the current definition. This function is executed every time a stored value is loaded into the form spec, so it is important that it is idem potent. In other words: The function should change values only once, and in subsequent calls leave the value alone. Counter example: Simply multiplying a value by 10 will increase it during every (patch) upgrade and also every time the surprised user looks at their configuration. By default the value remains unchanged.

custom_validate: tuple[Callable[[Union[tuple[Literal['no_levels'], None], tuple[Literal['fixed'], tuple[TypeVar(_NumberT, int, float), TypeVar(_NumberT, int, float)]]]], object], ...] | None = None

Optional additional validators.

After the validation of the specific form spec is successful, these function are executed. They must raise a ValidationError in case validation fails. The return value of the functions will not be used.

form_spec_template: FormSpec[TypeVar(_NumberT, int, float)]: Template for the specification of the form fields of the warning and critical levels. If title or prefill_value are provided here, they will be ignored.

level_direction: LevelDirection: Specifies the type of bound the levels represents. This is used only to adjust the labels and error messages in the UI.

prefill_levels_type: DefaultValue[Literal[<LevelsType.NONE: 1>, <LevelsType.FIXED: 2>]] = DefaultValue(value=<LevelsType.FIXED: 2>): Pre-selected type of the levels (no levels or fixed levels).

prefill_fixed_levels: Union[DefaultValue[tuple[TypeVar(_NumberT, int, float), TypeVar(_NumberT, int, float)]], InputHint[tuple[TypeVar(_NumberT, int, float), TypeVar(_NumberT, int, float)]]]: Value to pre-populate the form field for fixed levels with.

class Levels(*, title=None, help_text=None, migrate=None, custom_validate=None, form_spec_template, level_direction, prefill_levels_type=DefaultValue(value=<LevelsType.FIXED: 2>), prefill_fixed_levels, predictive)

Specifies a form for configuring levels including predictive levels

This creates a FormSpec that extends the SimpleLevels with the possibility to configure predictive levels, i.e. levels that are based on a prediction of the monitored value.

Consumer model:

Type: _NoLevels | _FixedLevels | _PredictiveLevels.

The value presented to consumers will be crafted in a way that makes it a suitable argument for the check_levels function of the agent based API. In addition to the two types defined in SimpleLevels, this class also allows for predictive levels. The model of the predictive levels is:

_PredictiveLevels = tuple[
    Literal["predictive"],
    # (reference_metric, predicted_value, levels_tuple)
    tuple[str, float | None, tuple[float, float] | None],
]

The configured value will be presented to consumers as a 2-tuple consisting of the level type identifier "predictive" and a 3-tuple containing the name of the reference metric used for prediction, the predicted value and the resulting levels tuple.

Example: Levels resulting from configured upper predictive levels might look like this:

("predictive", ("mem_used_percent", 42.1, (50.3, 60.7)))

title: Title | None = None: A human readable title.

help_text: Help | None = None: Description to help the user with the configuration.

migrate: Callable[[object], Union[tuple[Literal['no_levels'], None], tuple[Literal['fixed'], tuple[TypeVar(_NumberT, int, float), TypeVar(_NumberT, int, float)]], tuple[Literal['cmk_postprocessed'], Literal['predictive_levels'], _PredictiveLevelsT[TypeVar(_NumberT, int, float)]]]] | None = None

A function to change the value every time it is loaded into the form spec.

You can add a migration function to a form spec to update the value from an old version to be compatible with the current definition. This function is executed every time a stored value is loaded into the form spec, so it is important that it is idem potent. In other words: The function should change values only once, and in subsequent calls leave the value alone. Counter example: Simply multiplying a value by 10 will increase it during every (patch) upgrade and also every time the surprised user looks at their configuration. By default the value remains unchanged.

custom_validate: tuple[Callable[[Union[tuple[Literal['no_levels'], None], tuple[Literal['fixed'], tuple[TypeVar(_NumberT, int, float), TypeVar(_NumberT, int, float)]], tuple[Literal['cmk_postprocessed'], Literal['predictive_levels'], _PredictiveLevelsT[TypeVar(_NumberT, int, float)]]]], object], ...] | None = None

Optional additional validators.

After the validation of the specific form spec is successful, these function are executed. They must raise a ValidationError in case validation fails. The return value of the functions will not be used.

form_spec_template: FormSpec[TypeVar(_NumberT, int, float)]: Template for the specification of the form fields of the warning and critical levels. If title or prefill_value are provided here, they will be ignored.

level_direction: LevelDirection: Specifies the type of bound the levels represents. This is used only to adjust the labels and error messages in the UI.

prefill_levels_type: DefaultValue[LevelsType] = DefaultValue(value=<LevelsType.FIXED: 2>): Pre-selected type of the levels (no levels, fixed levels or predictive levels).

prefill_fixed_levels: Union[DefaultValue[tuple[TypeVar(_NumberT, int, float), TypeVar(_NumberT, int, float)]], InputHint[tuple[TypeVar(_NumberT, int, float), TypeVar(_NumberT, int, float)]]]: Value to pre-populate the form fields with.

predictive: PredictiveLevels[TypeVar(_NumberT, int, float)]: Specification for the predictive levels.

Composite Form Specifications

Here is a list of all composite form specifications that are available in Checkmk. These are composed of other form specifications and can be used to create more complex forms. You can nest them as deep as you want.

FormSpecs that can be composed of other FormSpecs

iskeyword(): x.__contains__(y) <==> y in x.

class CascadingSingleChoiceElement(*, name, title, parameter_form)

Specifies an element of a single choice cascading form.

Arguments:

name: str: Identifier of the CascadingSingleChoiceElement. Must be a valid Python identifier.

title: Title: Human readable title that will be shown in the UI.

parameter_form: FormSpec[TypeVar(ModelT)]: Configuration specification of this entry.

class CascadingSingleChoice(*, title=None, help_text=None, migrate=None, custom_validate=None, elements, label=None, prefill=InputHint(value=Title('Please choose')))

Specification for a single-selection from multiple options.

Every option can have its own configuration form.

Consumer model:

Type: tuple[str, object]

The configured value will be presented as a 2-tuple consisting of the name of the choice and the consumer model of the selected form specification.

Example: A CascadingSingleChoice with a selected Dictionary form specification would result in ("my_value", {...})

Arguments:

elements: Sequence[CascadingSingleChoiceElement[Any]]: Elements to choose from.

label: Label | None = None: Text displayed in front of the input field.

prefill: Union[DefaultValue[str], InputHint[Title]] = InputHint(value=Title('Please choose')): Name of pre-selected choice. If DefaultValue is used, it must be one of the elements names. If InputHint is used, its title will be shown as a placeholder in the UI, requiring the user to select a value.

class DictGroup(*, title=None, help_text=None): Specification for a group of dictionary elements that are more closely related thematically than the other elements. A group is identified by its title and help text.

class NoGroup: Default group for dictionary elements that don’t belong to any group

class DictElement(*, parameter_form, required=False, render_only=False, group=NoGroup())

Specifies an element of a dictionary form.

Arguments:

parameter_form: FormSpec[TypeVar(ModelT)]: Configuration specification of this entry.

required: bool = False

Whether the user has to configure the value in question.

If set to False, it may be omitted and values will be inherited from more general rules or the default configuration.

render_only: bool = False: Element that can’t be edited. Can be used to store the discovered parameters.

group: DictGroup | NoGroup = NoGroup(): Group this element belongs to. Elements of the same group are displayed together without affecting the data model.

class Dictionary(*, title=None, help_text=None, migrate=None, custom_validate=None, elements, no_elements_text=Message('(no parameters)'), ignored_elements=())

Specifies a (multi-)selection of configuration options.

Consumer model:

Type: dict[str, object] The configured value will be presented as a dictionary consisting of the names of provided configuration options and their respective consumer models.

Arguments:

elements: Mapping[str, DictElement[Any]]: key-value mapping where the key identifies the option and the value specifies how the nested form can be configured. The key has to be a valid Python identifier.

no_elements_text: Message = Message('(no parameters)'): Text to show if no elements are specified

ignored_elements: tuple[str, ...] = (): Elements that can no longer be configured, but aren’t removed from rules if they are present. They might be ignored when rendering the ruleset. You can use these to deprecate elements, to avoid breaking the old configurations.

class List(*, title=None, help_text=None, migrate=None, custom_validate=None, element_template, add_element_label=Label('Add new entry'), remove_element_label=Label('Remove this entry'), no_element_label=Label('No entries'), editable_order=True)

Specifies a list of configuration elements of the same type.

Consumer model:

Type: list[object] The configured value will be presented as a list consisting of the consumer models of the configured elements.

Arguments:

element_template: FormSpec[TypeVar(ModelT)]: Configuration specification of the list elements.

add_element_label: Label = Label('Add new entry'): Label used to customize the add element button.

remove_element_label: Label = Label('Remove this entry'): Label used to customize the remove element button.

no_element_label: Label = Label('No entries'): Label used in the rule summary if the list is empty.

editable_order: bool = True: Indicate if the users should be able to reorder the elements in the UI.

class MultipleChoiceElement(*, name, title)

Specifies an element of a multiple choice form.

Arguments:

name: str: Identifier of the MultipleChoiceElement. Must be a valid Python identifier.

title: Title: Human readable title that will be shown in the UI.

class MultipleChoice(*, title=None, help_text=None, migrate=None, custom_validate=None, elements, show_toggle_all=False, prefill=DefaultValue(value=()))

Specifies a multiple choice form.

Consumer model:

Type: list[str] The configured value will be presented as a list consisting of the names of the selected elements.

Arguments:

elements: Sequence[MultipleChoiceElement]: Elements to choose from.

show_toggle_all: bool = False: Show toggle all elements option in the UI.

prefill: DefaultValue[Sequence[str]] = DefaultValue(value=()): Element names to select by default.

Form Specifications for preconfigured entities

Here is a list of all form specifications for preconfigured entities that are available in Checkmk. You can use them to let the user configure a preconfigured entity, depending on what entities are available in the site.

FormSpecs that allow a selection form preconfigured resources in a setup

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

class Proxy(*, title=None, help_text=None, migrate=None, custom_validate=None, allowed_schemas=frozenset({ProxySchema.HTTP, ProxySchema.HTTPS, ProxySchema.SOCKS4, ProxySchema.SOCKS4A, ProxySchema.SOCKS5, ProxySchema.SOCKS5H}))

Specifies a form for configuring a proxy

Parameters:: allowed_schemas (frozenset[ProxySchema]) – Set of available proxy schemas that can be used in a proxy url

class Metric(*, title=None, help_text=None, migrate=None, custom_validate=None): Specifies a form selecting from a list of metrics registered in Checkmk

class MonitoredHost(*, title=None, help_text=None, migrate=None, custom_validate=None): Specifies a form selecting from a list of hosts configured in Checkmk

class MonitoredService(*, title=None, help_text=None, migrate=None, custom_validate=None): Specifies a form selecting from a list of currently monitored services in Checkmk

class Password(*, title=None, help_text=None, migrate=None, custom_validate=None): Specifies a form for configuring passwords (explicit or from password store)

class TimePeriod(*, title=None, help_text=None, migrate=None, custom_validate=None): Specifies a form selecting from a list of time periods configured in Checkmk

Validators for Form Specifications

This API provides a set of validators that can be used to validate the input of a form specification. Instances of these validators can be used as arguments to as “custom_validator” argument of a form specification.

You can implement your own custom validator, these are just some commonly used ones at your disposal.

exception ValidationError(message)

Raise when custom validation found invalid values

Parameters:: message (Message) – Description of why the value is invalid

class LengthInRange(min_value=None, max_value=None, error_msg=None): Custom validator that ensures the validated size is in a given interval.

class NumberInRange(min_value=None, max_value=None, error_msg=None): Custom validator that ensures the validated number is in a given interval.

class RegexGroupsInRange(min_groups=None, max_groups=None, error_msg=None): Custom validator that ensures the validated value is in a given interval.

class MatchRegex(regex, error_msg=None): Custom validator that ensures the validated value matches the given regular expression.

class NetworkPort(error_msg=None): Validator that ensures that an integer is in the network port range

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

class Url(protocols, error_msg=None): Custom validator that ensures the validated value is a URL with the specified scheme.

class EmailAddress(error_msg=None): Validator that ensures the validated value is an email address

class HostAddress(error_msg=None)

Validator that ensures the validated value is a hostname or IP address.

It does not resolve the hostname or check if the IP address is reachable.

Migrations for Form Specifications

Since the data model of form specifications can change over time, we need to provide a way to migrate old data to the new data model. This is done by providing migration functions that can be used to migrate old data to the new data model.

Here we offer a set of migration functions that can be used to migrate old configurations to the new Levels and SimpleLevels forms.

migrate_to_upper_integer_levels(model, scale=1.0)

Transform a previous levels configuration (Tuple, SimpleLevels, Levels or PredictiveLevels) representing upper (warn, crit) levels to an integer-based model of the Levels FormSpec. The decimal part of floating point values will be truncated when converting to integer values.

Parameters:

model (object) – Old value presented to the consumers to be migrated
scale (float) – Factor to scale the levels with. For example, a scale of 1000 would convert milliseconds to seconds.

Return type:

Union[tuple[Literal['no_levels'], None], tuple[Literal['fixed'], tuple[int, int]], tuple[Literal['cmk_postprocessed'], Literal['predictive_levels'], _PredictiveLevelsT[int]]]

migrate_to_upper_float_levels(model, scale=1.0)

Transform a previous levels configuration (Tuple, SimpleLevels, Levels or PredictiveLevels) representing upper (warn, crit) levels to a float-based model of the Levels FormSpec

Parameters:

model (object) – Old value presented to the consumers to be migrated
scale (float) – Factor to scale the levels with. For example, a scale of 1000 would convert milliseconds to seconds.

Return type:

Union[tuple[Literal['no_levels'], None], tuple[Literal['fixed'], tuple[float, float]], tuple[Literal['cmk_postprocessed'], Literal['predictive_levels'], _PredictiveLevelsT[float]]]

migrate_to_lower_integer_levels(model, scale=1.0)

Transform a previous levels configuration (Tuple, SimpleLevels, Levels or PredictiveLevels) representing lower (warn, crit) levels to an integer-based model of the Levels FormSpec. The decimal part of floating point values will be truncated when converting to integer values.

Parameters:

model (object) – Old value presented to the consumers to be migrated
scale (float) – Factor to scale the levels with. For example, a scale of 1000 would convert milliseconds to seconds.

Return type:

Union[tuple[Literal['no_levels'], None], tuple[Literal['fixed'], tuple[int, int]], tuple[Literal['cmk_postprocessed'], Literal['predictive_levels'], _PredictiveLevelsT[int]]]

migrate_to_lower_float_levels(model, scale=1.0)

Transform a previous levels configuration (Tuple, SimpleLevels, Levels or PredictiveLevels) representing lower (warn, crit) levels to a float-based model of the Levels FormSpec

Parameters:

model (object) – Old value presented to the consumers to be migrated
scale (float) – Factor to scale the levels with. For example, a scale of 1000 would convert milliseconds to seconds.

Return type:

Union[tuple[Literal['no_levels'], None], tuple[Literal['fixed'], tuple[float, float]], tuple[Literal['cmk_postprocessed'], Literal['predictive_levels'], _PredictiveLevelsT[float]]]

migrate_to_integer_simple_levels(model, scale=1.0)

Transform a previous levels configuration (Tuple or SimpleLevels) representing (warn, crit) levels to an integer-based model of the SimpleLevels FormSpec. The decimal part of floating point values will be truncated when converting to integer values.

Parameters:

model (object) – Old value presented to the consumers to be migrated
scale (float) – Factor to scale the levels with. For example, a scale of 1000 would convert milliseconds to seconds.

Return type:

Union[tuple[Literal['no_levels'], None], tuple[Literal['fixed'], tuple[int, int]]]

migrate_to_float_simple_levels(model, scale=1.0)

Transform a previous levels configuration (Tuple or SimpleLevels) representing (warn, crit) levels to a float-based model of the SimpleLevels FormSpec

Parameters:: model (object) – Old value presented to the consumers to be migrated
Return type:: Union[tuple[Literal['no_levels'], None], tuple[Literal['fixed'], tuple[float, float]]]

migrate_to_password(model)

Transform a previous password configuration represented by (“password”, <password>) or (“store”, <password-store-id>) to a model of the Password FormSpec, represented by (“cmk_postprocessed”, “explicit_password”, (<password-id>, <password>)) or (“cmk_postprocessed”, “stored_password”, (<password-store-id>, “”)).

Parameters:: model (object) – Old value presented to the consumers to be migrated
Return type:: tuple[Literal['cmk_postprocessed'], Literal['explicit_password', 'stored_password'], tuple[str, str]]

migrate_to_proxy(model)

Transform a previous proxy configuration to a model of the Proxy FormSpec. Previous configurations are transformed in the following way:

(“global”, <stored-proxy-id>) -> (“cmk_postprocessed”, “stored_proxy”, <stored-proxy-id>) (“environment”, “environment”) -> (“cmk_postprocessed”, “environment_proxy”, “”) (“url”, <url>) -> (“cmk_postprocessed”, “explicit_proxy”, <url>) (“no_proxy”, None) -> (“cmk_postprocessed”, “no_proxy”, “”)

Parameters:: model (object) – Old value presented to the consumers to be migrated
Return type:: tuple[Literal['cmk_postprocessed'], Literal['environment_proxy', 'no_proxy', 'stored_proxy', 'explicit_proxy'], str]

migrate_to_time_period(model)

Transform a previous time period configuration to a model of the TimePeriod FormSpec. Previous configurations are transformed in the following way:

<time-period> -> (“time_period”, “preconfigured”, <time-period>)

Parameters:: model (object) – Old value presented to the consumers to be migrated
Return type:: tuple[Literal['cmk_postprocessed'], Literal['stored_time_period'], str]