Skip to main content
emisar

Vector observability pipeline

v0.1.15

Read-only ops for a Vector (vector.dev) pipeline running on the runner host: version + compiled-component inventory, offline config validation, the configured topology as Graphviz DOT, a bounded live event tap, plus health and per-component throughput reads over the local API. CLI subcommands talk to the local binary; the API reads hit 127.0.0.1:8686.

7 allowed by default
Pack ID
vector
Vendor
emisar
OS
linux
Actions
7
Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.
vector curl

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host 
sudo emisar pack install vector --hash sha256:dba108d0b263e7c46b5fea0861fb45096ab00f7348b4892309b17113652a60ea

Setup

Drives the local Vector instance on the runner host: the CLI actions invoke the vector binary directly, and the health / metrics reads call Vector's HTTP API at $VECTOR_API (default 127.0.0.1:8686). No credentials — the API is unauthenticated and binds loopback only.

Environment

Set these on the runner host, then add each name to execution.inherit_env so the value reaches the action.

  • VECTOR_API default http://127.0.0.1:8686

    Vector GraphQL/health API base URL; requires api.enabled=true in the Vector config.

Host access

Run these commands yourself on the runner host. Emisar shows and copies setup recipes; it never runs them.

Read Vector's protected configuration even when deployment replaces restrictive files.

vector.validatevector.graph

Run the Emisar service as root

Grant access 
sudo install -d -m 0755 /etc/systemd/system/emisar.service.d
printf '%s\n' '[Service]' 'User=root' 'Group=root' | sudo tee /etc/systemd/system/emisar.service.d/10-vector-host-access.conf >/dev/null
sudo systemctl daemon-reload
sudo systemctl restart emisar
Verify access 
test "$(systemctl show emisar --property=User --value)" = root
sudo test -r /etc/vector/vector.yaml

Impact: Every Emisar action on this runner executes as root and can read every Vector config, including sink credentials embedded directly in those files.

Notes

  • VECTOR_API only reaches an action when the runner allowlists it in execution.inherit_env — the action env is scrubbed to PATH/LANG/LC_ALL/TERM by default. Unset, it falls back to http://127.0.0.1:8686, so a Vector API bound elsewhere silently reads the local one instead.
  • The HTTP API is unauthenticated and binds 127.0.0.1:8686 only when api.enabled = true in the Vector config. The CLI actions (version, list, validate, graph, tap) do not need it — they talk to the local binary and work whether or not the API is on.
  • VERSION CAVEAT: Vector's observability API was GraphQL ( /graphql , /playground ) through v0.54, then migrated to gRPC in v0.55 (April 2026), which REMOVED both. So the CLI subcommands work on ANY version, plain GET /health works on ANY version, but the raw GraphQL component_metrics action only works on Vector <= 0.54 (it 404s on >= 0.55). Run vector.version first; on >= 0.55 use gRPC tooling for component metrics instead.
  • Every action is read-only — none start, stop, reload, or reconfigure Vector. tap adds slight overhead on the running instance while sampling, then auto-exits.

Verify it works

Runs vector.health, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host 
sudo emisar pack verify vector

Install and configure a pack walks through the whole sequence on a host.

Actions 7 total

View on GitHub
  • vector.component_metrics exec low Low — read-only or trivially reversible

    POST /graphql (component metrics)

    Show per-component throughput from the Vector GraphQL API: received and sent event totals for every source, transform, and sink, plus sent-bytes for sinks. GraphQL API — Vector <= 0.54 ONLY. On Vector >= 0.55 (gRPC migration, April 2026) the /graphql endpoint was REMOVED and this returns 404; run vector.version first and, if >= 0.55, use gRPC tooling instead. Requires api.enabled=true; binds 127.0.0.1:8686.

    View source on GitHub
  • vector.graph exec low Low — read-only or trivially reversible

    vector graph

    Show the configured Vector topology as a Graphviz DOT graph — the source -> transform -> sink wiring read from the config file. Offline: reads the config, emits DOT, connects to nothing. Pipe the output to `dot` to draw it. Talks only to the local binary — needs no API.

    View source on GitHub
  • vector.health exec low Low — read-only or trivially reversible

    GET /health

    Check liveness of the local Vector API. Returns {"ok":true} (HTTP 200) when serving, or {"ok":false} (HTTP 503) while draining/shutting down. Works on ANY Vector version — this endpoint survived the v0.55 gRPC migration. Requires api.enabled=true in the Vector config; binds 127.0.0.1:8686.

    View source on GitHub
  • vector.list exec low Low — read-only or trivially reversible

    vector list --format json

    List the sources, transforms, and sinks compiled into this Vector binary, as JSON. This is the static component catalog of the build — not the running topology (use vector.graph for what is actually configured). Talks only to the local binary — needs no API.

    View source on GitHub
  • vector.tap exec medium Medium — changes state, easily reversible

    vector tap --outputs-of

    Sample live events flowing OUT of a named component for a bounded window, as JSON, then auto-exit. The run terminates after duration_ms — NOT on --limit alone, which caps events PER sampling interval, not total, so without a duration a tap can run indefinitely. Adds slight overhead on the running Vector instance while sampling. Connects to the local API (tap is API-backed); component is matched against configured component IDs and supports glob patterns.

    View source on GitHub
  • vector.validate exec low Low — read-only or trivially reversible

    vector validate --no-environment

    Validate a Vector config file offline — checks syntax and topology. Runs with --no-environment, so it checks structure only and skips all network sink healthchecks and environment probing — it never connects to anything. Talks only to the local binary — needs no API.

    View source on GitHub
  • vector.version exec low Low — read-only or trivially reversible

    vector --version

    Show the Vector binary version and build metadata. Run this FIRST: it tells you whether the observability API is GraphQL (Vector <= 0.54) or gRPC (>= 0.55, April 2026). That determines whether the GraphQL component_metrics action will work or 404. Talks only to the local binary — needs no API.

    View source on GitHub
← Back to registry
Pack reference  Publish your own