---
title: "HTML to PDF logging diagnostics | Nutrient .NET SDK"
canonical_url: "https://www.nutrient.io/guides/dotnet/conversion/html-to-pdf-logging-diagnostics/"
md_url: "https://www.nutrient.io/guides/dotnet/conversion/html-to-pdf-logging-diagnostics.md"
last_updated: "2026-05-28T01:45:39.246Z"
description: "Learn how to configure diagnostic logging for HTML-to-PDF conversion using Nutrient .NET SDK."
---

# 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`](https://learn.microsoft.com/en-us/dotnet/core/extensions/logging). 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](https://www.nutrient.io/sdk/dotnet/getting-started.md?product=gdpicture&framework=dotnet#importing-nutrient-net-sdk-to-your-application) guide:

```csharp

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:

```csharp

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:

```csharp

// 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](https://www.nutrient.io/guides/dotnet/deployment/headless-modes-google-chrome.md) 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:

```csharp

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:

| Category                                                            | Description                                                    |
| ------------------------------------------------------------------- | -------------------------------------------------------------- |
| `GdPicture.Internal.HTML.HtmlConverter`                             | Conversion orchestration, security mitigations, PDF generation |
| `GdPicture.Internal.HTML.Engines.Process.ChromeOutProcessConverter` | Chrome process lifecycle, DevTools Protocol connection         |

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](https://www.nutrient.io/guides/dotnet/troubleshoot.md) 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](https://www.nutrient.io/guides/dotnet/conversion/html-to-pdf-file-logging-diagnostics.md) guide.
---

## Related pages

- [Convert any image to PDF in C#](/guides/dotnet/conversion/any-image-to-pdf.md)
- [Convert to MS Office from any file in C#](/guides/dotnet/conversion/any-file-to-office.md)
- [Convert DWG or DXF to PDF in C#](/guides/dotnet/conversion/cad-to-pdf.md)
- [Convert bitmap (BMP) to PDF in C#](/guides/dotnet/conversion/bmp-to-pdf.md)
- [Convert emails (MSG/EML) to PDF in C#](/guides/dotnet/conversion/email-to-pdf.md)
- [Embed a font in a Word document](/guides/dotnet/conversion/embed-font-in-word-document.md)
- [Convert Excel to PDF in C#](/guides/dotnet/conversion/excel-to-pdf.md)
- [HTML to PDF file logging diagnostics](/guides/dotnet/conversion/html-to-pdf-file-logging-diagnostics.md)
- [Convert HTML to PDF using C# and .NET](/guides/dotnet/conversion/html-to-pdf.md)
- [Convert HTML to Word in C#](/guides/dotnet/conversion/html-to-word.md)
- [Convert images to PDFs in C#](/guides/dotnet/conversion/image-to-pdf.md)
- [Convert files to PDF in C# .NET](/guides/dotnet/conversion.md)
- [Convert JPG to PDF in C#](/guides/dotnet/conversion/jpg-to-pdf.md)
- [Converting a document from Markdown to PDF format](/guides/dotnet/conversion/markdown-to-pdf.md)
- [Merge and combine multiple files into a PDF in C#](/guides/dotnet/conversion/merge-to-pdf.md)
- [Convert MS Office files to PDFs in C#](/guides/dotnet/conversion/office-to-pdf.md)
- [Convert PDF to bitmap (BMP) in C#](/guides/dotnet/conversion/pdf-to-bmp.md)
- [Convert PDF to Excel in C#](/guides/dotnet/conversion/pdf-to-excel.md)
- [Converting PDF to HTML](/guides/dotnet/conversion/pdf-to-html.md)
- [Convert images to PDFs in C#](/guides/dotnet/conversion/pdf-to-image.md)
- [Convert PDF to JPG in C#](/guides/dotnet/conversion/pdf-to-jpg.md)
- [Converting a document from PDF to Markdown format](/guides/dotnet/conversion/pdf-to-markdown.md)
- [Convert PDF to other images in C#](/guides/dotnet/conversion/pdf-to-other-image.md)
- [Convert PDF to PDF/UA](/guides/dotnet/conversion/pdf-to-pdf-ua.md)
- [Convert PDF to PDF/A](/guides/dotnet/conversion/pdf-to-pdfa.md)
- [Convert PDF to PNG in C#](/guides/dotnet/conversion/pdf-to-png.md)
- [Convert PDF to SVG in C#](/guides/dotnet/conversion/pdf-to-svg.md)
- [Convert PDF to PowerPoint in C#](/guides/dotnet/conversion/pdf-to-powerpoint.md)
- [Convert PDF to TIFF in C#](/guides/dotnet/conversion/pdf-to-tiff.md)
- [Convert PDF to Word in C#](/guides/dotnet/conversion/pdf-to-word.md)
- [Convert PNG to PDF in C#](/guides/dotnet/conversion/png-to-pdf.md)
- [Convert PowerPoint to PDF in C#](/guides/dotnet/conversion/powerpoint-to-pdf.md)
- [Convert RTF to Word in C#](/guides/dotnet/conversion/rtf-to-docx.md)
- [Convert SVG to PDF in C#](/guides/dotnet/conversion/svg-to-pdf.md)
- [Convert RTF to PDF in C#](/guides/dotnet/conversion/rtf-to-pdf.md)
- [Convert text to PDF in C#](/guides/dotnet/conversion/text-to-pdf.md)
- [Convert TIFF to PDF in C#](/guides/dotnet/conversion/tiff-to-pdf.md)
- [Convert to Word, Excel, or PowerPoint in C#](/guides/dotnet/conversion/to-office.md)
- [Converting Word documents with comments to PDF](/guides/dotnet/conversion/word-document-to-pdf-including-comments.md)
- [Converting Word documents to PDF/UA](/guides/dotnet/conversion/word-document-to-pdf-ua.md)
- [Convert Word to PDF in C#](/guides/dotnet/conversion/word-to-pdf.md)