Logging System¶

pcapkit.utilities.logging owns pcapkit’s logger hierarchy, rooted at logger, and the API through which an application decides what, if anything, pcapkit emits.

pcapkit.utilities.logging.logger¶

Logger instance named after pcapkit, at the root of the package’s logger hierarchy. Per-module loggers are its children, so configuring this one configures all of pcapkit.

Type:: logging.Logger

The Logger Hierarchy¶

pcapkit is the root. Each module logs through a child logger named after the module, obtained from get_logger(), so any subtree can be addressed on its own:

import logging

# quieten the registry's bookkeeping, keep everything else
logging.getLogger('pcapkit.foundation.registry').setLevel(logging.WARNING)

# or follow just the extraction path
logging.getLogger('pcapkit.foundation.extraction').setLevel(logging.DEBUG)

Logger names are the module paths, e.g. pcapkit.foundation.extraction, pcapkit.foundation.registry.protocols, pcapkit.foundation.engines.pcap, pcapkit.foundation.reassembly.reassembly, pcapkit.foundation.traceflow.tcp, pcapkit.utilities.warnings.

pcapkit.utilities.logging.get_logger(name=None)[source]¶

Retrieve a logger inside pcapkit’s hierarchy.

This is the accessor every module in pcapkit uses, as logger = get_logger(__name__), so that records carry the emitting module’s name and an application can address one subtree at a time.

Parameters:: name (str | None) – Dotted logger name, normally the caller’s __name__. None or 'pcapkit' yields the root logger. A name outside the pcapkit hierarchy – notably '__main__', which is what __name__ reports for a module run as a script – is placed under the root rather than beside it, since a sibling of pcapkit would escape every pcapkit-level configuration.
Return type:: Logger
Returns:: The requested logger.

pcapkit.utilities.logging.ROOT_LOGGER_NAME = 'pcapkit'¶

Name of the logger at the root of pcapkit’s hierarchy.

Type:: str

What `DEBUG` Will Tell You¶

At logging.DEBUG the library reports what it did with a file: which input was opened, which engine was requested and which was actually used (including a fallback when an optional dependency is missing), the file format identified from the magic number, the output format and dumper, whether reassembly and flow tracing were enabled and with which flags, how many frames were read, and when cleanup ran. Reassembly reports datagram counts on flush and flow tracing reports flows opening and closing.

Note

Nothing is logged from inside per-frame or per-field parsing loops, so DEBUG on a million-packet capture does not yield a million records. Registration bookkeeping in pcapkit.foundation.registry is at DEBUG rather than INFO, since a library announcing its own registry entries is not news to its consumer.

Configuring the Output¶

Importing pcapkit configures no logging output: the only handler attached to logger is a logging.NullHandler, and no level is set. This is the convention for libraries: the application keeps control of its logging, and pcapkit’s records propagate into whatever it has configured, e.g. via logging.basicConfig() or logging.config.

An application that would rather let pcapkit set up its own output calls configure():

import logging
import sys

from pcapkit.utilities.logging import configure, reset

# everything pcapkit does, on stderr
configure(logging.DEBUG, stream=sys.stderr)

# to a file, with a format of your own
configure(logging.INFO, handler=logging.FileHandler('pcapkit.log'),
          fmt='%(asctime)s %(name)s %(levelname)s %(message)s')

# loud in general, quiet about the registry
configure(logging.DEBUG, stream=sys.stderr)
configure(logging.WARNING, name='pcapkit.foundation.registry')

# and back to the pristine, library-neutral state
reset()

pcapkit.utilities.logging.configure(level=None, *, name=None, stream=None, handler=None, fmt=None, datefmt=None, propagate=None, replace=True)[source]¶

Configure pcapkit’s logging at runtime.

Every argument is optional and only the ones supplied take effect, so this is usable both as a one-shot setup call and as a targeted adjustment.

Parameters:

level (int | str | None) – Level for the logger, as either a str name ('DEBUG') or an int (logging.DEBUG). Left untouched when None, which for a freshly imported pcapkit means the level is inherited from the application.
name (str | None) – Logger to configure, as accepted by get_logger(). Defaults to the root logger; pass e.g. 'pcapkit.foundation.registry' to configure one subtree.
stream (IO[str] | None) – Writable text stream to log to, e.g. sys.stderr. A logging.StreamHandler is created for it and given a logging.Formatter built from fmt and datefmt.
handler (Handler | None) – An already-built handler to attach instead, for anything a plain stream cannot express – a RotatingFileHandler, a queue handler, a test double. Mutually exclusive with stream. Its formatter is only replaced if fmt or datefmt is given.
fmt (str | None) – Format string for the handler this call creates. Defaults to DEFAULT_FORMAT.
datefmt (str | None) – Date format string for the handler this call creates. Defaults to DEFAULT_DATE_FORMAT.
propagate (bool | None) – Whether records should reach ancestor loggers. Setting this to False on the root logger keeps pcapkit’s records out of the application’s own handlers.
replace (bool) – Whether to detach the logger’s existing handlers first, so that repeated calls replace rather than accumulate output. Pass False to add a second destination. Unlike reset(), this only touches handlers – the level and propagation are left alone unless the corresponding arguments are given.

