C++17 API Reference¶

This page documents the portable ISO C++17 classes, structs, enums, and functions in namespace ezsnmp_data_logger, generated automatically from header Doxygen comments via Breathe.

Core Engine & CLI Dispatcher¶

DataLogger¶

class DataLogger¶

High-throughput C++17 SNMP Data Logger engine.

Orchestrates concurrent SNMP polling across configured Devices Under Test (DUTs), buffers collected Batch objects through a bounded lock-protected queue, and fans telemetry out to CSV, JSONL, SQLite3, PostgreSQL, and Prometheus HTTP sinks.

Designed with a clean PIMPL boundary so SWIG 4.x can expose DataLogger directly to Python, JavaScript/Node.js, Java, C#, Go, Ruby, Perl, PHP, Lua, R, Tcl, Octave, D, Guile, and Scilab.

Public Functions

explicit DataLogger(LoggerConfig const &config)¶

Construct a DataLogger from a parsed LoggerConfig struct.

Parameters:: config – Validated LoggerConfig.
Throws:: ConfigError – or SinkError on invalid configuration or sink setup failure.

explicit DataLogger(std::string const &json_config)¶

Construct a DataLogger directly from a JSON configuration string.

Parameters:: json_config – Complete JSON configuration document.
Throws:: ConfigError – or SinkError on invalid JSON or sink setup failure.

void set_batch_callback(std::function<void(Batch const&)> cb)¶: Register an optional C++ observer invoked on the writer thread after each Batch is persisted (used by CLI --json live event streaming).

void start()¶: Start background DUT polling threads and sink writer thread (non-blocking).

void stop()¶: Signal all polling threads to stop, drain the bounded queue, and flush sinks.

void run()¶: Run the logger synchronously in the foreground until stop(), max_cycles, or duration.

std::vector<Batch> run_once()¶

Execute exactly one polling cycle across all enabled DUTs, write to sinks, and flush.

Returns:: Vector of Batch objects collected during this single cycle.

bool is_running() const¶

Check whether background polling/writing threads are currently active.

Returns:: true if running, false otherwise.

bool push_batch(Batch const &batch)¶

Manually push a custom Batch into the writer queue (enables external language producers).

Parameters:: batch – Batch to enqueue for storage sinks.
Returns:: true if enqueued, false if dropped due to queue back-pressure.

bool push_batch_json(std::string const &batch_json)¶

Parse a Batch from JSON text and enqueue it for storage sinks.

Parameters:: batch_json – JSON string representing a Batch.
Returns:: true if enqueued, false if dropped due to queue back-pressure.

void flush()¶: Flush all active storage sinks immediately.

LoggerStats stats() const¶

Return structured operational telemetry statistics.

Returns:: LoggerStats snapshot.

std::string stats_json(int indent = -1) const¶

Return operational telemetry statistics serialized as a JSON string.

Parameters:: indent – Indentation spaces (-1 for compact single-line JSON).
Returns:: JSON stats string.

std::string config_json(int indent = 2) const¶

Return the active configuration serialized as JSON text.

Parameters:: indent – Indentation spaces (default 2).
Returns:: JSON configuration string.

Public Static Functions

static DataLogger from_file(std::string const &file_path)¶

Create a DataLogger by reading a JSON configuration file from disk.

Parameters:: file_path – Path to the JSON configuration file.
Returns:: Configured DataLogger instance (by move/RVO or pointer-safe wrapper).

static std::vector<DutProbeResult> probe(LoggerConfig const &config, std::string const &dut_filter = "")¶

Probe configured DUTs once without writing to any storage sink.

Parameters:

config – LoggerConfig containing DUT definitions.
dut_filter – Optional single DUT name to probe (empty = all enabled DUTs).

Returns:

Vector of DutProbeResult objects with live samples and latency.

static std::string probe_json(std::string const &json_config, std::string const &dut_filter = "", int indent = -1)¶

Probe configured DUTs from JSON configuration text and return a JSON report.

