Skip to content

DOCS-4140: Clarify where logs are #4444

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

DOCS-4140: Clarify where logs are #4444

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
650b792
DOCS-4140: Clarify where logs are
npentrel Jul 3, 2025
66f5f70
Apply suggestions from code review
npentrel Jul 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/manage/troubleshoot/troubleshoot.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,9 @@ If not follow the steps for the standalone version.
{{< tabs >}}
{{% tab name="Linux" %}}

By default, `viam-server` writes logs to STDOUT and does not store them in a file on your machine.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking at the broader context, I see where in a section where the viam-server is running as a standalone (not started via the viam-agent). I don't have a big opinion regarding this, but historically there was a third option for how the viam-server is run.

The classic installation script would have systemctl (on linux) manage the viam-server. Which would write logs to a file that journalctl could conjure.

Again, given I don't think we surface that installation script any more, this information is accurate for when the viam-server is run by hand.

If you want to store your logs in a file, stop the running `viam-server` instance, and restart it with the `-logfile` option.

1. First check where the `viam-server` binary is and where the machine cloud credentials file for your machine is:

```sh {class="command-line" data-prompt="$" data-output="2"}
Expand All @@ -89,6 +92,9 @@ If not follow the steps for the standalone version.
{{% /tab %}}
{{% tab name="macOS" %}}

`viam-server` writes logs to STDOUT and does not store them in a file on your machine.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Linux instruction makes sense but for the mac one, maybe clarify where STDOUT goes by default so there's more of a distinction between default behavior versus what -debug does?

To view your logs, stop the running `viam-server` instance, and restart it with the `-debug` option which will sent the logs to STDOUT in the current terminal window.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't have a mac on hand to sanity check this, but this sounds wrong. I wouldn't expect the instructions for linux and mac to differ (especially if we no longer have the systemctl installation script for linux -- which complicates the story).

I expect that the -debug flag only writes more* output to stdout. For example, the following should only appear when using -debug:

2025-07-07T13:34:23.450Z	DEBUG	rdk.ftdc	ftdc/ftdc.go:182	Added statser	{"name":"proc.viam-server","type":"*sys.UsageStatser"}

The -logFile argument on mac should similarly write logs to a file if that behavior is desired.


1. Kill the running `viam-server` instance.
2. Then run `viam-server` with the `-debug` option and pass in your machine cloud credentials file:

Expand Down
Loading