Metrics API

The Metrics struct provides comprehensive observability into the logging system's performance and health.

Quick Reference: Method Aliases

Full Method	Alias(es)	Description
`init()`	`create()`	Initialize metrics
`deinit()`	`destroy()`	Deinitialize metrics
`initWithConfig()`	`createWithConfig()`, `newWithConfig()`	Initialize with config
`recordLog()`	`record()`, `log()`	Record log event
`recordDrop()`	`drop()`, `dropped()`	Record dropped event
`recordError()`	`recordErr()`	Record error event
`getSnapshot()`	`metricsSnapshot()`	Get metrics snapshot
`formatLevelBreakdown()`	`levels()`, `breakdown()`	Format level breakdown
`reset()`	`clear()`	Reset metrics
`uptimeSeconds()`	`uptimeSec()`	Get uptime in seconds
`bytesPerSecond()`	`throughput()`	Get bytes per second
`setRecordLoggedCallback()`	`onRecordLogged()`, `setOnRecordLogged()`	Set record logged callback
`setSnapshotCallback()`	`onSnapshot()`, `setOnSnapshot()`	Set snapshot callback
`setThresholdCallback()`	`onThreshold()`, `setOnThreshold()`	Set threshold callback
`setErrorCallback()`	`onError()`, `setOnError()`	Set error callback
`getConfig()`	`getConfiguration()`, `configuration()`	Get configuration
`isEnabled()`	`enabled()`, `isActive()`	Check if enabled
`recordLogWithLatency()`	`recordWithLatency()`, `logWithLatency()`	Record log with latency
`recordSinkWrite()`	`sinkWrite()`, `recordSinkWriteOp()`	Record sink write
`recordSinkError()`	`sinkError()`, `recordSinkErrorOp()`	Record sink error
`takeSnapshot()`	`captureSnapshot()`, `takeSnapshotNow()`	Take snapshot
`getHistory()`	`getSnapshots()`, `snapshots()`	Get snapshots history
`exportMetrics()`	`exportData()`, `toString()`	Export metrics
`exportJson()`	`json()`, `toJson()`	Export as JSON
`exportPrometheus()`	`prometheus()`, `toPrometheus()`	Export as Prometheus
`exportStatsd()`	`statsd()`, `toStatsd()`	Export as StatsD
`avgLatencyNs()`	`avgLatency()`, `averageLatency()`	Get average latency
`minLatencyNs()`	`minLatency()`	Get minimum latency
`maxLatencyNs()`	`maxLatency()`	Get maximum latency
`getHistogram()`	`latencyHistogram()`, `getLatencyHistogram()`	Get latency histogram
`latencyPercentileNs()`	`latencyPercentile()`, `percentileNs()`	Estimate latency percentile (ns)
`latencyPercentileMs()`	`percentileMs()`	Estimate latency percentile (ms)
`getLatencySummary()`	`latencySummary()`, `summaryLatency()`	Get latency summary (p50/p95/p99)
`format()`	`formatMetrics()`, `stringify()`	Format metrics
`recordCustomLog()`	`recordCustom()`, `customLog()`	Record custom log
`hasRecords()`	`hasData()`	Check if has records
`totalRecordCount()`	`recordCount()`, `totalRecords()`	Get total record count
`totalBytesLogged()`	`bytesLogged()`, `totalBytes()`	Get total bytes logged
`rate()`	`recordsPerSecond()`, `recordsPerSec()`	Get records per second
`errorCount()`	`errorTotal()`, `totalErrors()`	Get error count
`droppedCount()`	`dropTotal()`, `totalDropped()`	Get dropped count
`errorRate()`	`failureRate()`	Get error rate
`dropRate()`	`dropPercentage()`	Get drop rate
`hasHighErrorRate()`	`highErrorRate()`, `errorRateHigh()`	Check if high error rate
`hasHighDropRate()`	`highDropRate()`, `dropRateHigh()`	Check if high drop rate
`levelCount()`	`countForLevel()`, `levelRecords()`	Get level count
`sinkCount()`	`sinks()`, `sinkTotal()`	Get sink count
`totalSinkErrors()`	`sinkErrorsTotal()`	Get total sink errors
`totalSinkFlushes()`	`sinkFlushesTotal()`	Get total sink flushes
`lastRecordAgeMs()`	`recordAgeMs()`, `ageSinceLastRecordMs()`	Get age since last record
`recordSinkFlush()`	`sinkFlush()`, `recordSinkFlushOp()`	Record sink flush
`getSinkMetrics()`	`sinkMetrics()`, `getSinkStats()`	Get sink metrics
`getSinkMetricsByName()`	`sinkMetricsByName()`, `getSinkStatsByName()`	Get sink metrics by name
`hasErrors()`	`hasFailures()`	Check if has errors
`hasDropped()`	`hasDrops()`	Check if has dropped
`getRecordsWritten()`	`records()`, `written()`	Get records written (SinkMetrics)
`getBytesWritten()`	`bytes()`, `bytesWritten()`	Get bytes written (SinkMetrics)
`getWriteErrors()`	`writeErrors()`, `errors()`	Get write errors (SinkMetrics)
`getFlushCount()`	`flushes()`, `flushCount()`	Get flush count (SinkMetrics)
`hasWritten()`	`hasData()`, `isActive()`	Check if has written (SinkMetrics)
`getErrorRate()`	`errorRate()`, `failureRate()`	Get error rate (SinkMetrics)
`getSuccessRate()`	`successRate()`, `success()`	Get success rate (SinkMetrics)
`avgBytesPerRecord()`	`avgBytes()`, `bytesPerRecord()`	Get avg bytes per record (SinkMetrics)
`avgRecordsPerFlush()`	`avgRecords()`, `recordsPerFlush()`	Get avg records per flush (SinkMetrics)
`throughputBytesPerSecond()`	`throughput()`, `bytesPerSecond()`	Get throughput (SinkMetrics)
`getDropRate()`	`dropRate()`, `dropPercentage()`	Get drop rate (Snapshot)
`basic()`	`simple()`, `minimal()`	Basic preset (MetricsPresets)
`createMetricsSink()`	`metricsSink()`, `sink()`	Create metrics sink (MetricsPresets)