Parameters:

json_config – JSON configuration text.
dut_filter – Optional single DUT name to probe (empty = all enabled DUTs).
indent – Indentation spaces (-1 for compact).

Returns:

JSON report object containing per-DUT probe results.

static std::string request_json(std::string const &json_config, std::string const &dut_name, std::string const &operation, std::vector<std::string> const &oids, int max_repeaters = 10, bool record_to_sinks = false, int indent = -1)¶

Execute an on-demand SNMP request (get, getnext, walk, bulkget, bulkwalk) against a configured DUT via ezsnmp’s SessionBase and optionally persist results to sinks.

Parameters:

json_config – JSON configuration text.
dut_name – Target DUT name from configuration.
operation – SNMP operation (get, getnext, walk, bulkget, bulkwalk).
oids – Vector of OID strings to query.
max_repeaters – Max repeaters for bulk operations (default 10).
record_to_sinks – If true, also write the returned Batch to all enabled sinks.
indent – Indentation spaces (-1 for compact).

Returns:

JSON report containing returned samples and latency.

static std::string set_json(std::string const &json_config, std::string const &dut_name, std::string const &oid, std::string const &set_type, std::string const &set_value, bool record_to_sinks = false, int indent = -1)¶

Execute an on-demand SNMP SET operation against a configured DUT via ezsnmp’s SessionBase::set and optionally persist the response to configured sinks.

Parameters:

json_config – JSON configuration text.
dut_name – Target DUT name from configuration.
oid – Target OID string.
set_type – Net-SNMP / ezsnmp type character (s, i, u, t, a, o, x).
set_value – Value string to write.
record_to_sinks – If true, also write the SET response Batch to all enabled sinks.
indent – Indentation spaces (-1 for compact).

Returns:

JSON report containing SET response sample(s) and latency.

static std::string inspect_json(std::string const &json_config, int limit = 50, std::string const &dut_filter = "", std::string const &metric_filter = "", int indent = -1)¶

Inspect recent logged samples from configured local sinks and return JSON.

Parameters:

json_config – JSON configuration text.
limit – Maximum rows to return (default 50).
dut_filter – Optional DUT name filter.
metric_filter – Optional metric name filter.
indent – Indentation spaces (-1 for compact).

Returns:

JSON report object with inspected telemetry rows.

class Impl¶

CliRunner & CliResult¶

class CliRunner¶

Command-line interface dispatcher for ezsnmp_data_logger.

Powers both the native ezsnmp-data-logger C++17 CLI executable and programmatic CLI execution from any SWIG target language. The GUI interacts exclusively with this CLI interface and JSON configuration files.

Public Static Functions

static int run(std::vector<std::string> const &args)¶

Execute CLI arguments, writing directly to process stdout/stderr.

Parameters:: args – Command-line arguments (excluding argv[0] program name).
Returns:: Process exit code (0 on success, non-zero on error).

static CliResult execute(std::vector<std::string> const &args)¶

Execute CLI arguments and capture stdout/stderr in a CliResult struct.

Parameters:: args – Command-line arguments (excluding argv[0] program name).
Returns:: Captured CliResult containing exit_code, stdout_text, and stderr_text.

static void request_stop()¶: Request any active foreground CliRunner::run session to stop gracefully.

struct CliResult¶

Structured result returned when executing a CLI command programmatically.

Public Functions

std::string to_json(int indent = -1) const¶

Serialize this CliResult to a JSON string.

Parameters:: indent – Indentation spaces (-1 for compact).
Returns:: JSON string.

EzSnmp Polling Layer¶

EzSnmpPoller delegates all SNMPv1, SNMPv2c, and SNMPv3 get, getnext, walk, bulkget, bulkwalk, and set requests to ezsnmp’s C++17 SessionBase and Result classes, normalizing returned bindings into Sample and Batch records.

class ISnmpPoller¶

Abstract interface for executing SNMP requests against a single Device Under Test.

