HTML to PDF file logging diagnostics

Console logging often falls short in production when you need to diagnose HTML-to-PDF conversion issues. File-based logging solves that problem because logs persist after restarts, support post-mortem analysis, and keep standard output clean.

This guide builds on the concepts introduced in the HTML-to-PDF console logging diagnostics guide and extends the configuration with a file logging provider. It covers:

• File output configuration
• Rolling file rotation
• Dual-sink logging to both console and file

For a complete reference of log severity levels and log categories emitted by the SDK, refer to the console logging diagnostics guide.

Choose a file logging provider

Microsoft.Extensions.Logging doesn’t include a built-in file provider. This guide uses NReco.Logging.File nreco(opens in a new tab), which integrates with LoggerFactory.Create().

Prepare the project

Initialize the SDK and import NReco.Logging.File with the standard logging abstractions:

using GdPicture14;
using GdPicture.Internal.Globals;
using Microsoft.Extensions.Logging;
using NReco.Logging.File;

LicenseManager licence = new LicenseManager();
licence.RegisterKEY("");

Configure file and console logging

Create an ILoggerFactory with:

• .AddConsole() for immediate terminal output
• .AddFile() for persisted diagnostics

AddFile() takes a file path and a callback for rotation settings:

using ILoggerFactory loggerFactory = LoggerFactory.Create(builder =>
{
    builder
        .AddFilter("GdPicture.Internal.HTML", LogLevel.Debug)
        .AddConsole()
        .AddFile("html-conversion.log", fileLoggerOpts =>
        {
            fileLoggerOpts.Append = false;
            fileLoggerOpts.FileSizeLimitBytes = 10 * 1024 * 1024;  // 10 MB per file
            fileLoggerOpts.MaxRollingFiles = 3;
        });
});

GdPictureLoggerFactory.SetLogger(loggerFactory);

File rotation options

• Append
  • Set to false to create a fresh log file on each run.
  • Set to true to keep adding logs across runs.
• FileSizeLimitBytes
  • Defines the maximum file size before rotation.
  • When the file reaches the limit, the provider renames it (for example, html-conversion.log to html-conversion.1.log) and creates a new file.
• MaxRollingFiles
  • Defines how many rotated files the provider keeps.
  • Older files are deleted to prevent unbounded disk use.

If you need full protocol output for troubleshooting, set the filter to LogLevel.Trace. This produces high log volume, so increase FileSizeLimitBytes or MaxRollingFiles as needed.

Set up the web browser engine and run the conversion

// Uncomment the code below to fetch a chrome headless shell instance, instead of using the local chromium
// GdPictureDocumentUtilities.SetWebBrowserPath(
//     GdPictureDocumentUtilities.FetchLatestChromeHeadlessShell(Environment.CurrentDirectory));

If you run HTML conversion inside Docker on Linux, make sure the container is configured for Chrome-based rendering first. Refer to the running Chrome-based conversions in Docker guide.

With file logging configured, all internal SDK events are written to both the console and html-conversion.log:

using GdPictureDocumentConverter converter = new GdPictureDocumentConverter();
converter.LoadFromHttp(new Uri("https://www.nutrient.io/sdk/dotnet"));
GdPictureStatus status = converter.SaveAsPDF("output.pdf");

if (status == GdPictureStatus.OK)
{
    Console.WriteLine("Conversion completed. Diagnostic logs written to html-conversion.log");
}
else
{
    Console.Error.WriteLine($"Conversion failed with status: {status}. Check html-conversion.log for details.");
}

Review the log file

After conversion completes, html-conversion.log contains the diagnostic trace. The file persists after the app exits, so you can review or share it later. The format matches console output:

info: GdPicture.Internal.HTML.HtmlConverter[0]
      Loading url https://www.nutrient.io/sdk/dotnet
info: GdPicture.Internal.HTML.HtmlConverter[0]
      Url loaded
info: GdPicture.Internal.HTML.HtmlConverter[0]
      Starting conversion to PDF...

Handle errors

When conversion fails, the log file gives you a full event timeline leading to the failure. This helps with intermittent issues that are hard to reproduce. For details on GdPictureStatus return codes, refer to the handling errors with .NET SDK guide.

Conclusion

File-based logging supports production troubleshooting without changing application behavior or requiring an active terminal session. Rolling file rotation prevents unbounded disk usage, and dual-sink configurations give you both immediate console feedback and persistent file records. For an introduction to HTML-to-PDF diagnostic logging and the full reference of severity levels and log categories, refer to the console logging diagnostics guide.