Overview

Metrics tracks record counts, throughput, errors, and per-sink statistics. It uses thread-safe atomic operations for all counters, making it safe for concurrent access without locks on hot paths.

Types

Metrics

The main metrics controller with atomic counters and callback support.

zig

pub const Metrics = struct {
    total_records: std.atomic.Value(u64),
    total_bytes: std.atomic.Value(u64),
    dropped_records: std.atomic.Value(u64),
    error_count: std.atomic.Value(u64),
    level_counts: [10]std.atomic.Value(u64),
    start_time: i64,
    sink_metrics: std.ArrayList(SinkMetrics),
    
    // Callbacks
    on_record_logged: ?*const fn (Level, u64) void,
    on_metrics_snapshot: ?*const fn (*const Snapshot) void,
    on_threshold_exceeded: ?*const fn (MetricType, u64, u64) void,
    on_error_detected: ?*const fn (ErrorEvent, u64) void,
};

MetricType

Types of metrics for threshold notifications.

zig

pub const MetricType = enum {
    total_records,
    total_bytes,
    dropped_records,
    error_count,
    records_per_second,
    bytes_per_second,
};

ErrorEvent

Error event types for monitoring.

zig

pub const ErrorEvent = enum {
    records_dropped,
    sink_write_error,
    buffer_overflow,
    sampling_drop,
};

SinkMetrics

Per-sink statistics with atomic counters.

zig

pub const SinkMetrics = struct {
    name: []const u8,
    records_written: std.atomic.Value(u64),
    bytes_written: std.atomic.Value(u64),
    write_errors: std.atomic.Value(u64),
    flush_count: std.atomic.Value(u64),
};

Getter Methods

Method	Return	Description
`getRecordsWritten()`	`u64`	Get total records written
`getBytesWritten()`	`u64`	Get total bytes written
`getWriteErrors()`	`u64`	Get write errors count
`getFlushCount()`	`u64`	Get flush count

Boolean Checks

Method	Return	Description
`hasWritten()`	`bool`	Check if any records have been written
`hasErrors()`	`bool`	Check if any errors have occurred

Rate Calculations

Method	Return	Description
`getErrorRate()`	`f64`	Calculate error rate (0.0 - 1.0)
`getSuccessRate()`	`f64`	Calculate success rate (0.0 - 1.0)
`avgBytesPerRecord()`	`f64`	Calculate average bytes per record
`avgRecordsPerFlush()`	`f64`	Calculate average records per flush
`throughputBytesPerSecond(elapsed_seconds)`	`f64`	Calculate bytes per second throughput

Reset

Method	Description
`reset()`	Reset all statistics to initial state

Snapshot

A point-in-time snapshot of metrics, useful for reporting.

zig

pub const Snapshot = struct {
    total_records: u64,
    total_bytes: u64,
    dropped_records: u64,
    error_count: u64,
    uptime_ms: i64,
    records_per_second: f64,
    bytes_per_second: f64,
    level_counts: [10]u64,
    
    pub fn getDropRate(self: *const Snapshot) f64;
};

Methods

Initialization

`init(allocator: std.mem.Allocator) Metrics`

Initializes a new Metrics instance with all counters at zero.

Alias: create

`initWithConfig(allocator: std.mem.Allocator, config: MetricsConfig) Metrics`