Subclassed by ezsnmp_data_logger::EzSnmpPoller, ezsnmp_data_logger::StubSnmpPoller

Public Functions

virtual Batch poll() = 0¶

Execute one polling cycle across all configured metrics of the DUT.

Returns:: Batch containing timestamp, DUT identity, and collected Sample entries.

virtual Batch request(std::string const &operation, std::vector<std::string> const &oids, int max_repeaters = 10) = 0¶

Perform an on-demand SNMP request (get, getnext, walk, bulkget, bulkwalk).

Parameters:

operation – SNMP operation name.
oids – Target OID strings.
max_repeaters – Max repeaters for bulk operations.

Returns:

Batch containing the returned ezsnmp Result samples.

virtual Batch set_oid(std::string const &oid, std::string const &set_type, std::string const &set_value) = 0¶

Perform an SNMP SET operation (oid, type_char, value).

Parameters:

oid – Target OID string.
set_type – Net-SNMP / ezsnmp type character (e.g. “s”, “i”, “u”, “t”, “a”, “o”, “x”).
set_value – Value string to write.

Returns:

Batch containing the SET response Sample(s).

class EzSnmpPoller : public ezsnmp_data_logger::ISnmpPoller ¶

Poller backed directly by ezsnmp’s C++17 SessionBase and Result layer.

Delegates all Net-SNMP session management, SNMPv1/v2c/v3 USM authentication & privacy, thread-safe MIB formatting, and GET/GETNEXT/WALK/BULKGET/BULKWALK/SET operations to the sibling ezsnmp library (SessionBase), converting returned Result objects into ezsnmp_data_logger::Sample records for storage in the data_logger layer.

Public Functions

virtual Batch poll() override¶

Execute one polling cycle across all configured metrics of the DUT.

Returns:: Batch containing timestamp, DUT identity, and collected Sample entries.

virtual Batch request(std::string const &operation, std::vector<std::string> const &oids, int max_repeaters = 10) override¶

Perform an on-demand SNMP request (get, getnext, walk, bulkget, bulkwalk).

Parameters:

operation – SNMP operation name.
oids – Target OID strings.
max_repeaters – Max repeaters for bulk operations.

Returns:

Batch containing the returned ezsnmp Result samples.

virtual Batch set_oid(std::string const &oid, std::string const &set_type, std::string const &set_value) override¶

Perform an SNMP SET operation (oid, type_char, value).

Parameters:

oid – Target OID string.
set_type – Net-SNMP / ezsnmp type character (e.g. “s”, “i”, “u”, “t”, “a”, “o”, “x”).
set_value – Value string to write.

Returns:

Batch containing the SET response Sample(s).

class StubSnmpPoller : public ezsnmp_data_logger::ISnmpPoller ¶

Deterministic/synthetic SNMP poller for testing, demos, and offline validation.

Public Functions

virtual Batch poll() override¶

Execute one polling cycle across all configured metrics of the DUT.

Returns:: Batch containing timestamp, DUT identity, and collected Sample entries.

virtual Batch request(std::string const &operation, std::vector<std::string> const &oids, int max_repeaters = 10) override¶

Perform an on-demand SNMP request (get, getnext, walk, bulkget, bulkwalk).

Parameters:

operation – SNMP operation name.
oids – Target OID strings.
max_repeaters – Max repeaters for bulk operations.

Returns:

Batch containing the returned ezsnmp Result samples.

virtual Batch set_oid(std::string const &oid, std::string const &set_type, std::string const &set_value) override¶

Perform an SNMP SET operation (oid, type_char, value).

Parameters:

oid – Target OID string.
set_type – Net-SNMP / ezsnmp type character (e.g. “s”, “i”, “u”, “t”, “a”, “o”, “x”).
set_value – Value string to write.

Returns:

Batch containing the SET response Sample(s).

std::unique_ptr<ISnmpPoller> ezsnmp_data_logger::create_snmp_poller(DutConfig const &dut)¶: Factory creating the appropriate ISnmpPoller for a DutConfig (“ezsnmp” or “stub”).

