zabgrab.model.config

Config file schema.

Every config file (and the merged result of all of them) validates against Config. All settings are optional in the schema; the values used when nothing is configured live in BUILTIN_DEFAULTS, which is treated as the lowest config layer so that every resolved value has a recorded source.

Module Attributes

BUILTIN_DEFAULTS

Values used when no config layer sets them.

Classes

Agg(*values)

Hourly trend statistics: the minimum, average, maximum and count.

AuthMethod(*values)

How to authenticate with a Zabbix server.

Config(*[, defaults, servers, templates])

A config file, or the merged result of several.

Defaults(*[, server, from_, to, resolution, ...])

The [defaults] table: settings applied to every run.

FetchSettings(*[, server, from_, to, ...])

Settings shared by [defaults] and templates.

Format(*values)

Output file formats.

Resolution(*values)

Data resolution.

ServerConfig(*, url[, auth, token_env, ...])

A Zabbix server (a [servers.NAME] table).

Template(*[, server, from_, to, resolution, ...])

A named, reusable fetch (a [templates.NAME] table).
class zabgrab.model.config.Format(*values)[source]

Bases: StrEnum

Output file formats.

H5, MAT

HDF5 and MATLAB v7.3 (the same layout), which can hold several fetches.

TSV, CSV

Tab- and comma-separated values, with # comment lines of metadata.

class zabgrab.model.config.Resolution(*values)[source]

Bases: StrEnum

Data resolution.

RAW

Every value collected (Zabbix’s history).

HOURLY

Hourly statistics (Zabbix’s trends), for numeric items only.

class zabgrab.model.config.Agg(*values)[source]

Bases: StrEnum

Hourly trend statistics: the minimum, average, maximum and count.

class zabgrab.model.config.AuthMethod(*values)[source]

Bases: StrEnum

How to authenticate with a Zabbix server.

class zabgrab.model.config.ServerConfig(*, url, auth=AuthMethod.TOKEN, token_env=None, username=None, verify_ssl=True, timeout=30.0)[source]

Bases: BaseModel

A Zabbix server (a [servers.NAME] table).

Parameters:

  • url (Annotated[str, AfterValidator(func=~zabgrab.model.names.validate_url)])

  • auth (AuthMethod)

  • token_env (Annotated[str, AfterValidator(func=~zabgrab.model.config._validate_env_name)] | None)

  • username (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])] | None)

  • verify_ssl (bool)

  • timeout (Annotated[float, Gt(gt=0)])

url

The frontend or API URL.

Type:

str

auth

Log in with an API token (default) or a username and password.

Type:

AuthMethod

token_env

An environment variable holding the token (else the keyring is used).

Type:

str or None

username

The default username for password logins.

Type:

str or None

verify_ssl

Whether to check the server’s TLS certificate.

Type:

bool

timeout

Seconds to wait for each API request.

Type:

float

model_config = {'extra': 'forbid', 'frozen': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class zabgrab.model.config.FetchSettings(*, server=None, from_=None, to=None, resolution=None, agg=None, format=None, output_dir=None, output_pattern=None, timezone=None, jobs=None, max_items=None, mat_text_warn_entries=None)[source]

Bases: BaseModel

Settings shared by [defaults] and templates.

Each field corresponds to a zabgrab fetch option of the same name (from is --from, output_dir is --output-dir, and so on), except mat_text_warn_entries, which is config only. Unset fields are None.

Parameters:

  • server (Annotated[Annotated[str, AfterValidator(func=~zabgrab.model.names.validate_server_ref), Tag(tag=<value>)] | Annotated[Choice[Annotated[str, AfterValidator]], Tag(tag=<choice>)], Discriminator(discriminator=~zabgrab.model.choice._discriminate, custom_error_type=None, custom_error_message=None, custom_error_context=None), AfterValidator(func=~zabgrab.model.config._ask_only)] | None)

  • from_ (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])] | None)

  • to (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])] | None)

  • resolution (Resolution | None)

  • agg (Annotated[list[Agg], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)]), AfterValidator(func=~zabgrab.model.config._validate_unique)] | None)

  • format (Annotated[Annotated[Format, Tag(tag=<value>)] | Annotated[Choice[Format], Tag(tag=<choice>)], Discriminator(discriminator=~zabgrab.model.choice._discriminate, custom_error_type=None, custom_error_message=None, custom_error_context=None)] | None)

  • output_dir (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])] | None)

  • output_pattern (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])] | None)

  • timezone (Annotated[str, AfterValidator(func=~zabgrab.model.config._validate_timezone)] | None)

  • jobs (Annotated[int, Gt(gt=0)] | None)

  • max_items (Annotated[int, Gt(gt=0)] | None)

  • mat_text_warn_entries (Annotated[int, Ge(ge=0)] | None)

