Profiles & checks¶

The most important concept in Vesana. Once you grasp this page, discovery, the SNMP picker, effective config, and visuals all fall into place.

The two tiers¶

flowchart LR
    subgraph "Profile — what is this device?"
        P[Profile 'APC Smart-UPS']
        PC1[Profile-check 'Battery voltage']
        PC2[Profile-check 'Output load']
        PC3[Profile-check 'Temperature 1']
        P --- PC1
        P --- PC2
        P --- PC3
    end

    subgraph "Hosts — actual devices"
        H1[Host 'ups-server-room']
        H2[Host 'ups-rack42']
    end

    subgraph "host_services — what is actually monitored?"
        S1[Service 'Battery voltage']
        S2[Service 'Output load']
        S3[Service 'Battery voltage']
        S4[Service 'Output load']
    end

    P --> H1
    P --> H2
    PC1 --> S1
    PC2 --> S2
    PC1 --> S3
    PC2 --> S4

Layer	Describes	Table
Profile	Device type + capabilities + visual layout type	`profiles`
Profile-check	One check definition per profile — type, config, thresholds	`profile_checks`
Host	Concrete monitored device, has one primary profile and optionally further ones	`hosts`
Host-service	Instance of a profile-check for a host, optional overrides	`host_services`

Profile — what is this device¶

A profile contains:

Name + description
Category (server, network_device, ups, storage, vmhost, …)
Vendor (cisco, hpe, apc, …)
Capabilities:
- agent_capable — can an agent be installed?
- snmp_enabled — is SNMP supported?
- ip_required — does the profile need an IP?
- os_family — windows / linux / generic
sysOID / sysDescr patterns — for auto-matching at discovery
Visual type (switch_portmap, ups_panel, nas_diskbay, firewall_panel)
Icon — from the icon library (Configuration → Icons)

Builtin vs. custom¶

Profiles are either builtin (shipped, is_builtin=true) or custom (user-created). Builtins can be edited — then is_modified=true.

Reset exists per check, not for the whole profile: an edited builtin check can be reset to its default values (super admins only), optionally including the overrides on all hosts. If a check has no shipped default values, Vesana rejects the reset instead of reporting success.

Vesana library — the distribution path for profiles¶

Device profiles come from the Vesana library — the catalog of profiles that Vesana publishes and signs. A new installation does not ship a local profile catalog; discovery matching uses the detection rules from the library. New device profiles or improved coverage therefore don't have to wait for a Vesana release.

Install creates a profile; the MIBs its checks use come along. Only versions signed by Vesana are installed.
Profiles not changed locally are updated automatically every hour. If the library has a newer version of a locally modified profile, it shows "Update available"; a super admin applies it via the comparison dialog. Passwords and communities appear only masked in the preview.

Profile-check — what is monitored¶

Each profile has N profile-checks. Each one has:

Field	Meaning
`name`	Display name, e.g. „Battery voltage"
`check_type`	`ping`, `http`, `snmp`, `agent_cpu`, `agent_disk`, `snmp_string`, `snmp_table`, …
`check_config`	JSONB with type-specific options (OID, path, pattern …)
`interval_seconds`	How often (default 60 s)
`confirmation_interval_seconds`	Gap between confirmation retries in the `probing` state (default 10 s); only effective when the server runs the check itself, not for agent/collector
`confirmation_attempts`	Confirmed failures before `probing → degraded` (default 1)
`threshold_warn`	Warn threshold
`threshold_crit`	Crit threshold
`check_mode`	`active` / `passive` / `agent`
`value_type`	`gauge`, `counter`, `status`, `info`, `duration`
`script_id`	optional: reference to a monitoring script
`auto_add`	created automatically when the profile is applied?
`sort_order`	Order in the check table; set by dragging on the profile and the default for every device with this profile until someone reorders there
`chart_style`	Display in history: `auto` (default), `curve`, `band`, `both`; NULL = not set (= `auto`)
`is_modified`	did someone edit a builtin?

