A guide to debugging and troubleshooting Vector

type: guide domain: operations

This guide covers troubleshooting Vector. The sections are intended to be followed in order. If you’d like to troubleshoot by inspecting events flowing through your pipeline, please check out the Vector tap guide.

First, we’re sorry to hear that you’re having trouble with Vector! Reliability and operator friendliness are very important to us, and we urge you to open an issue to let us know what’s going on. This helps us improve Vector.

1. Check for any known issues

Start by searching Vector’s issues. You can filter to the specific component via the label filter.

2. Check Vector’s logs

We’ve taken great care to ensure that Vector’s logs are high quality and helpful. In most cases the logs will surface the issue:

Tail logs:

tail -f /usr/local/var/log/vector.log

Tail logs:

tail -f /var/log/vector.log

If you aren’t using a service manager and you’re redirecting Vector’s output to a file, you can use a utility like tail to access your logs:

tail /var/log/vector.log

Tail logs:

sudo journalctl -fu vector

3. Enable backtraces

You can skip to the next section if you don’t have an exception in your logs.

If you see an exception in Vector’s logs then we’ve clearly found the issue. Before you report a bug, please enable backtraces:

RUST_BACKTRACE=full vector --config=/etc/vector/vector.yaml

Backtraces are critical for debugging errors. Once you have the backtrace please open a bug report issue.

4. Enable debug logging

If you don’t see an error in your Vector logs and the Vector logs appear to be frozen, then you’ll want to drop your log level to debug:

Vector rate limits logs in the hot path. As a result, dropping to the debug level is safe for production environments.
VECTOR_LOG=debug vector --config=/etc/vector/vector.yaml
vector --verbose --config=/etc/vector/vector.yaml

5. Get help

At this point, we recommend reaching out to the community for help.

  1. If you’ve encountered a bug, please file a bug report

  2. If you’ve identified a missing feature, please file a feature request.

  3. If you need help, join our chat community. You can post a question and search previous questions.