User guideWayseer 0.28.3Contents

Configuration

Wayseer reads one YAML file, config.yaml, from the config folder in where files are kept, or any other file with wayseer --config path/to/config.yaml. wayseer --help shows the full path on your machine. On a Mac, Settings… (⌘,) in the app menu opens the file in use in your default text editor; the menu also has About, Hide and Quit, and a Window menu.

If the file does not exist, Wayseer writes the default one there on first run, with every option described in comments. Saving it while Wayseer runs applies the changes (reloading). At start, an unknown key or a bad value stops it, naming the file and the line. For a misspelt colour: at the top level:

level=ERROR msg=config err="…/config.yaml: yaml: unmarshal errors:\n  line 2: field colour not found in type kernel.Config"

wayseer --print-config prints the file it would read.

Sections

Reloading

Saving the config file applies it while the app runs, a quarter of a second after the last write, so an editor that saves by renaming a new file over the old one is seen too. A save that changes only comments or layout does nothing. Otherwise one line in the status bar says what changed:

config: prom restarted; 1 place added

• An instance added starts, one removed stops, and one whose kind, options or actions changed restarts. A source turned off stays off (turning a source off).
• places, theme, reduce_motion, effects, keymap, home, watch_config, chrome, revocations and updates change at once. Turning both checks off stops a fetch under way.
• control, identity, memory_limit, nl and observations change when Wayseer next starts; the line says so.
• A changed license_file is read at once, and the line says what it locked or unlocked. A save to the key file itself applies the same way, while the config is watched (license and keys). A changed license_terms_accepted applies at once too.

A file that does not load changes nothing, and the line says why, as starting would: config not loaded: yaml: line 4: …. Values the file quotes are left out of it, in case a secret was written in the wrong place. Fix the file and save it again.

>reload config reloads the file now, for a folder that does not report changes, such as some network filesystems, or with watch_config: false.

Theme

Three themes are built in: dark; light, for daylight; and high-contrast, white on black with brighter borders and no glow, for low vision or a washed-out screen.

With no name, or name: auto, Wayseer follows the desktop's appearance setting: light when the desktop prefers light, high-contrast when it asks for high contrast, and dark otherwise, including where it says nothing. The desktop's settings are only read, never changed. Each platform's settings are:

Change one and the app follows: within a second on Linux, and within a few seconds on macOS and Windows, where it reads them again every two seconds.

name picks one theme to keep whatever the desktop says. Any token you set overrides the theme, whichever it is; tokens left out keep that theme's values:

theme:
  name: light
  colours:
    accent: "#8a3ffc"
  motion:
    camera_spring: 10

In every built-in theme, text meets WCAG contrast (4.5:1 for body text, 3:1 for muted text and status colors) on every surface; high-contrast holds all text to 7:1 and borders and links to 3:1. Each theme's status colors stay distinct under the three common forms of color blindness, and status also shows as a shape (see Lenses). An override can undo all of that, so check any color you change. bloom sets how strongly warn and fail glows light the scene around them: 0.8 in the dark theme, and 0 in the light and high-contrast ones, where they show as flat tints. depth sets how softly Topology blurs what is more than one link from the focus, from 0, sharp, to 1, the dark and light themes' value; high-contrast keeps it at 0. An unknown name stops Wayseer and lists the built-in themes.

Keys

A key is a character (h, ?, +), a named key (left, right, up, down, home, end, esc, enter, tab, backspace, delete, space, f1 to f4), or either with modifiers (primary+, ctrl+, alt+, super+, cmd+, shift+). Two keys with a space between them are a chord. A command may take arguments. An empty command unbinds the key.

primary is the modifier each platform's shortcuts use: Ctrl on Linux and Windows, Cmd on macOS. The default keys use it, so one keymap works everywhere. ctrl is always Ctrl, and alt is Option on a Mac. super is the Super or Windows key, and Cmd on a Mac. cmd names Cmd only on macOS; on Linux and Windows a keymap with it is refused, with its line.

keymap:
  primary+w: app.quit
  g h: view.home
  g 2: time.last span=2h
  "0": ""

On a Mac, Enter is Return and Backspace is Delete. The keys page shows each default as Linux and Windows write it and as macOS does, so Ctrl+K is ⌘K there. ⌘Q and ⌘W quit on a Mac, and the window manager's Alt+F4 does on Windows and most Linux desktops. In a line being edited, Cmd selects all and pastes on macOS (⌘A, ⌘V) and Option moves and deletes by word; elsewhere Ctrl does both.

Modules

Each module instance has a kind, a name you choose, and options for that kind:

modules:
  - kind: internal       # Wayseer itself: frame time, memory, modules
    name: wayseer
  - kind: prometheus
    name: prom
    options:
      url: http://localhost:9090

The default config lists the options of each module kind in comments, and each module has a page in this guide (modules).

An instance's actions lists the actions it may offer, by ID, such as actions: [restart, scale]. With none listed, the default, it offers none, and Wayseer only reads from it. An ID the module does not offer stops the app, naming the ones it does. Each action still waits for you to confirm it (actions).

Turning a source off

