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, vm_host, server_hardware)
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.

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)
`retry_interval_seconds`	In soft state (default 15 s)
`max_check_attempts`	Soft → hard after how many failures (default 3)
`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 each service — merge of profile default and host override:

COALESCE(hs.interval_override, pc.interval_seconds)         AS interval_seconds
COALESCE(pc.check_config, '{}'::jsonb)
  || COALESCE(hs.config_overrides, '{}'::jsonb)             AS effective_config

Override is additive: override fields replace, all others come 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

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
`vm_host`	VMware/KVM host with VM list + cores
`server_hardware`	PSU/CPU/RAM layout

Background: Hosts → Discovery & SNMP picker.

Next¶

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