Initializes a new Metrics instance with custom configuration.

`deinit(self: *Metrics) void`

Releases all resources associated with metrics.

Alias: destroy

Callbacks

`setRecordLoggedCallback(callback: *const fn (Level, u64) void) void`

Sets the callback invoked when a record is logged.

`setSnapshotCallback(callback: const fn (const Snapshot) void) void`

Sets the callback invoked when a metrics snapshot is taken.

`setThresholdCallback(callback: *const fn (MetricType, u64, u64) void) void`

Sets the callback invoked when metrics exceed thresholds.

`setErrorCallback(callback: *const fn (ErrorEvent, u64) void) void`

Sets the callback invoked when errors or dropped records are detected.

Configuration

`getConfig() MetricsConfig`

Returns the current metrics configuration.

`isEnabled() bool`

Returns true if metrics collection is enabled.

Recording

`recordLog(level: Level, bytes: u64) void`

Records a successful log event with its level and size.

Alias: record, log

`recordLogWithLatency(level: Level, bytes: u64, latency_ns: u64) void`

Records a log with latency measurement for histogram tracking.

`recordDrop() void`

Records a dropped log event (e.g., due to buffer overflow).

Alias: drop, dropped

`recordError() void`

Records an internal error.

Alias: recordErr

`recordCustomLog(bytes: u64) void`

Records a log using a custom level.

Sink Tracking

`addSink(name: []const u8) !usize`

Adds a sink to track. Returns the sink index.

`recordSinkWrite(sink_index: usize, bytes: u64) void`

Records a successful write to a sink.

`recordSinkError(sink_index: usize) void`

Records a write error on a sink.

`recordSinkFlush(sink_index: usize) void`

Records a flush operation on a sink.

`getSinkMetrics(sink_index: usize) ?SinkMetrics`

Returns sink metrics by index.

`getSinkMetricsByName(name: []const u8) ?SinkMetrics`

Returns sink metrics by name.

Snapshots

`getSnapshot() Snapshot`

Returns a thread-safe snapshot of the current metrics.

Alias: metricsSnapshot

`takeSnapshot() !Snapshot`

Takes a snapshot and optionally stores in history.

`getHistory() []const Snapshot`

Returns the snapshot history.

`formatLevelBreakdown(allocator: Allocator) ![]u8`

Returns a formatted string showing log counts by level.

Alias: levels, breakdown

Export

`exportMetrics(allocator: Allocator) ![]u8`

Exports metrics in the configured format.

`exportJson(allocator: Allocator) ![]u8`

Exports metrics as JSON format.

`exportPrometheus(allocator: Allocator) ![]u8`

Exports metrics as Prometheus exposition format.

`exportStatsd(allocator: Allocator) ![]u8`

Exports metrics as StatsD format.

Latency

`avgLatencyNs() u64`

Returns average latency in nanoseconds.

`minLatencyNs() u64`

Returns minimum latency in nanoseconds.

`maxLatencyNs() u64`

Returns maximum latency in nanoseconds.

`getHistogram() [20]u64`

Returns histogram bucket data.

`latencyPercentileNs(percentile: f64) u64`

Estimates latency percentile in nanoseconds using histogram buckets.

`latencyPercentileMs(percentile: f64) f64`

Estimates latency percentile in milliseconds.

`getLatencySummary() LatencySummary`

Returns aggregated latency values including min, max, avg, p50, p95, and p99.

Statistics

`totalRecordCount() u64`

Returns the total number of records logged.

`totalBytesLogged() u64`

Returns the total bytes written.

`errorCount() u64`

Returns the total error count.

`droppedCount() u64`

Returns the count of dropped records.

`errorRate() f64`

Returns the error rate (0.0 - 1.0).

`dropRate() f64`

Returns the drop rate (0.0 - 1.0).

`rate() f64`

Returns records per second throughput.

`bytesPerSecond() f64`

Returns bytes per second throughput.

Alias: throughput

`uptime() i64`

Returns uptime in milliseconds.

`uptimeSeconds() f64`

Returns uptime in seconds.

Alias: uptimeSec

`levelCount(level: Level) u64`

Returns the count for a specific log level.

`sinkCount() usize`

Returns the number of sinks being tracked.

`totalSinkErrors() u64`

Returns total sink write errors across all tracked sinks.

`totalSinkFlushes() u64`

Returns total sink flush count across all tracked sinks.

`lastRecordAgeMs() ?i64`

Returns age in milliseconds since the last recorded log entry, or null when no record has been logged yet.

State

`hasRecords() bool`

Returns true if any records have been logged.

`hasErrors() bool`

Returns true if any errors have occurred.

`hasDropped() bool`

Returns true if any records have been dropped.