S, or >source.list in the palette, lists each instance with its kind, how fresh its data is, and how many entities it has. Space or a click turns the one at the cursor off or on, and Enter shows its entities in Grid. A click on an instance's name in the status bar turns it off or on too, and source off prom and source on prom in the palette do the same by name. An instance turned off stops, and its entities, edges and series leave the view until it is on again. The strip shows it faintly, as off rather than failing. Turning a source off changes only what the app shows, never the config, and it stays off after a restart: the names of the instances turned off are kept in sources.yaml (where files are kept). A name the config no longer has is forgotten.

An external module's instance also lists, beneath it, who signed its package and what the package declares it may do.

An instance of a paid kind with no key to unlock it says locked instead, and doesn't start. Space, a click or source on only says why. Once a key unlocks it, it starts, unless you turned it off (license and keys).

External modules

A module of your own runs as an external module once it is a signed package you installed with >modules.install. The entry names the package by its id, as module: acme/widget, and passes the module's own options through. External modules describes how. It runs only under a license key; without one it is locked and its program never starts (license and keys). Each start checks the package again, and a package that fails is locked with the reason (why a module is refused).

A command naming any other program is a config error: Wayseer runs no unsigned program (Upgrading).

Upgrading. SQL, Kubernetes and files are built in. A config written for their old programs, as kind: external with command: [wayseer-sql], still works: the app runs the built-in module with the same options, and the status line says which kind to write instead. The app never changes the file. External modules shows the change.

Identity

Two modules often describe the same machine: Prometheus scrapes db-07:9100 while an inventory lists db-07.lan. Identity rules link such entities with a same_as edge, and the lenses show them as one entity until >view.merge shows them apart. The filter same_as:<ref> follows the links. The defaults are:

identity:
  - name: hostname
    match: hostname
    kinds: [host, node]
    keys: [name, hostname, instance, address]
  - name: ip
    match: ip
    kinds: [host, node]
    keys: [name, ip, instance, address]
  - name: cloud-instance
    match: attribute
    keys: [cloud.instance_id]

Two entities are linked when any key of one has the same value as any key of the other under the same rule. Each rule has:

Some values never link, because many machines share them: localhost, and loopback, link-local, multicast and unspecified addresses. Entities from the same module instance are never linked to each other, and a link goes away when the values stop matching.

A list replaces the defaults entirely, so copy the ones you want to keep. identity: [] turns linking off.

Places

An entity can have a place on Earth. Some modules send one. For the rest, name your regions, zones or cities under places, and an entity whose attribute holds one of those names is placed there. For cloud regions:

places:
  names:
    us-east-1:      {lat: 38.9,  lon: -77.4}
    eu-west-1:      {lat: 53.35, lon: -6.26}
    ap-southeast-1: {lat: 1.35,  lon: 103.82}

An entity with no place of its own takes the place of what it is a member_of, such as a host in a placed cluster: the first such owner, by the order the module sent the edges, that has a place of its own. It goes one step only, so a process on that host is not placed. A place a module sends comes first, then one named here, then one taken from an owner, and an entity follows its owner when the owner moves or loses its place.

Names are only matched against this list. Nothing is looked up anywhere else.

To check what is placed, run with --dump-world 2s: its place table counts the entities whose place came from a module, from names, or from an owner, and those with none. The demo profile names its three cities this way. Geo shows what is placed (lenses).

Secrets

Secrets never go in the config file. Wherever one is needed, name where it is kept, with one of:

nl:
  provider: anthropic
  secret_keyring: wayseer/anthropic   # or: secret_file: ~/.config/wayseer/anthropic-key

Wayseer writes the config with mode 0600, and never writes a secret to a log, an error or the request log.

The keyring

Wayseer only reads the keyring. Store the secret first with your platform's own tool, under a service and an account, the two halves of secret_keyring. Each command below asks for the secret rather than taking it on the command line, where it would stay in your shell history. For secret_keyring: wayseer/anthropic:

On Linux, Wayseer reads the item whose service and account attributes match; if the keyring is locked, it asks the keyring to unlock, and waits up to two minutes for you. On a Mac, the first read may ask whether Wayseer may use the item; Always Allow stops it asking again. On Windows, the credential's target is the service and its user the account.

An error names the service and account, never the secret. With no keyring running, it says so and names the other two options:

secret_keyring: no keyring: the Secret Service is not running; use secret_file or secret_env instead

An external module on Linux reaches the keyring only with DBUS_SESSION_BUS_ADDRESS in its env.

Where files are kept

Each platform keeps them where its own apps do:

• state.yaml remembers that the tour was seen, the end-user license version you accepted, and the version you were last told of.
• places.yaml holds bookmarks (time and bookmarks).
• sources.yaml names the sources turned off.
• windows.yaml lists the windows open at quit.
• license.key is the license key you added.
• modules/ holds the packages you installed.
• revocations/ holds the revocation list and record.
• updates.yaml names the releases you were told of.
• nl-log.jsonl is the request log.
• actions.jsonl is the action log.
• downloads/ holds the marketplace packages downloaded and not yet installed, and releases of Wayseer until they are installed.

All are readable only by you. The control socket, when it is on, is kept apart from these.

XDG_CONFIG_HOME and XDG_STATE_HOME, when set to a full path, win on every platform: the files go in a wayseer folder under them. On Linux that is the usual XDG rule; on macOS and Windows it lets one setting serve every machine. --config wins over both for the config. The Flatpak sets both to folders of its own under ~/.var/app/org.wayseer.Wayseer/ (Installing on Linux).