Skip to main content
emisar

Vector observability pipeline

v0.1.16

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 counters. CLI subcommands use the local binary; health reads the API at 127.0.0.1:8686, and counters read the Prometheus exporter at 127.0.0.1:9598/metrics.

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 binary 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 before copying it into the runner's packs dir. That hash covers the exact bytes this page was built from, so a tampered copy is rejected. The command reloads a running daemon itself, so you don't need to restart it manually.

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

Setup

Inspect the Vector instance on this host using its CLI, health API, and Prometheus exporter. Configure the exporter separately from the API; neither read starts or reconfigures Vector.

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 health API base URL; requires api.enabled=true in the Vector config.

  • VECTOR_METRICS_URL default http://127.0.0.1:9598/metrics

    Complete URL of this instance's Prometheus exporter. Connect an internal_metrics source with the default vector namespace to the sink.

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

  • Allowlist VECTOR_API and VECTOR_METRICS_URL in the runner's execution.inherit_env when overriding their defaults. Otherwise each read uses its loopback default.
  • Enable the health API with api.enabled: true and api.address: 127.0.0.1:8686 . The live tap also needs the API; version, list, validate, and graph use the local binary.
  • For counters, add sources.emisar_internal.type: internal_metrics and sources.emisar_internal.namespace: vector ; add sinks.emisar_metrics.type: prometheus_exporter , sinks.emisar_metrics.inputs: [emisar_internal] , and sinks.emisar_metrics.address: 127.0.0.1:9598 . The exporter serves /metrics without needing api.enabled . Bind it explicitly to loopback: the sink's vendor default is 0.0.0.0:9598.
  • Keep unauthenticated API/exporter endpoints private. vector.component_metrics supports the Vector 0.55+ exporter, requires curl 8.4+, and fails when no valid per-component counters arrive; it does not call the removed GraphQL endpoint.
  • 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 script low Low: read-only or trivially reversible

    Show per-component counters

    Show per-component counters from this Vector instance's Prometheus exporter: received and sent events and bytes, errors, and discarded events where present. Retains component id, kind, and type; sums other label dimensions and omits timestamps. Requires an internal_metrics source with the default vector namespace connected to a prometheus_exporter sink, and curl 8.4+. Reads VECTOR_METRICS_URL (default http://127.0.0.1:9598/metrics), independently of api.enabled. Returns sorted Prometheus text, bounded to 1 MiB, with floating-point totals. Empty, malformed, duplicate, nonfinite, or oversized counter data fails; a valid zero is retained.

    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. Uses the local binary; needs neither the health API nor the Prometheus exporter.

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