User guideWayseer 0.28.3Contents

Files

The file module reads CSV and JSON files and turns their records into entities, links, metrics and events, as a mapping in the config says. Use it for an inventory kept in a spreadsheet, an export from another tool, or a recording. It reads the files again when they change. The demo world is made this way.

Configuration

modules:
  - kind: file
    name: inventory
    options:
      files:
        - path: ~/fleet/hosts.csv
          entities:
            kind: host
            id: hostname
            status: state
            reason: note
            attrs: [os, cores, memory]
            units: {memory: bytes}
            tags: tags
            edges:
              - {rel: depends_on, to: depends, kind: host}
        - path: ~/fleet/services.json
          records: data.services
          entities: {kind: service, id: id, attrs: [meta.owner]}
        - path: ~/fleet/cpu.csv
          series:
            kind: host
            id: host
            time: ts
            metrics:
              cpu.utilisation: {field: cpu, unit: percent}
        - path: ~/fleet/changes.csv
          events:
            kind: host
            id: host
            time: ts
            severity: level
            type: what
            message: text
            fields: [version]

With this hosts.csv:

hostname,state,note,os,cores,memory,tags,depends
web-01,ok,,linux,8,17179869184,prod;edge,db-01
db-01,warn,disk 91% full,linux,32,68719476736,prod,

there are two hosts, web-01 depending on db-01, and db-01 shows as warn with its reason. Detail shows db-01's memory as 64 GiB.

Each file maps its records to entities, series, events, or any of them together. The format comes from the extension (.csv, .tsv or .json) unless format says.

• Fields. In a CSV file a field is a column, by its header. In JSON it is a key, dotted to reach into nested objects, as in meta.owner.
• Several values. A CSV cell holding several values, such as tags or the targets of a link, separates them with ;. JSON uses an array.
• Kinds and relations. A kind or relation is a lowercase name, such as host or depends_on, with at most one prefix, such as acme/rack. The relations the lenses know are runs_on, depends_on, talks_to, member_of, owns and parent_of.
• Status. One of ok, warn, crit, down or unknown.
• Units. units gives a numeric attribute its unit, by field: bytes, bytes_per_second, bits, bits_per_second, percent, ratio (0 to 1, shown as a percentage), seconds, count or per_second. Detail then shows 64 GiB rather than 68719476736, and a filter can say memory>32GiB.
• Times. RFC 3339, such as 2026-09-01T10:00:00Z, or Unix seconds.
• Series. A series id with no entity of its own still shows, as a bare entity of that kind.

The options below go under options.

Units

A metric's unit is one of bytes, bytes_per_second, bits, bits_per_second, percent, ratio (0 to 1), seconds, count or per_second. Without one, the number shows as it is. A metric name used in more than one file must have the same unit in each.

Traffic

An edge can carry traffic: how much flows along it each second. rate names the field holding one rate for each id in to, in the same order, and unit says what is counted: requests, bytes or messages. With this services.csv:

id,calls,call_rates
web,api;auth,120;4.5
api,,

and the mapping

edges:
  - {rel: talks_to, to: calls, kind: service, rate: call_rates, unit: requests}

web talks to api at 120 requests a second and to auth at 4.5. An empty rate cell means no traffic is known. A record whose rates are not numbers, are negative, or do not match its ids one for one is skipped and reported like any other bad record. The rate is the traffic now; a file holds no history of it, so edit the file to change it. The demo's talks_to edges carry rates this way.

When files change

The module watches the files and reads a file again soon after it changes, and every rescan in case a change was missed. A record that cannot be read, such as a row with a missing id or a time it cannot parse, is skipped. It is reported once, as a warn event naming the file and the line. A missing or unreadable file shows in the module's health, and the entities it gave are removed until it can be read again.

Replay

With replay: true, every time in the files moves by the same amount, so that the newest lands at the moment the files were first loaded. A recording made last week then shows as if it had just happened, which suits demos. The shift is fixed at the first load, so a file that changes later keeps its times in step with the rest.