Auto-add¶

auto_add = true: when a profile is applied to a host, the check is auto-created. auto_add = false: the check is in the profile, but as an option — operator activates explicitly.

Useful for checks that aren't on every model (fan sensors missing on fanless switches).

Host-service — instance with overrides¶

When a profile is applied to a host, host_services are created for each profile-check with auto_add=true. Per service you can override what the profile-check defines:

Field	Meaning
`display_name`	Display name, can differ per host
`profile_check_id`	FK to profile-check
`interval_override`	NULL = use profile-check value; set = use override
`chart_style_override`	NULL = use the profile-check value; otherwise `auto`, `curve`, `band` or `both` (curve with the status band below) — how the check's history is drawn
`config_overrides`	JSONB patch over `check_config`
`threshold_warn_override`	same logic
`threshold_crit_override`	same logic

Effective config¶

Worker and frontend compute the effective config for every service — the merge of profile default and host override: override fields replace, all other fields stay from the profile check.

flowchart LR
    PC[Profile check<br/>interval=60<br/>warn=80<br/>crit=95<br/>config={path:'/'}]
    HS[Host service<br/>interval_override=NULL<br/>warn_override=70<br/>config_overrides={path:'/var'}]
    EFF[Effective<br/>interval=60<br/>warn=70<br/>crit=95<br/>config={path:'/var'}]
    PC --> EFF
    HS --> EFF

Inherited is not overridden. When a host check is saved, only what differs from the profile value remains as an override — a field whose value equals the profile is not an override. That is why the host editor shows thresholds as "empty = inherited" with the profile value as placeholder, and a profile update still reaches the host. (Previously every save froze all inherited values as host values; existing data was unpinned during the update.) The same applies to the configurable values of a script.

Lifecycle of a profile-check¶

sequenceDiagram
    participant U as User
    participant API
    participant DB
    participant R as Receiver
    participant W as Worker
    participant A as Agent/Collector

    U->>API: Apply profile 'APC Smart-UPS' to host 'ups-rack42'
    API->>DB: INSERT host_services (for each auto_add check)
    A->>API: GET /agent/config or /collector/config
    API->>DB: SELECT host_services + COALESCE(profile_checks)
    API-->>A: deliver effective configs
    A->>A: run check
    A->>R: send result
    R->>W: via the Redis stream
    W->>DB: writes check_results, current_status
    W->>DB: alert evaluation when threshold crossed

Capabilities filter check types¶

In the frontend (Add-Service modal) and backend (POST /host-services/), check types are filtered contextually:

Agent checks (agent_*) → only hosts with profile.agent_capable = true and agent_managed = true
SNMP checks → only hosts with profile.snmp_enabled = true
Network checks (ping, port, snmp, ssh_) → only hosts with ip_address set
Profile-checks are filtered OS-aware: Linux hosts don't see Windows-specific checks and vice versa

So „not possible" vs. „not allowed" is visible immediately.

Profile operations¶

Operation	What happens
Apply	Assign the profile to a host additionally (does not replace an existing profile) → create host_services for `auto_add` profile-checks
Clone	Duplicate profile + all profile-checks (auto-rename with suffix)
Export	Download JSON bundle `{schema_version, profile, checks}`
Import	Upload JSON bundle (or ZIP), one bad bundle doesn't break the rest
Reset (builtin check)	Reset an edited builtin check to its default values, optionally including host overrides
Usage	how many hosts/services use this profile?

UI details: Hosts & devices → Edit profiles.

Visual types¶

Profiles with visual_type enable special hardware visualizations on the host detail page:

Visual type	For
`switch_portmap`	Port layout for switches with up/down/speed per port
`ups_panel`	UPS status panel with battery / load / temperature
`nas_diskbay`	Disk-bay layout for NAS
`firewall_panel`	Firewall with VPN tunnels + throughput

Background: Hosts → Discovery & SNMP picker.

Next¶

Hosts → Edit profiles — the UI
Status & state model — what happens to results
Glossary