The Vector Observability API

Vector ships with a gRPC API that allows you to interact with a running Vector instance. This page covers how to configure and enable Vector’s API.

Configuration

api

optional object
API options.

Warning

The API currently does not support authentication. Only enable it in isolated environments or for debugging. It must not be exposed to untrusted clients.

api.address

common optional string
The network address to which the API should bind. If you’re running Vector in a Docker container, bind to 0.0.0.0. Otherwise the API will not be exposed outside the container.
Examples 
"0.0.0.0:8686"
"127.0.0.1:1234"
default: 127.0.0.1:8686

api.enabled

common optional bool
Whether the API is enabled for this Vector instance.
default: false

Endpoints

GET /health

HTTP healthcheck endpoint served on the same port as the gRPC API, preserved for compatibility with Vector 0.54.0 and earlier so existing HTTP probes (for example AWS ALB and Kubernetes HTTP probes) keep working unchanged. The response body is {"ok": true} while Vector is serving and {"ok": false} once Vector begins draining.

Responses

Code
Description
200
Vector is initialized and running.
503
Vector is draining or shutting down and should be removed from the load balancer.

HEAD /health

Same semantics as GET /health but returns no body. Intended for load balancer probes that prefer HEAD.

Responses

Code
Description
200
Vector is initialized and running.
503
Vector is draining or shutting down and should be removed from the load balancer.

How it works

The API exposes a gRPC service defined in proto/vector/observability.proto. You can interact with it using any standard gRPC tooling.

For compatibility with Vector 0.54.0 and earlier, the HTTP GET /health endpoint continues to be served on the same port as the gRPC API, so existing HTTP probes (for example AWS ALB health checks and Kubernetes HTTP liveness/readiness probes) keep working without changes. See the Endpoints section above for details.

Example using grpcurl 

# Check health (standard gRPC health check, compatible with Kubernetes gRPC probes)
grpcurl -plaintext localhost:8686 grpc.health.v1.Health/Check

# List components
grpcurl -plaintext localhost:8686 vector.observability.v1.ObservabilityService/GetComponents

# Stream events (tap)
grpcurl -plaintext \
  -d '{"outputs_patterns": ["*"], "limit": 100, "interval_ms": 500}' \
  localhost:8686 vector.observability.v1.ObservabilityService/StreamOutputEvents

Example using curl (HTTP health) 

# 200 with body {"ok":true} while serving, 503 {"ok":false} during drain
curl -i http://localhost:8686/health
Sidebar