pdcomm_logging_configure

Function

Configures library-local diagnostics logging.

PdcommStatus pdcomm_logging_configure(const uint8_t *input, size_t size)

Declared in: #include <pdcomm.h>

Logging is off by default. When it is enabled, records are written as JSON Lines (one JSON object per line) by a single background thread named pdcomm-log, to standard error or to a size-rotated file. Protocol code never blocks on logging: records that do not fit the bounded queue are dropped and counted in pdcomm_logging_status().

input is a UTF-8 JSON object, not NUL-terminated, with these optional members (unknown members are rejected):

enabled (boolean, default true): false turns logging off.
level (string, default "info"): "error", "warn", "info", "debug", or "trace".
file (non-empty string or null, default null): the log file path; null writes to standard error.
max_bytes (integer, default 10485760): rotation size, from 8192 to 1073741824 bytes.
files (integer, default 3): number of retained files, from 1 to 16.
forensics (boolean, default false): adds periodic process samples; requires level "debug" or "trace" while logging is enabled.

The call waits up to two seconds for the logging thread to apply the new configuration.

Parameters

Name	Description
`input`	JSON object bytes. Must not be NULL.
`size`	Number of bytes at `input`, from 1 to 16384.

Returns

#PDCOMM_OK when the configuration was applied; #PDCOMM_INVALID_ARGUMENT when input is NULL, size is 0 or larger than 16384, the JSON is invalid or out of range, the sink cannot be opened, or the logging thread could not apply the configuration within two seconds; #PDCOMM_INTERNAL_ERROR when a panic was contained.

Notes

Thread safety: may be called from any thread. Logging state is process-wide and shared by every endpoint.
When the environment variable PDCOMM_LOG is set to a level other than off before first use, the library enables logging with that level and reads PDCOMM_LOG_FILE, PDCOMM_LOG_MAX_BYTES, PDCOMM_LOG_FILES, and PDCOMM_LOG_FORENSICS. A later call to this function replaces that configuration.
No pointer is retained after the call returns.