When something is wrong with a live app, you need two things fast: what it is saying, and how it is behaving. The logs and the metrics. On raw Kubernetes, getting reliable access to both usually means standing up an entire monitoring stack first, which is a real project with its own learning curve. Burrow gives you both as one command addons that run on the nodes you already pay for, so you can go from "no visibility" to "reading the logs" in a minute. This guide shows you how.
Start with the logs you already have
Before any addon, you can read what your app is printing right now:
burrow app logs web
That pulls the recent output straight from your running app. For a lot of debugging, this is all you need: deploy, something looks off, read the last lines, spot the missing config value or the stack trace. When you want fewer or more lines, pass a tail count. This works out of the box, with nothing installed.
The limit is history and reach. Reading straight from the running app gives you recent lines from what is running now. To search across time, keep logs when a process restarts, and query them properly, you want them aggregated somewhere. That is the logs addon.
Install centralized logging in one command
burrow addon install logs
This stands up log aggregation on your cluster (Burrow uses VictoriaLogs for this) and starts collecting your apps' output into one searchable place. Nothing to configure, no pipeline to design. It runs on your own nodes, so it adds capability without adding a separate bill.
Once it is collecting, you query it:
burrow addon logs 'error'
That searches your aggregated logs for lines mentioning error. The query language is expressive when you need it and forgiving when you do not: an empty query matches everything, and you narrow from there. Now "show me every error from the last hour, across restarts" is a query, not an archaeology project.
If you already run your own logging, say Loki, you do not have to throw it away and install ours. Burrow can connect to a backend you already have and query it through the same commands, so your agent gets access to the logs you already keep. The same is true on the metrics side: if you already run Prometheus, you can point Burrow at it instead of installing a second collector. Either way the commands you and your agent run do not change; only what sits behind them does. That is the no lock in version of observability: bring what you have, or install the addon, and the surface stays the same.
A few queries worth knowing
You do not need to master the query language to get value, but a handful of shapes cover most of what you actually reach for. Start broad and narrow down. An empty query shows you everything recent, which is the right first move when you have no idea what is going on and just want to see the stream. From there you filter to a word that matters, error, timeout, panic, the name of a failing endpoint, and the noise drops away.
The rhythm in practice is: look at everything, spot a word that keeps showing up in the bad lines, filter to it, and read what surrounds it. Most debugging sessions are some version of that loop, and having the logs in one searchable place is what makes the loop fast instead of a scavenger hunt across restarts and machines.
Add metrics to see how it is behaving
Logs tell you what happened. Metrics tell you how the app is doing: CPU, memory, traffic, the shape of its load over time. Install the metrics addon the same way:
burrow addon install metrics
This installs a metrics collector on your cluster (VictoriaMetrics) that watches your apps' resource use and traffic. Again, one command, running on your nodes, nothing to wire up by hand.
You query metrics with an instant query:
burrow addon metrics 'sum(rate(http_requests_total[5m]))'
That is a standard PromQL query, the same query language the wider ecosystem uses, so if you have written these before, they work here, and if you have not, your agent can. The point is not that you memorize query syntax. The point is that the data is there and reachable the moment you install the addon.
Logs tell you what, metrics tell you how much
It helps to hold the two apart, because they answer different questions and you reach for them at different moments. Logs are events: this request failed, this job ran, this error was thrown, each with a timestamp and a message. They are what you read when you want to know what happened and why. Metrics are numbers over time: how much CPU, how much memory, how many requests per second, how many of them errored. They are what you read when you want to know how much and whether it is trending the wrong way.
A typical investigation uses both in sequence. The metrics tell you something is off, a spike in memory, a climb in error rate, a jump in latency, and roughly when it started. Then the logs from that window tell you what actually happened to cause it. Metrics point you at the moment, logs explain the moment. Having both installed means you can go from "something feels wrong" to "here is the specific thing" without ever leaving the command line.
Getting your app's own numbers scraped
Resource metrics like CPU and memory come for free once the collector is watching. If you also want your app's own application metrics picked up, tell Burrow which port they are on when you deploy:
burrow app deploy web --image ghcr.io/you/web:1.5.0 --metrics-port 9090
That marks the app so the metrics collector scrapes your metrics endpoint on that port. Now your custom counters and timings flow into the same place as everything else, queryable the same way.
A nice bonus: your database watches itself
If you have attached a Postgres database to your app, installing the metrics addon gives you database health for free. Postgres exports its own metrics, so once the collector is running, your database is scraped automatically: connection and transaction health, plus slow query statistics. Install the two addons in either order, it does not matter which comes first.
This closes a common blind spot. When a page feels slow, "is it the app or the database?" is usually a guess. With both addons in place, it is a question you can answer from data. That is exactly the kind of thing your agent can now do for you instead of shrugging.
Why this matters for operating through an agent
Here is the part that ties it together. An AI coding agent is great at writing your app and often goes blind the moment the code leaves the editor, because it cannot see what the running app is doing. Give it access to logs and metrics and that changes completely.
Ask your agent "why is my app throwing errors?" and, with the logs addon in place, it reads what actually happened instead of theorizing. Chasing a stubborn bug? It can add logging to your code, redeploy, and read the new lines back. Ask "why is my site slow?" and, with metrics in place, it looks at the actual CPU, memory, and traffic and points at the bottleneck, or fixes it.
All of this runs through the same read commands you use: burrow app logs, burrow addon logs, burrow addon metrics. Your agent is not getting a secret backchannel, it is reading the same data you can read, which means you can always check its work.
From guessing to knowing
The shift here is bigger than convenience. An agent without visibility is reduced to reasoning about your app from the code alone, which is a bit like a doctor diagnosing over the phone. It can make educated guesses, but it cannot see the patient. Give it logs and metrics and it can look. The quality of what it tells you changes accordingly: "this might be a database issue" becomes "the database is fine, but this endpoint is throwing on every request with this exact error, and here is the line."
That is the difference between an agent that theorizes and an agent that diagnoses. And because the visibility is just addons on your own cluster, you are not paying a separate vendor for the privilege, and the data never leaves your infrastructure. It sits on the nodes you already run, readable by you and by the agent you already trust.
Reading straight from the running app, or from history
One last distinction that trips people up. There are two ways to read logs here, and they are good at different things. Reading straight from the running app with burrow app logs web shows you what is happening right now, on what is running now, with nothing installed. It is perfect for a quick look during a deploy or a live issue.
Querying the logs addon with burrow addon logs shows you history: lines from before the latest restart, lines from across time, searchable. It is what you want when the interesting event already happened and you need to go back and find it. Keep both in your toolkit. The live view for what is happening, the addon for what happened.
A worked example: chasing a slow endpoint
To make the loop concrete, here is how a real "the site feels slow" investigation runs from the command line. Start with the metrics, because they tell you whether something is actually wrong and roughly when it started. Look at request rate and error rate first:
burrow addon metrics 'sum(rate(http_requests_total[5m]))'
burrow addon metrics 'sum(rate(http_requests_total{status=~"5.."}[5m]))'
Say the second one is climbing: errors are up. Now you want to know how much and on what. Check the app's resource use to rule the obvious causes in or out:
burrow addon metrics 'sum(rate(container_cpu_usage_seconds_total{pod=~"web.*"}[5m]))'
If CPU is flat but errors are up, it is probably not load, it is something in the code path. So you pivot to the logs for the same window and filter to the noise:
burrow app logs web
burrow addon logs 'error'
The live view shows you what the app is saying right now; the addon query shows you the errors across the recent past, including from before the latest restart. Filter down to the word that keeps appearing in the bad lines, read what surrounds it, and you have gone from "the site feels slow" to "this endpoint throws on every request with this exact error, on this line." Metrics pointed you at the moment, the logs explained it. That is the whole loop, and it is fast because the data is one command away instead of a stack you have to build first.
The same data, from the agent's side
When your agent is the one looking, it reaches the same data through its own JSON first commands: burrow-agent logs-query for a log search and burrow-agent metrics-query for a metrics query. The results come back as structured JSON so the agent can compose them into an answer, but it is reading exactly what you read with burrow addon logs and burrow addon metrics. There is no separate feed and no hidden access. That symmetry is the point: you can always run the same query the agent ran and check its work against the same numbers.
What can go wrong, and how it is handled
A handful of gotchas are worth knowing so they do not trip you up.
Querying before you install returns nothing useful. burrow addon logs and burrow addon metrics read from the addons. If you have not installed them yet, there is nothing aggregated to search. Reading straight from the running app with burrow app logs web always works with nothing installed; the addon queries need the addon.
An empty query is a feature, not a mistake. An empty log query matches everything recent. That is the right first move when you have no idea what is going on and just want to see the stream, then you narrow from there. Do not overthink the query language; start broad and filter.
History has a horizon. The logs addon keeps what it has collected on your cluster, on your own disk. It is not infinite. For a live issue it is exactly right; for something from long ago, remember you are querying retained history, not all of time.
Custom app metrics need the app to actually expose them. Resource metrics like CPU and memory come for free once the collector is watching. Your own application counters only show up if your app serves a metrics endpoint and you told Burrow which port it is on at deploy time. If a custom metric is missing, check that the app is exposing it on the port you named.
Metrics are numbers, logs are events, and they answer different questions. If you find yourself asking "what happened," you want logs. If you are asking "how much, and is it trending the wrong way," you want metrics. Reaching for the wrong one is the most common way a debugging session stalls.
The whole visibility setup, start to finish
burrow app logs web # recent output, no addon needed
burrow addon install logs # aggregate and search logs
burrow addon logs 'error' # query them
burrow addon install metrics # collect CPU, memory, traffic
burrow addon metrics 'up' # query them
Two commands stand up the visibility that usually takes a weekend to assemble, and they run on infrastructure you already own. The goal is that "how is my app doing?" always has a real answer close at hand, whether you are the one asking or your agent is answering. Visibility should be the easy part, not the project you keep meaning to get to.