JSON Configuration Model¶

struct LoggerConfig¶

Complete unified JSON configuration for ezsnmp_data_logger.

Public Functions

std::string to_json(int indent = 2) const¶: Serialize the complete configuration back to JSON text.

Public Static Functions

static LoggerConfig from_json(std::string const &json_text)¶: Parse a LoggerConfig from a JSON string.

static LoggerConfig from_file(std::string const &file_path)¶: Load and parse a LoggerConfig from a JSON file path.

struct LoggerRuntimeConfig¶: Engine-level runtime scheduling, queueing, and lifecycle parameters.

struct DutConfig¶: Configuration for a single Device Under Test (DUT).

struct SnmpConfig¶: SNMP protocol, security, MIB, and output formatting settings mapped directly to ezsnmp’s C++17 SessionBase constructor parameters.

struct MetricConfig¶: Single SNMP OID metric or SET request definition within a DUT configuration.

struct SinkConfig¶: Configuration for a single telemetry output sink.

struct GuiConfig¶

Cross-platform GUI settings stored inside JSON configuration files.

Supports native cross-platform desktop (tkinter.ttk on Linux, macOS, Windows) and local browser studio (web on Linux, macOS, Windows).

struct ValidationReport¶

Structured result of validating a JSON configuration.

Public Functions

std::string to_json(int indent = -1) const¶: Serialize this validation report to a JSON string.

Telemetry Datatypes¶

enum class ezsnmp_data_logger::TypeTag : int¶

Discriminator tag identifying which typed field of Sample is active.

Values:

enumerator Null¶

enumerator Int64¶

enumerator Float64¶

enumerator Str¶

struct Sample¶

Single SNMP metric reading captured via ezsnmp for a Device Under Test (DUT).

Preserves the full ezsnmp Result metadata (oid, oid_index, snmp_type, raw_value) alongside normalized typed storage fields (type_tag, i64, f64, str_val, status).

Public Functions

Sample() = default¶: Construct an empty null sample.

std::string display_value() const¶

Render the active value as a display string regardless of type_tag.

Returns:: String representation of the sample value.

std::string to_json(int indent = -1) const¶

Serialize this sample to a JSON string.

Parameters:: indent – Indentation spaces (-1 for compact).
Returns:: JSON object string.

Public Static Functions

static Sample make_int(std::string const &name, std::string const &oid_str, int64_t val, int status_code = 0)¶: Create an integer sample.

static Sample make_float(std::string const &name, std::string const &oid_str, double val, int status_code = 0)¶: Create a floating-point sample.

static Sample make_string(std::string const &name, std::string const &oid_str, std::string const &val, int status_code = 0)¶: Create a string sample.

static Sample from_json(std::string const &json_text)¶

Parse a Sample from a JSON object string (including ezsnmp Result.to_dict() JSON).

Parameters:: json_text – JSON string representing a sample or ezsnmp Result.
Returns:: Parsed Sample.

struct Batch¶

Timestamped collection of SNMP samples polled from a single DUT.

Public Functions

std::string to_json(int indent = -1) const¶

Serialize this Batch to a JSON string.

Parameters:: indent – Indentation spaces (-1 for compact).
Returns:: JSON object string.

Public Static Functions

static Batch from_json(std::string const &json_text)¶

Parse a Batch from a JSON object string.

Parameters:: json_text – JSON string representing a batch.
Returns:: Parsed Batch.

struct DutProbeResult¶

Diagnostic result from probing or requesting a DUT via ezsnmp.

Public Functions

std::string to_json(int indent = -1) const¶

Serialize this DutProbeResult to a JSON string.

Parameters:: indent – Indentation spaces (-1 for compact).
Returns:: JSON object string.

struct LoggerStats¶

Live operational telemetry counters for a DataLogger instance.

Public Functions

std::string to_json(int indent = -1) const¶

