Logging and Diagnostics Leave feedback
On this page
To enable logging, wire a logger through ViewerSettings when you construct the Viewer. GroupDocs.Viewer for Python via .NET ships two loggers out of the box — ConsoleLogger writes trace/warning/error messages to standard output, and FileLogger writes them directly to a log file. Both implement the same ILogger interface.
The logger emits three types of messages:
- Error: for critical exceptions that prevent rendering.
- Warning: for recoverable or expected issues.
- Trace: for general informational messages.
To stream log messages to standard output, construct ViewerSettings with a ConsoleLogger and pass the settings to the Viewer constructor:
from groupdocs.viewer import Viewer, ViewerSettings
from groupdocs.viewer.logging import ConsoleLogger
from groupdocs.viewer.options import HtmlViewOptions
def write_logs_to_console():
# Create viewer settings with a console logger
viewer_settings = ViewerSettings(logger=ConsoleLogger())
# Load DOCX document and render it to HTML
with Viewer("./sample.docx", settings=viewer_settings) as viewer:
html_options = HtmlViewOptions.for_embedded_resources("write_logs_to_console/page_{0}.html")
viewer.view(html_options)
if __name__ == "__main__":
write_logs_to_console()
sample.docx is the sample file used in this example. Click here to download it.
write_logs_to_console/page_1.html (317 KB)
write_logs_to_console/page_2.html (149 KB)
write_logs_to_console/page_3.html (113 KB)
ViewerSettings(logger=ConsoleLogger())bundles a fresh console logger into a settings object. Theloggerkeyword argument is the only construction form —ViewerSettings()with no arguments is not supported.- The
Vieweris constructed withsettings=viewer_settings. The logger is active for the wholewithblock. - As the
viewmethod is called and rendering occurs, trace / warning / error messages are written to standard output.
The Python binding ships a dedicated FileLogger class that writes directly to a log file — no stream redirection required. Pass the target file path to the constructor:
from groupdocs.viewer import Viewer, ViewerSettings
from groupdocs.viewer.logging import FileLogger
from groupdocs.viewer.options import HtmlViewOptions
def write_logs_to_file():
# Create a file logger that writes trace/warning/error messages to log.txt
# and wire it through ViewerSettings
viewer_settings = ViewerSettings(logger=FileLogger("./log.txt"))
# Load DOCX document and render it to HTML
with Viewer("./sample.docx", settings=viewer_settings) as viewer:
html_options = HtmlViewOptions.for_embedded_resources("write_logs_to_file/page_{0}.html")
viewer.view(html_options)
if __name__ == "__main__":
write_logs_to_file()
sample.docx is the sample file used in this example. Click here to download it.
log.txt (484 bytes)
write_logs_to_file/page_1.html (317 KB)
write_logs_to_file/page_2.html (149 KB)
write_logs_to_file/page_3.html (113 KB)
FileLogger("./log.txt")openslog.txtfor writing on first use and appends every trace, warning, and error message to it.- The file logger is passed as the
loggerkeyword argument toViewerSettings, and the settings object is then passed to theViewerconstructor. - All log messages produced during rendering land in
log.txt— no need to redirectsys.stdout.
Use FileLogger when you want structured, per-run log files for long-running services or batch jobs.
If you already have a logging pipeline that consumes sys.stdout, you can redirect ConsoleLogger output there instead. Redirect sys.stdout for the duration of the render call — the logger will write its messages into the file handle:
import sys
from groupdocs.viewer import Viewer, ViewerSettings
from groupdocs.viewer.logging import ConsoleLogger
from groupdocs.viewer.options import HtmlViewOptions
def redirect_logs_to_file():
log_file_path = "./log.txt"
# Redirect standard output to a file so ConsoleLogger writes into it
original_stdout = sys.stdout
with open(log_file_path, "w", encoding="utf-8") as log_file:
sys.stdout = log_file
try:
# Create viewer settings with a console logger — the logger
# writes through sys.stdout, which is currently redirected to log_file.
viewer_settings = ViewerSettings(logger=ConsoleLogger())
# Load DOCX document and render it to HTML
with Viewer("./sample.docx", settings=viewer_settings) as viewer:
html_options = HtmlViewOptions.for_embedded_resources("redirect_logs_to_file/page_{0}.html")
viewer.view(html_options)
finally:
sys.stdout = original_stdout
if __name__ == "__main__":
redirect_logs_to_file()
sample.docx is the sample file used in this example. Click here to download it.
log.txt (0 bytes)
redirect_logs_to_file/page_1.html (317 KB)
redirect_logs_to_file/page_2.html (149 KB)
redirect_logs_to_file/page_3.html (113 KB)
sys.stdoutis redirected tolog.txtso anyprint-style writes (including the ones emitted byConsoleLogger) land in the file.ViewerSettingsis instantiated withloggerset to a freshConsoleLoggerinstance.- A
Viewerobject is created with the configured settings and performs rendering — trace messages are captured in the file instead of the terminal. sys.stdoutis restored in thefinallyblock so subsequentprintcalls continue to go to the terminal.
Prefer FileLogger (Example 2) for new code — it avoids the global sys.stdout mutation. Use the redirection approach only when you need ConsoleLogger output to flow into an existing stdout-based pipeline.
Was this page helpful?
Any additional feedback you'd like to share with us?
Please tell us how we can improve this page.
Thank you for your feedback!
We value your opinion. Your feedback will help us improve our documentation.
