Skip to content
Start free evaluation

pdcomm::DiagnosticLogging

Class

Controls the optional diagnostic log of the SECS/GEM native library.

class DiagnosticLogging

Declared in: #include <pdcomm_logging.hpp>

Logging is off by default. When enabled, the library writes JSON Lines records asynchronously from a background pdcomm-log thread to standard error or to a rotating file. Protocol calls never wait for the logger: when its queue is full or busy, records are dropped and counted in status().

The settings are process-wide for the SECS/GEM library only. The Modbus library has its own pdcomm::modbus::DiagnosticLogging. If the PDCOMM_LOG environment variable is set to a level other than off when the logger is first used, it enables logging at that level; PDCOMM_LOG_FILE, PDCOMM_LOG_MAX_BYTES, PDCOMM_LOG_FILES and PDCOMM_LOG_FORENSICS supply the other options.

pdcomm::DiagnosticLogging::configure(R"({"enabled":true,"level":"debug"})");
// ... run the session ...
pdcomm::DiagnosticLogging::flush();
std::cout << pdcomm::DiagnosticLogging::status() << '\n';
pdcomm::DiagnosticLogging::configure(R"({"enabled":false})");

Notes

  • All members are static and thread-safe. Failures throw std::runtime_error, not pdcomm::Error.

Members

configure

Method

Applies a logging configuration given as a JSON object.

static void configure(const std::string &json)

Declared in: #include <pdcomm_logging.hpp>

Accepted keys, all optional:

  • enabled (bool, default true): turns logging on or off.
  • level ("error", "warn", "info", "debug" or "trace"; default "info").
  • file (non-empty path string, or null for standard error; default standard error).
  • max_bytes (rotation size, 8192 to 1073741824; default 10485760).
  • files (number of rotated files kept, 1 to 16; default 3).
  • forensics (bool, default false): adds resource samples; requires "debug" or "trace".

Unknown keys are rejected. The call waits up to two seconds for the logging thread to apply the new sink.

Parameters

NameDescription
jsonUTF-8 JSON object of at most 16384 bytes.

Notes

  • Throws std::runtime_error: when json is empty, longer than 16384 bytes, not valid JSON, contains an unknown or invalid option, the log file cannot be opened, or the logging thread does not acknowledge in time.

flush

Method

Waits until queued log records are written.

static void flush()

Declared in: #include <pdcomm_logging.hpp>

The call waits up to two seconds. When logging has never been enabled it returns immediately.

Notes

  • Throws std::runtime_error: when the logging thread does not confirm the flush in time.

status

Method

Returns the current logging status as a JSON object.

static std::string status()

Declared in: #include <pdcomm_logging.hpp>

The object reports enabled, level/level_name, sink ("file" or "stderr"), max_bytes, files, forensics, queue and record limits, and the counters written, dropped, write_errors and configuration_errors.

Returns

The status JSON text.

Notes

  • Throws std::runtime_error: when the native call fails, including when the status text would exceed this wrapper's fixed 4096-byte buffer.

Privacy Policy