Serialize LoggerStats to a JSON string.

Parameters:: indent – Indentation spaces (-1 for compact).
Returns:: JSON object string.

struct InspectRow¶

Flattened stored telemetry record returned when inspecting configured sinks.

Public Functions

std::string to_json(int indent = -1) const¶

Serialize InspectRow to a JSON string.

Parameters:: indent – Indentation spaces (-1 for compact).
Returns:: JSON object string.

Storage Sinks & Inspection¶

class ISink¶

Abstract storage/telemetry output sink interface.

Subclassed by ezsnmp_data_logger::CsvSink, ezsnmp_data_logger::JsonlSink, ezsnmp_data_logger::PrometheusSink, ezsnmp_data_logger::PsqlSink, ezsnmp_data_logger::SqliteSink

Public Functions

virtual void write(Batch const &batch) = 0¶

Write a polled Batch to this sink.

Parameters:: batch – Timestamped batch of SNMP samples.

virtual void flush() = 0¶: Flush any buffered samples to underlying storage.

virtual void close() = 0¶: Flush and release all resources held by this sink.

virtual std::string name() const = 0¶

Return the short type identifier of this sink (e.g. “csv”, “sqlite3”).

Returns:: Sink type name.

std::unique_ptr<ISink> ezsnmp_data_logger::create_sink(SinkConfig const &cfg)¶

Instantiate a concrete ISink from a SinkConfig.

Parameters:: cfg – Sink configuration entry.
Throws:: SinkError – if sink initialization fails or support is not compiled in.
Returns:: Unique pointer to constructed ISink.

std::vector<InspectRow> ezsnmp_data_logger::inspect_configured_sinks(LoggerConfig const &cfg, int limit = 50, std::string const &dut_filter = "", std::string const &metric_filter = "")¶

Query recent stored telemetry rows across configured local sinks (SQLite3, JSONL, CSV).

Parameters:

cfg – Full LoggerConfig specifying sink paths.
limit – Maximum number of most-recent rows to return.
dut_filter – Optional DUT name filter (empty = all DUTs).
metric_filter – Optional metric name filter (empty = all metrics).

Returns:

Vector of InspectRow sorted newest-first.

Exceptions¶

class LoggerError : public std::runtime_error¶

Base exception class for all ezsnmp_data_logger errors.

All domain-specific exceptions in the C++17 core inherit from LoggerError so SWIG bindings across every target language can catch errors uniformly.

Subclassed by ezsnmp_data_logger::CliError, ezsnmp_data_logger::ConfigError, ezsnmp_data_logger::SinkError, ezsnmp_data_logger::SnmpError

Public Functions

inline explicit LoggerError(std::string const &message)¶

Construct a LoggerError with an explanatory message.

Parameters:: message – Human-readable error message.

class ConfigError : public ezsnmp_data_logger::LoggerError ¶

Exception thrown when JSON configuration parsing or validation fails.

Public Functions

inline explicit ConfigError(std::string const &message)¶

Construct a ConfigError with an explanatory message.

Parameters:: message – Human-readable configuration error message.

class SnmpError : public ezsnmp_data_logger::LoggerError ¶

Exception thrown when an SNMP session or polling operation fails fatally.

Public Functions

inline explicit SnmpError(std::string const &message)¶

Construct an SnmpError with an explanatory message.

Parameters:: message – Human-readable SNMP error message.

class SinkError : public ezsnmp_data_logger::LoggerError ¶

Exception thrown when a storage sink initialization, write, or query fails.

Public Functions

inline explicit SinkError(std::string const &message)¶

Construct a SinkError with an explanatory message.

Parameters:: message – Human-readable sink error message.

class CliError : public ezsnmp_data_logger::LoggerError ¶

Exception thrown when CLI command arguments or execution fail.

Public Functions

inline explicit CliError(std::string const &message)¶

Construct a CliError with an explanatory message.

Parameters:: message – Human-readable CLI error message.