Return type:

Logger

Returns:

The logger that was configured, for chaining or inspection.

Raises:

ValueError – If both stream and handler are given, since which one is meant to receive fmt would be ambiguous.

Example

Restore the pre-1.5 default of sys.stderr at logging.INFO:

configure(logging.INFO, stream=sys.stderr)

Send everything to a file, but keep the registry’s bookkeeping out:

configure(logging.DEBUG, handler=logging.FileHandler('pcapkit.log'))
configure(logging.INFO, name='pcapkit.foundation.registry')

pcapkit.utilities.logging.reset(name=None)[source]¶

Restore a pcapkit logger to its pristine, library-neutral state.

That is: no handlers other than the logging.NullHandler on the root, no level of its own (logging.NOTSET, so the level is inherited from the application’s configuration), and propagation enabled.

Parameters:: name (str | None) – Logger to reset, as accepted by get_logger(). Defaults to the root logger, which also resets nothing else – children keep any level explicitly set on them.
Return type:: Logger
Returns:: The logger that was reset.

Note

This discards the PCAPKIT_DEVMODE bootstrap along with everything else. To reinstate it, call configure(logging.DEBUG, stream=sys.stderr).

pcapkit.utilities.logging.ensure_output(level=10, *, stream=None)[source]¶

Guarantee that pcapkit’s records have somewhere to go.

This is for a caller that has switched something on precisely because it wants to see the output, and for which staying silent merely because the application never configured logging would be unhelpful.

Note that Extractor(verbose=True) and the CLI’s -v do not go through here: their frame chains are user-facing output and are written to sys.stdout with print(), so they are visible with no logging configuration at all. Nothing in pcapkit calls this function itself; it exists for consumers.

An application that has configured its own handlers has already answered the question, so nothing is changed in that case.

Parameters:

level (int | str) – Level to configure if, and only if, a handler has to be added.
stream (IO[str] | None) – Where to write, defaulting to sys.stderr.

Return type:

bool

Returns:

True if a handler was added, False if output was already going somewhere and the existing configuration was left alone.

Formatting¶

pcapkit.utilities.logging.DEFAULT_FORMAT = '[%(levelname)s] %(asctime)s - %(message)s'¶

Default logging.Formatter format string.

Type:: str

pcapkit.utilities.logging.DEFAULT_DATE_FORMAT = '%m/%d/%Y %I:%M:%S %p'¶

Default logging.Formatter date format string.

Type:: str

pcapkit.utilities.logging.formatter¶

Default formatter, used by any handler that configure() creates and by the PCAPKIT_DEVMODE bootstrap.

Type:: logging.Formatter

pcapkit.utilities.logging.handler¶

The historical sys.stderr handler. It is only attached under PCAPKIT_DEVMODE; it is constructed unconditionally so that logger.addHandler(handler) remains a one-line way back to the pre-1.5 default output.

Type:: logging.StreamHandler

Environment Variables¶

pcapkit.utilities.logging.DEVMODE¶

Development mode flag.

Type:: bool

Compatibility Note¶

Warning

Before 1.5.0, importing pcapkit attached a logging.StreamHandler on sys.stderr and forced the level to logging.INFO (or logging.DEBUG under PCAPKIT_DEVMODE). It no longer does, because that hijacked the logging configuration of every application importing pcapkit. Two consequences are visible to existing code:

Nothing reaches stderr by default. The registered ... bookkeeping is at logging.DEBUG, not logging.INFO. To restore the stderr output:

import logging, sys
from pcapkit.utilities.logging import configure
configure(logging.INFO, stream=sys.stderr)

Equivalently, re-attach the module’s own handler, which is still built with the historical format:

from pcapkit.utilities.logging import handler, logger
logger.setLevel(logging.INFO)
logger.addHandler(handler)

The handler is not at logger.handlers[0]. Code that reached into that list to remove or reconfigure it should call reset() or configure() instead.

Unchanged: logger is public, importable from both pcapkit.utilities.logging and pcapkit.utilities, and named pcapkit; PCAPKIT_DEVMODE attaches the stderr handler at logging.DEBUG; and Extractor(verbose=True) – like the CLI’s -v – prints a line per frame to sys.stdout. That output is a feature of the tool rather than diagnostics, so it deliberately stays on print(): routing it through logging would move it to another stream and hide it until the consumer configured a handler.

Note

The warning channel is documented in User Defined Warnings. In short, pcapkit.utilities.warnings.warn() reports each warning exactly once per channel – one logging.WARNING record and one warnings.warn() – and constructing a warning does not touch the process-wide warning filters, so suppression is the application’s to configure.

Logging System¶

The Logger Hierarchy¶

What DEBUG Will Tell You¶

Configuring the Output¶

Formatting¶

Environment Variables¶

Compatibility Note¶

What `DEBUG` Will Tell You¶