Diagnostics for content that extraction drops without failing.
Extraction can omit content and still return {:ok, text}. Enable capture
to forward diagnostic records to Elixir's Logger and help explain missing
content.
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)
:okRecords 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
Capture is global to the VM, not per document or per process: it affects
every document handle in it. 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.
Structured warnings
Some tolerated conditions are recorded as PdfElixide.Warning.t/0
values, independently of capture and without explicit enablement.
PdfElixide.Document.structured_warnings/1 lists per-document warnings;
structured_warnings/0 and take_structured_warnings/0 read the process-wide
feed. Which feed a warning reaches depends on the call that raised it; see
"Which feed a warning reaches" in PdfElixide.Warning.
Under concurrent use an entry may come from any handle in the VM; see the Concurrency guide.
Summary
Functions
Returns whether capture is currently enabled.
Sets the capture level, returning :ok.
Lists the warnings recorded process-wide, oldest first, without emptying the list.
Returns the warnings recorded process-wide, oldest first, and empties the list.
Types
Functions
@spec enabled?() :: boolean()
Returns whether capture is currently enabled.
@spec flush() :: non_neg_integer()
Forwards every captured record to Logger and empties the buffer.
Library calls that capture records automatically attempt to forward them, including when a call raises. Returns the number of records forwarded.
Records reach Logger without the calling process's own metadata; see
"Attribution" in the module documentation.
@spec set_level(level()) :: :ok
Sets the capture level, returning :ok.
Raises ArgumentError unless level is one of [:off, :error, :warning, :info, :debug, :trace].
Setting :off also discards any records captured but not yet forwarded.
@spec structured_warnings() :: [PdfElixide.Warning.t()]
Lists the warnings recorded process-wide, oldest first, without emptying the list.
See PdfElixide.Warning for which conditions are recorded and which feed
each one reaches.
@spec take_structured_warnings() :: [PdfElixide.Warning.t()]
Returns the warnings recorded process-wide, oldest first, and empties the list.
The list is bounded and discards the oldest entries when full. If it
overflowed since it was last emptied, a single Logger warning
reports how many entries were discarded, so a truncated list cannot be
mistaken for a complete one.