Attention

This is the documentation for HARP Proxy, actually published as an early preview. Both the software and documentation are a work in progress, and although we already use it on various production servers, they may contain inaccuracies, typographical errors, huge mistakes and empty pages. We work hard to eradicate all mistakes and implement stuff, but it is a long and tedious process. We appreciate your patience and understanding. Of course, any help will be greatly appreciated.

Logging

For logging purposes, Harp uses the standard python logging module, with structlog on top of it.

Logs are organized in a hierarchical manner according to the python package structure. The root logger sets up global configurations which can be modified for each package or subpackage. The configurations for a package are inherited by all its subpackages.

Log levels

To adjust the logs verbosity, set a lower minimum level for one of the loggers. Available log levels are, from most verbose to least, DEBUG, INFO, WARNING, ERROR, CRITICAL.

• LOGGING_HARP=...: log level for harp.* and harp_app.* loggers [default: INFO].

• LOGGING_HARP_EVENTS=...: log level for harp.event_dispatcher_* loggers [default: WARNING]. Allows to get debug information about the events happening (managed by whistle).

• LOGGING_HTTP=...: log level for httpcore.* and httpx.* loggers [default: WARNING].

• LOGGING_HYPERCORN_ACCESS=...: log level for hypercorn.access logger [default: WARNING].

• LOGGING_HYPERCORN_ERROR=...: log level for hypercorn.error logger [default: INFO].

Formatters

There are a few different logs formatters that you can use depending on your needs:

• plain is the simplest formatter, using a simple console output without colors (no ansi codes).

• pretty is the default formatter, using colors so that the logs are easier to read.

• json will format each log line as a small json, making it easy to ingest in log processing systems.

• keyvalue is another structured formatter, using key=value pairs.

To choose a formatter, set the LOGGING_FORMAT environment variable:

export LOGGING_FORMAT=json harp start ...

Special cases

SQL logs (SQLAlchemy)

To enable SQL logs, you should configure the sqlalchemy logger minimum level to INFO

export LOGGING_SQL=INFO harp start ...

This works for all execution contexts, including tests, etc.

HTTP Client logs (HTTPX)

Todo

Document how to enable HTTPX logs and the low level logs.

Questions

Why can’t I configure the logger in harm regular config files?

The logger is a special case that needs to be configured at the earliest possible time in the application lifecycle. We may consider about pre-reading config files to configure the logger in the future, but this creates some complexity that we do not want to consider, for now.

Why does the logger-related environment variables have a different prefix?

The reason is basically the same as for the config files: as all HARP_ prefixed environment variables are used to extend the regular harp configuration, we decided to use a different prefix for the logger-related variables to avoid confusion or hacks to discriminate between regular config and logger-related config.