`hasHighErrorRate(threshold: f64) bool`

Returns true if error rate exceeds the threshold.

`hasHighDropRate(threshold: f64) bool`

Returns true if drop rate exceeds the threshold.

`reset() void`

Resets all metrics to zero.

Alias: clear

Presets

MetricsPresets

zig

pub const MetricsPresets = struct {
    /// Creates a basic metrics instance.
    pub fn basic(allocator: std.mem.Allocator) Metrics;
    
    /// Creates a metrics sink configuration.
    pub fn createMetricsSink(file_path: []const u8) SinkConfig;
};

Example

zig

const Metrics = @import("logly").Metrics;

// Initialize
var metrics = Metrics.init(allocator);
defer metrics.deinit();

// Record logs
metrics.recordLog(.info, 256);
metrics.recordLog(.err, 512);

// Check statistics
const snapshot = metrics.getSnapshot();
std.debug.print("Records: {d}\n", .{snapshot.total_records});
std.debug.print("Rate: {d:.2} rec/s\n", .{snapshot.records_per_second});

// Check health
if (metrics.hasHighErrorRate(0.01)) {
    std.debug.print("Warning: High error rate!\n", .{});
}

// Get level breakdown
const breakdown = try metrics.formatLevelBreakdown(allocator);
defer allocator.free(breakdown);
std.debug.print("{s}\n", .{breakdown});

// Reset if needed
metrics.reset();

Performance

Lock-free: All hot paths use atomic operations
Low overhead: ~1-2% CPU for enabled metrics
Thread-safe: Safe for concurrent access from multiple threads
Batch updates: Reduces contention in high-throughput scenarios

Metrics API ​

Quick Reference: Method Aliases ​

Overview ​

Types ​

Metrics ​

MetricType ​

ErrorEvent ​

SinkMetrics ​

Getter Methods ​

Boolean Checks ​

Rate Calculations ​

Reset ​

Snapshot ​

Methods ​

Initialization ​

init(allocator: std.mem.Allocator) Metrics ​

initWithConfig(allocator: std.mem.Allocator, config: MetricsConfig) Metrics ​

deinit(self: *Metrics) void ​

Callbacks ​

setRecordLoggedCallback(callback: *const fn (Level, u64) void) void ​

setSnapshotCallback(callback: *const fn (*const Snapshot) void) void ​

setThresholdCallback(callback: *const fn (MetricType, u64, u64) void) void ​

setErrorCallback(callback: *const fn (ErrorEvent, u64) void) void ​

Configuration ​

getConfig() MetricsConfig ​

isEnabled() bool ​

Recording ​

recordLog(level: Level, bytes: u64) void ​

recordLogWithLatency(level: Level, bytes: u64, latency_ns: u64) void ​

recordDrop() void ​

recordError() void ​

recordCustomLog(bytes: u64) void ​

Sink Tracking ​

addSink(name: []const u8) !usize ​

recordSinkWrite(sink_index: usize, bytes: u64) void ​

recordSinkError(sink_index: usize) void ​

recordSinkFlush(sink_index: usize) void ​

getSinkMetrics(sink_index: usize) ?SinkMetrics ​

getSinkMetricsByName(name: []const u8) ?SinkMetrics ​

Snapshots ​

getSnapshot() Snapshot ​

takeSnapshot() !Snapshot ​

getHistory() []const Snapshot ​

formatLevelBreakdown(allocator: Allocator) ![]u8 ​

Export ​

exportMetrics(allocator: Allocator) ![]u8 ​

exportJson(allocator: Allocator) ![]u8 ​

exportPrometheus(allocator: Allocator) ![]u8 ​

exportStatsd(allocator: Allocator) ![]u8 ​

Latency ​

avgLatencyNs() u64 ​

minLatencyNs() u64 ​

maxLatencyNs() u64 ​

getHistogram() [20]u64 ​

latencyPercentileNs(percentile: f64) u64 ​

latencyPercentileMs(percentile: f64) f64 ​

getLatencySummary() LatencySummary ​

Statistics ​

totalRecordCount() u64 ​

totalBytesLogged() u64 ​

errorCount() u64 ​

droppedCount() u64 ​

errorRate() f64 ​

dropRate() f64 ​

rate() f64 ​

bytesPerSecond() f64 ​

uptime() i64 ​

uptimeSeconds() f64 ​

levelCount(level: Level) u64 ​

sinkCount() usize ​

totalSinkErrors() u64 ​

totalSinkFlushes() u64 ​

lastRecordAgeMs() ?i64 ​

State ​

hasRecords() bool ​

hasErrors() bool ​

hasDropped() bool ​

hasHighErrorRate(threshold: f64) bool ​

hasHighDropRate(threshold: f64) bool ​

reset() void ​