Diagnostics for content that extraction drops without failing.

Most damaged pages do not produce an error. A content stream that will not decode, a font that fails to load, a Form XObject that cannot be processed and a character with no usable mapping are all handled by continuing with less content, so PdfElixide.Document.text/1 returns {:ok, text} with material missing and no way to tell that page from a blank one. Each of those is reported internally as a log record. Enable capture and the records reach Elixir's Logger, naming the page and the reason.

This is off by default and is a diagnostic aid, not an error channel — a captured record does not change what a call returns, and neither does a failure to forward one, which is reported at :error level and nothing more. Errors still arrive as PdfElixide.Error.t/0; see PdfElixide.Document.text_opts/0 for what :on_page_error can and cannot catch.

Enabling

iex> PdfElixide.Logging.set_level(:warning)
:ok

Records are then forwarded to Logger at the matching level, tagged with pdf_elixide: true and the originating module in :pdf_source metadata. Turn it back off with set_level(:off), which also discards anything captured but not yet forwarded.

To capture at startup, set it in your application's start/2 before opening any document.

Attribution

Under concurrent use, a record may be forwarded by a process other than the one whose work produced it. Forwarded records therefore omit that process's Logger metadata. Use :pdf_source, the message and the timestamp instead; the :pid added by Logger identifies only the forwarding process.

Cost, and why it is off by default

Capture is process-global, not per-document or per-process: it affects every document handle in the VM. Records are buffered as they are produced and forwarded when the next call returns, so a level of :debug or :trace on a large document produces a great deal of output and measurably slows extraction. :warning is the level that reports dropped content.

The buffer is bounded. If it fills before anything drains it — capture enabled but no further calls made — the oldest records are discarded, and a single warning reports how many were lost so a truncated capture cannot be mistaken for a complete one.