Virtualization — vSphere events

Collecting events from VMware vSphere — ESXi hosts and vCenter Server — via the vSphere API. This is the agent’s vsphere_event reader: it polls the vCenter for event history and converts each event into a Sondar event.

The reader

vsphere_event is a reader in the agent (registered under the agent kind), so it is configured as a reader in a collection task rather than as an app:

readers:
  - vsphere_event:
      url: https://vcenter.example.com/sdk   # required
      username: admin@vsphere.local
      password: secret
      timeout: 10s
      sleep_time: 1s
      insecure: true
      filter:
        disable_full_message: false
        category: []
        type: []
        event_type_id: []
        tag: []
        max_count: 100
        event_chain_id: ""
        recursion: all
        username:
          enable: false
          system_user: false
          user_list: []

vSphere versions. The reader uses VMware’s own govmomi client, pinned at v0.30.2. The floor is vSphere API 6.5 — that is what the max_count option requires, and it is the only version requirement stated anywhere in the collector. There is no tested upper bound recorded: newer vCenters are expected to work, because govmomi negotiates the API version, but this page will not claim a matrix nobody has run. If you are on 8.x and it works or does not, that is worth telling us.

An earlier revision of this line read “Supported vSphere versions: 6.5, 6.7 and 7.0”. Those three numbers came from two unrelated comments — the 6.5 minimum above, and an upstream Telegraf note that cluster metrics are reported oddly on “6.7, 7.0 and possible more”. Neither was a support matrix.

url (required) — the vCenter or ESXi SDK URL.
username / password — vCenter credentials.
timeout (default 10s) — the request timeout.
sleep_time (default 1s, minimum 1s) — how long to rest when no new events arrive, to avoid hammering the vCenter.
insecure (default true) — skip TLS certificate verification. This default trusts any certificate the vCenter presents, which makes the connection interceptable on an untrusted network; the credentials above travel over it. It ships true because self-signed vCenter certs are the norm and the collector would otherwise fail on most installs. Set it false wherever vCenter has a certificate from a CA your agents trust.

filter — the vSphere EventFilterSpec:

key	what it does
`disable_full_message`	drop the full formatted message per event
`category`	only events in these categories (Event severity classes)
`type` / `event_type_id`	only these event types; the two are mutually exclusive, and `event_type_id` is the one for current vSphere (API 4.0+)
`tag`	only events carrying these tags (API 4.0+)
`max_count`	max events per request, default 100
`event_chain_id`	filter by event chain
`recursion`	`all`, `self` or `children` — how far down the inventory hierarchy to collect (default `all`)
`username`	restrict to specific users (`enable`, `system_user`, `user_list`)

The reader keeps a checkpoint (vsphere.meta) so an interrupted poll resumes where it stopped rather than re-reading the whole event history.

The collected events flow through the standard transformers/senders pipeline, so they can be shaped like any other event and sent to the event index.