model_config = {'extra': 'forbid', 'frozen': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class zabgrab.model.config.Defaults(*, server=None, from_=None, to=None, resolution=None, agg=None, format=None, output_dir=None, output_pattern=None, timezone=None, jobs=None, max_items=None, mat_text_warn_entries=None)[source]

Bases: FetchSettings

The [defaults] table: settings applied to every run.

Parameters:

  • server (Annotated[Annotated[str, AfterValidator(func=~zabgrab.model.names.validate_server_ref), Tag(tag=<value>)] | Annotated[Choice[Annotated[str, AfterValidator]], Tag(tag=<choice>)], Discriminator(discriminator=~zabgrab.model.choice._discriminate, custom_error_type=None, custom_error_message=None, custom_error_context=None), AfterValidator(func=~zabgrab.model.config._ask_only)] | None)

  • from_ (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])] | None)

  • to (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])] | None)

  • resolution (Resolution | None)

  • agg (Annotated[list[Agg], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)]), AfterValidator(func=~zabgrab.model.config._validate_unique)] | None)

  • format (Annotated[Annotated[Format, Tag(tag=<value>)] | Annotated[Choice[Format], Tag(tag=<choice>)], Discriminator(discriminator=~zabgrab.model.choice._discriminate, custom_error_type=None, custom_error_message=None, custom_error_context=None)] | None)

  • output_dir (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])] | None)

  • output_pattern (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])] | None)

  • timezone (Annotated[str, AfterValidator(func=~zabgrab.model.config._validate_timezone)] | None)

  • jobs (Annotated[int, Gt(gt=0)] | None)

  • max_items (Annotated[int, Gt(gt=0)] | None)

  • mat_text_warn_entries (Annotated[int, Ge(ge=0)] | None)

model_config = {'extra': 'forbid', 'frozen': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class zabgrab.model.config.Template(*, server=None, from_=None, to=None, resolution=None, agg=None, format=None, output_dir=None, output_pattern=None, timezone=None, jobs=None, max_items=None, mat_text_warn_entries=None, description=None, items=<factory>)[source]

Bases: FetchSettings

A named, reusable fetch (a [templates.NAME] table).

Parameters:

  • server (Annotated[Annotated[str, AfterValidator(func=~zabgrab.model.names.validate_server_ref), Tag(tag=<value>)] | Annotated[Choice[Annotated[str, AfterValidator]], Tag(tag=<choice>)], Discriminator(discriminator=~zabgrab.model.choice._discriminate, custom_error_type=None, custom_error_message=None, custom_error_context=None), AfterValidator(func=~zabgrab.model.config._ask_only)] | None)

  • from_ (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])] | None)

  • to (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])] | None)

  • resolution (Resolution | None)

  • agg (Annotated[list[Agg], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)]), AfterValidator(func=~zabgrab.model.config._validate_unique)] | None)

  • format (Annotated[Annotated[Format, Tag(tag=<value>)] | Annotated[Choice[Format], Tag(tag=<choice>)], Discriminator(discriminator=~zabgrab.model.choice._discriminate, custom_error_type=None, custom_error_message=None, custom_error_context=None)] | None)

  • output_dir (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])] | None)

  • output_pattern (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])] | None)

  • timezone (Annotated[str, AfterValidator(func=~zabgrab.model.config._validate_timezone)] | None)

  • jobs (Annotated[int, Gt(gt=0)] | None)

  • max_items (Annotated[int, Gt(gt=0)] | None)

  • mat_text_warn_entries (Annotated[int, Ge(ge=0)] | None)

  • description (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])] | None)

  • items (list[ItemSpec])

description

What the template is for.

Type:

str or None

items

The items to fetch.

Type:

list of ItemSpec

model_config = {'extra': 'forbid', 'frozen': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class zabgrab.model.config.Config(*, defaults=<factory>, servers=<factory>, templates=<factory>)[source]

Bases: BaseModel

A config file, or the merged result of several.

Parameters:
defaults

Settings for every fetch.

Type:

Defaults

servers

The configured servers, by name.

Type:

dict of str to ServerConfig

templates

The templates, by name.

Type:

dict of str to Template

model_config = {'extra': 'forbid', 'frozen': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

zabgrab.model.config.BUILTIN_DEFAULTS: dict[str, Any] = {'agg': ['min', 'avg', 'max'], 'jobs': 6, 'mat_text_warn_entries': 200000, 'max_items': 50, 'output_dir': '.', 'output_pattern': '{hosts}_{template}_{from}--{to}', 'resolution': 'raw', 'timezone': 'local'}

Values used when no config layer sets them. Keys are [defaults] keys.

from, to and format deliberately have no built-in value: when nothing sets them, the user is asked (or the format is taken from the output file name).