Profiles & checks¶

The most important concept in Vesana. Once you grasp this page, discovery, the SNMP picker, policies, 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 exactly one profile	`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 Lucide

Builtin vs. custom¶

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

Reset: Profile card → Reset restores a modified builtin to its original state.

Community Hub — the distribution path for profiles¶

New and updated builtin profiles primarily arrive via the Community Hub — a central, community-maintained collection that Vesana instances can pull profiles from and update against. It replaces the older path where profiles were baked directly into the repo seed script (which still works as a fallback). Practical effect: new device profiles or improved MIB coverage don't have to wait for a Vesana release — you can pull them from the hub any time. is_modified protects the same way it does with the classic seed run — a locally customized profile is never overwritten by a hub import.

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)
`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?
`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
`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 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->>API: POST /receiver with result
    API->>W: into 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	Set profile on host → 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)	Discard modifications, restore from seed
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