HTML to PDF logging diagnostics

When you convert HTML to PDF, diagnostic logs help you troubleshoot rendering issues, network failures, and security events. Without logs, failures often return generic errors that don’t explain the root cause.

Nutrient .NET SDK integrates with Microsoft.Extensions.Logging(opens in a new tab). You can route SDK diagnostics to any compatible provider, including the console, files, and structured logging backends.

This guide shows how to configure HTML-to-PDF diagnostic logging with console output.

How Nutrient supports diagnostic logging

Nutrient .NET SDK uses Microsoft.Extensions.Logging.ILoggerFactory for HTML-to-PDF diagnostics and emits structured logs at multiple severity levels:

• Trace — Incoming Chrome DevTools Protocol messages as JSON. This produces high-volume output for protocol-level debugging.
• Debug — URL permit/block decisions, frame navigation events, and Chrome process startup details.
• Information — Conversion milestones, such as page load, script injection, security mitigations, and PDF generation.
• Warning — Security events, navigation errors, and timeout warnings.
• Error — Chrome process failures and connection issues.

When you configure an ILoggerFactory and pass it to the SDK, these events are written to your configured output.

Prepare the project

Register the SDK license before you run conversion logic. For setup details, refer to the getting started with .NET SDK guide:

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

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

Configure the logger factory

Create an ILoggerFactory with LoggerFactory.Create(). Then pass it to the SDK with GdPictureLoggerFactory.SetLogger().

Use AddFilter to control category and severity output. GdPicture.Internal.HTML captures HTML-to-PDF diagnostics:

using ILoggerFactory loggerFactory = LoggerFactory.Create(builder =>
{
    builder
        .AddFilter("GdPicture.Internal.HTML", LogLevel.Debug)
        .AddConsole();
});

GdPictureLoggerFactory.SetLogger(loggerFactory);

Use the level that matches your troubleshooting scope:

• LogLevel.Debug — Verbose diagnostics, including URL filtering decisions and frame events.
• LogLevel.Trace — Full protocol messages as JSON (high volume).
• LogLevel.Information — Conversion milestones without protocol-level noise.
• LogLevel.Warning — Security events and errors only.

Set up the web browser engine

For HTML-to-PDF conversion, the SDK uses a Chrome headless engine. FetchLatestChromeHeadlessShell downloads and configures a compatible Chrome headless shell:

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

The SDK downloads the browser once and reuses the cached version on later runs.

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.

Run the conversion with diagnostic output

After you configure logging, run a standard HTML-to-PDF conversion. The SDK writes internal events to the console:

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. Review the log output above for diagnostics.");
}
else
{
    Console.Error.WriteLine($"Conversion failed with status: {status}");
}

A typical conversion writes logs similar to the following output:

dbug: GdPicture.Internal.HTML.Engines.Process.ChromeOutProcessConverter
      Starting Chrome from location '/path/to/chrome' ...
info: GdPicture.Internal.HTML.HtmlConverter
      Timeout in 00:01:00
info: GdPicture.Internal.HTML.HtmlConverter
      Inject pre-init malicious mitigation scripts on tab...
info: GdPicture.Internal.HTML.HtmlConverter
      Loading url https://www.nutrient.io/sdk/dotnet
info: GdPicture.Internal.HTML.HtmlConverter
      Url loaded
info: GdPicture.Internal.HTML.HtmlConverter
      Removing potential malicious nodes from DOM (including Shadow DOM)...
info: GdPicture.Internal.HTML.HtmlConverter
      Starting conversion to PDF...
info: GdPicture.Internal.HTML.HtmlConverter
      Conversion to PDF done

If you set LogLevel.Trace, the SDK also writes raw Chrome DevTools Protocol messages, for example:

trce: GdPicture.Internal.HTML.HtmlConverter
      Incoming Chrome DevTool Protocol message:
      {"method":"Page.lifecycleEvent","params":{"name":"DOMContentLoaded","frameId":"..."}}
trce: GdPicture.Internal.HTML.HtmlConverter
      Incoming Chrome DevTool Protocol message:
      {"method":"Fetch.requestPaused","params":{"requestId":"...","request":{"url":"https://..."}}}

Use Trace only when needed because it generates substantial output.

Available log categories

The SDK emits logs under these categories:

Use GdPicture.Internal.HTML to capture all HTML-to-PDF categories, or target individual categories for focused diagnostics.

Handle errors

GdPictureDocumentConverter.SaveAsPDF returns a GdPictureStatus value. When conversion fails, diagnostic logs supply context the status code alone can’t, such as blocked URLs, Chrome startup failures, or where in the page lifecycle a timeout occurred.

For status code handling details, refer to the handling errors with .NET SDK guide.

Conclusion

Console-based diagnostic logging gives you immediate visibility into the HTML-to-PDF conversion pipeline during development. Connect Microsoft.Extensions.Logging to the SDK to surface every security decision and conversion milestone directly in the terminal. To persist diagnostics to files for later analysis, refer to the HTML-to-PDF file logging diagnostics guide.