docs(developing): add a proper Logging guide (#881) by Anai-Guo · Pull Request #898 · vllm-project/guidellm

Anai-Guo · 2026-07-05T21:51:06Z

Summary

docs/guides/troubleshooting.md (Debug Logging) links to developer/developing.md#logging for the full logging guide, but that anchor pointed at a bare list of environment variables nested under Developing the Web UI — not the standalone guide the link implies. Fixes #881.

Changes

Promote ### Logging to a top-level ## Logging section, keeping the #logging anchor that the two troubleshooting links depend on.
Add an overview of GuideLLM's two logging sinks:
- Console — human-readable output to stdout, controlled by GUIDELLM__LOGGING__CONSOLE_LOG_LEVEL (default WARNING).
- File — structured JSON, enabled by GUIDELLM__LOGGING__LOG_FILE / GUIDELLM__LOGGING__LOG_FILE_LEVEL (default file guidellm.log, default level INFO).
List all GUIDELLM__LOGGING__* variables with defaults taken from LoggingSettings in src/guidellm/settings.py and the sink behavior in src/guidellm/logger.py.
Add console and file logging usage examples.

Docs-only; no code changes.

🤖 Generated with Claude Code

git log

commit 66cf2fe
Author: Anai-Guo antai12232931@anaiguo.com
Date: Sun Jul 5 14:50:52 2026 -0700

docs(developing): add a proper Logging guide

The Debug Logging section in docs/guides/troubleshooting.md links to
developer/developing.md#logging for the full logging guide, but the
existing content was a single env-var list nested under 'Developing the
Web UI' rather than a standalone guide.

Promote it to a top-level '## Logging' section (keeping the #logging
anchor the troubleshooting links rely on) and expand it into an actual
guide: an overview of the two logging sinks (human-readable console
output on stdout and structured-JSON file output), the full set of
GUIDELLM__LOGGING__* environment variables with accurate defaults from
LoggingSettings, and console/file usage examples.

Closes #881

Signed-off-by: Anai-Guo <antai12232931@anaiguo.com>

commit f6170d5
Author: Tai An antai12232931@outlook.com
Date: Mon Jul 6 19:09:14 2026 +0000

docs(developing): simplify Logging section per review (drop package name, consolidate, guidellm env)

Signed-off-by: Tai An <antai12232931@outlook.com>

Signed-off-by: Anai-Guo antai12232931@anaiguo.com
Signed-off-by: Tai An antai12232931@outlook.com

The Debug Logging section in docs/guides/troubleshooting.md links to developer/developing.md#logging for the full logging guide, but the existing content was a single env-var list nested under 'Developing the Web UI' rather than a standalone guide. Promote it to a top-level '## Logging' section (keeping the #logging anchor the troubleshooting links rely on) and expand it into an actual guide: an overview of the two logging sinks (human-readable console output on stdout and structured-JSON file output), the full set of GUIDELLM__LOGGING__* environment variables with accurate defaults from LoggingSettings, and console/file usage examples. Closes vllm-project#881 Signed-off-by: Anai-Guo <antai12232931@anaiguo.com>

jaredoconnell

I think this is close to ready. I have one comment.

jaredoconnell · 2026-07-06T15:53:49Z

+## Logging

-Logging is useful for learning how GuideLLM works and finding problems.
+GuideLLM uses [Loguru](https://github.com/Delgan/loguru) for logging, which is useful for learning how GuideLLM works and for diagnosing problems. Logging is configured entirely through environment variables (or the equivalent `GUIDELLM__LOGGING__*` settings), so no code changes are needed to change what is logged or where it goes.


This seems a little confusing the way you mention the settings.

Suggested change

GuideLLM uses [Loguru](https://github.com/Delgan/loguru) for logging, which is useful for learning how GuideLLM works and for diagnosing problems. Logging is configured entirely through environment variables (or the equivalent `GUIDELLM__LOGGING__*` settings), so no code changes are needed to change what is logged or where it goes.

GuideLLM uses [Loguru](https://github.com/Delgan/loguru) for logging, which is useful for learning how GuideLLM works and for diagnosing problems. For CLI usage, logging is configured through environment variables (or a .env file using the same GUIDELLM__LOGGING__* keys), so no code changes are needed to change what is logged or where it goes.

SkiHatDuckie

Also seems mostly good to me. In addition to Jared's suggestion:

SkiHatDuckie · 2026-07-06T16:05:20Z

+GUIDELLM__LOGGING__LOG_FILE=guidellm.log GUIDELLM__LOGGING__LOG_FILE_LEVEL=DEBUG guidellm run ...
+```
+
+If logging isn't responding to the environment variables, run the `guidellm config` command to validate that the environment variables match and are being set correctly.


Suggested change

If logging isn't responding to the environment variables, run the `guidellm config` command to validate that the environment variables match and are being set correctly.

If logging isn't responding to the environment variables, run the `guidellm env` command to validate that the environment variables match and are being set correctly.

config has been renamed to env as of v0.7.0. Might as well update that too.

…ame, consolidate, guidellm env) Signed-off-by: Tai An <antai12232931@outlook.com>

Anai-Guo · 2026-07-06T19:09:25Z

Thanks all for the review. Addressed the feedback:

@dbutenhof: dropped the Loguru package name, restored a non-"sink" heading ("configured as two independent outputs"), and consolidated the console/file bullets with the variable list below so the levels/defaults live in one place only.
@SkiHatDuckie: updated the troubleshooting line to guidellm env (renamed from config in v0.7.0).
@jaredoconnell: reworded the intro to remove the confusing settings phrasing.

Let me know if the consolidation went too far or if you'd like the defaults restated inline.

mergify · 2026-07-06T19:09:51Z

Hi @Anai-Guo, the DCO check has failed. Please click on DCO in the Checks section for instructions on how to resolve this.

dbutenhof · 2026-07-06T19:47:10Z

 ## Logging

-GuideLLM uses [Loguru](https://github.com/Delgan/loguru) for logging, which is useful for learning how GuideLLM works and for diagnosing problems. Logging is configured entirely through environment variables (or the equivalent `GUIDELLM__LOGGING__*` settings), so no code changes are needed to change what is logged or where it goes.
+Logging is controlled entirely through the `GUIDELLM__LOGGING__*` environment variables (or the equivalent settings object), so no code changes are needed to change what is logged or where it goes.


The "settings object" is a singleton that's only influenced by its default values and the environment variables. It's not a parameter anywhere, so the parenthetical statement isn't meaningful.

Now, as this is a "Developer" guide, perhaps you're trying to point out details of the implementation... but this document is focused more on tools and external controls, not source details. I think we should just remove the parenthetical statement.

dbutenhof · 2026-07-06T19:48:01Z

+Logging is controlled entirely through the `GUIDELLM__LOGGING__*` environment variables (or the equivalent settings object), so no code changes are needed to change what is logged or where it goes.

-GuideLLM writes to two independent sinks:
+Logging is set through two independent outputs:


Maybe, "GuideLLM can log to the console, to a file, or to both:"

Anai-Guo · 2026-07-06T22:16:20Z

Fixed the DCO check (the follow-up commit was missing a sign-off).

Heads-up on the merge conflict: main has since rewritten the same ### Logging block (and the install section), so GitHub flags this branch as conflicting. I tried to rebase onto the current main, but the interim upstream changes touch .github/workflows/build-multiarch-container.yml, which my token can't push without workflow scope — so I can't cleanly move the branch myself.

Happy to redo this however is easiest for you: I can re-open a fresh branch with just the Logging edits layered on top of the current main, or you can squash-merge and take this version of the section. Let me know which you'd prefer.

jaredoconnell reviewed Jul 6, 2026

View reviewed changes

SkiHatDuckie suggested changes Jul 6, 2026

View reviewed changes

dbutenhof reviewed Jul 6, 2026

View reviewed changes

Comment thread DEVELOPING.md Outdated

Comment thread DEVELOPING.md Outdated

Comment thread DEVELOPING.md Outdated

docs(developing): simplify Logging section per review (drop package n…

f6170d5

…ame, consolidate, guidellm env) Signed-off-by: Tai An <antai12232931@outlook.com>

dbutenhof reviewed Jul 6, 2026

View reviewed changes

Anai-Guo force-pushed the docs/logging-guide-881 branch from ff21b62 to f6170d5 Compare July 6, 2026 22:15

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(developing): add a proper Logging guide (#881)#898

docs(developing): add a proper Logging guide (#881)#898
Anai-Guo wants to merge 2 commits into
vllm-project:mainfrom
Anai-Guo:docs/logging-guide-881

Anai-Guo commented Jul 5, 2026 •

edited by github-actions Bot

Loading

Uh oh!

jaredoconnell left a comment

Uh oh!

jaredoconnell Jul 6, 2026

Uh oh!

SkiHatDuckie left a comment

Uh oh!

SkiHatDuckie Jul 6, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Anai-Guo commented Jul 6, 2026

Uh oh!

mergify Bot commented Jul 6, 2026

Uh oh!

dbutenhof Jul 6, 2026

Uh oh!

dbutenhof Jul 6, 2026

Uh oh!

Anai-Guo commented Jul 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	GuideLLM uses [Loguru](https://github.com/Delgan/loguru) for logging, which is useful for learning how GuideLLM works and for diagnosing problems. Logging is configured entirely through environment variables (or the equivalent `GUIDELLM__LOGGING__*` settings), so no code changes are needed to change what is logged or where it goes.
	GuideLLM uses [Loguru](https://github.com/Delgan/loguru) for logging, which is useful for learning how GuideLLM works and for diagnosing problems. For CLI usage, logging is configured through environment variables (or a .env file using the same GUIDELLM__LOGGING__* keys), so no code changes are needed to change what is logged or where it goes.

	If logging isn't responding to the environment variables, run the `guidellm config` command to validate that the environment variables match and are being set correctly.
	If logging isn't responding to the environment variables, run the `guidellm env` command to validate that the environment variables match and are being set correctly.

Uh oh!

Conversation

Anai-Guo commented Jul 5, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

git log

Uh oh!

jaredoconnell left a comment

Choose a reason for hiding this comment

Uh oh!

jaredoconnell Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

SkiHatDuckie left a comment

Choose a reason for hiding this comment

Uh oh!

SkiHatDuckie Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Anai-Guo commented Jul 6, 2026

Uh oh!

mergify Bot commented Jul 6, 2026

Uh oh!

dbutenhof Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

dbutenhof Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

Anai-Guo commented Jul 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Anai-Guo commented Jul 5, 2026 •

edited by github-actions Bot

Loading