inklog 0.1.5 - Docs.rs

🎯 A high-performance, secure, and feature-rich logging infrastructure built on Tokio

Inklog provides a comprehensive logging solution for enterprise applications:

⚡ High Performance	🔒 Security First	🌐 Multi-Target	📊 Observability
Async I/O with Tokio	AES-256-GCM encryption	Console, File, DB	Health monitoring
Batch writes & compression	Zeroized secret memory	Automatic rotation	Metrics & tracing

use inklog::{InklogConfig, LoggerManager};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = InklogConfig {
        file_sink: Some(inklog::FileSinkConfig {
            enabled: true,
            path: "logs/app.log".into(),
            max_size: "100MB".into(),
            compress: true,
            ..Default::default()
        }),
        ..Default::default()
    };

    let _logger = LoggerManager::with_config(config).await?;

    log::info!("Application started successfully");
    log::error!("Something went wrong with error details");

    Ok(())
}

✨ Features

🎯 Core Features	⚡ Enterprise Features
Always Available	Optional

🎯 Core Features (Always Available)

Status	Feature	Description
✅	Async I/O	Tokio-powered non-blocking logging
✅	Multi-Target Output	Console, file, database, custom sinks
✅	Structured Logging	tracing ecosystem integration
✅	Custom Formatting	Template-based log format
✅	File Rotation	Size-based and time-based rotation
✅	Data Masking	Regex-based PII redaction
✅	Health Monitoring	Sink status and metrics tracking
✅	CLI Tools	decrypt, generate, validate commands

⚡ Enterprise Features

Status	Feature	Description
🔍	Compression	ZSTD, GZIP, Brotli, LZ4 support (`zstd`, `flate2`, etc.)
🔒	Encryption	AES-256-GCM file encryption (`aes-gcm`)
🗄️	Database Sink	PostgreSQL, MySQL, SQLite via Sea-ORM
📊	Parquet Export	Analytics-ready log format (always available)
🌐	HTTP Endpoint	Axum-based health check server (`http` feature)
🔧	CLI Tools	Utility commands for log management (`cli` feature)

📦 Feature Presets

Preset	Features	Use Case
minimal	No optional features	Core logging only
standard	`http`, `cli`	Standard development setup
full	All default features	Production-ready logging

🚀 Quick Start

📦 Installation

Add this to your Cargo.toml:

[dependencies]
inklog = "0.1"

For full feature set:

[dependencies]
inklog = { version = "0.1", features = ["default"] }

💡 Basic Usage

🎬 5-Minute Quick Start

Step 1: Initialize Logger

use inklog::LoggerManager;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _logger = LoggerManager::new().await?;

    log::info!("Logger initialized");
    Ok(())
}

Step 2: Log Messages

use inklog::LoggerManager;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _logger = LoggerManager::new().await?;

    log::trace!("Trace message");
    log::debug!("Debug message");
    log::info!("Info message");
    log::warn!("Warning message");
    log::error!("Error message");

    Ok(())
}

Step 3: File Logging

use inklog::{FileSinkConfig, InklogConfig, LoggerManager};

let config = InklogConfig {
    file_sink: Some(FileSinkConfig {
        enabled: true,
        path: "logs/app.log".into(),
        max_size: "10MB".into(),
        rotation_time: "daily".into(),
        keep_files: 7,
        compress: true,
        ..Default::default()
    }),
    ..Default::default()
};

let _logger = LoggerManager::with_config(config).await?;

Step 4: Database Logging

use inklog::{DatabaseSinkConfig, InklogConfig};

let config = InklogConfig {
    database_sink: Some(DatabaseSinkConfig {
        enabled: true,
        url: "sqlite://logs/app.db".to_string(),
        pool_size: 5,
        batch_size: 100,
        flush_interval_ms: 1000,
        ..Default::default()
    }),
    ..Default::default()
};

let _logger = LoggerManager::with_config(config).await?;

🔧 Advanced Configuration

Encrypted File Logging

use inklog::{FileSinkConfig, InklogConfig};

// Set encryption key from environment
std::env::set_var("INKLOG_ENCRYPTION_KEY", "base64-encoded-32-byte-key");

let config = InklogConfig {
    file_sink: Some(FileSinkConfig {
        enabled: true,
        path: "logs/encrypted.log.enc".into(),
        max_size: "10MB".into(),
        encrypt: true,
        encryption_key_env: Some("INKLOG_ENCRYPTION_KEY".into()),
        compress: false, // Don't compress encrypted logs
        ..Default::default()
    }),
    ..Default::default()
};

let _logger = LoggerManager::with_config(config).await?;

Custom Log Format

use inklog::{InklogConfig, config::GlobalConfig};

let format_string = "[{timestamp}] [{level:>5}] {target} - {message} | {file}:{line}";

let config = InklogConfig {
    global: GlobalConfig {
        level: "debug".into(),
        format: format_string.to_string(),
        masking_enabled: true,
        ..Default::default()
    },
    ..Default::default()
};

let _logger = LoggerManager::with_config(config).await?;

🎨 Feature Flags

Default Features

inklog = "0.1"  # Includes: http, cli

Optional Features

# HTTP Server
inklog = { version = "0.1", features = [
    "http",       # Axum HTTP health endpoint
] }

# CLI Tools
inklog = { version = "0.1", features = [
    "cli",        # decrypt, generate, validate commands
] }

# Database Sinks (pick one or more)
inklog = { version = "0.1", features = [
    "sqlite",     # SQLite database sink
    "postgres",   # PostgreSQL database sink
    "mysql",      # MySQL database sink
] }

# Development
inklog = { version = "0.1", features = [
    "test-local", # Local testing mode
    "debug",     # Additional security audit logging
] }

Feature Details

Feature	Dependencies	Description
http	axum	HTTP health check endpoint
cli	clap, glob	Command-line utilities
sqlite	dbnexus, sea-orm	SQLite database sink
postgres	dbnexus, sea-orm	PostgreSQL database sink
mysql	dbnexus, sea-orm	MySQL database sink
duckdb	dbnexus, sea-orm	DuckDB backend (only for `--all-features` testing; DatabaseSink does not directly support duckdb driver)
test-local	-	Local testing mode
debug	-	Security audit logging
metrics	-	Health metrics collection
kit	trait-kit, dbnexus, oxcache	Dependency injection kit integration

📚 Documentation

📖 Additional Resources

Resource	Description
📘 API Reference	Complete API documentation on docs.rs
🏗️ Architecture	System architecture and design decisions
🔒 Security	Security best practices and features
📦 Examples	Working code examples for all features

💻 Examples

💡 Real-world Examples

📝 Basic Logging

use inklog::LoggerManager;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _logger = LoggerManager::new().await?;

    log::info!("Application started");
    log::error!("An error occurred: {}", err);

    Ok(())
}

📁 File Logging with Rotation

use inklog::{FileSinkConfig, InklogConfig, LoggerManager};

let config = InklogConfig {
    file_sink: Some(FileSinkConfig {
        enabled: true,
        path: "logs/app.log".into(),
        max_size: "10MB".into(),
        rotation_time: "daily".into(),
        keep_files: 7,
        compress: true,
        ..Default::default()
    }),
    ..Default::default()
};

let _logger = LoggerManager::with_config(config).await?;

🔒 Encrypted Logging

use inklog::{FileSinkConfig, InklogConfig};

std::env::set_var("INKLOG_ENCRYPTION_KEY", "base64-encoded-key");

let config = InklogConfig {
    file_sink: Some(FileSinkConfig {
        enabled: true,
        path: "logs/encrypted.log".into(),
        encrypt: true,
        encryption_key_env: Some("INKLOG_ENCRYPTION_KEY".into()),
        ..Default::default()
    }),
    ..Default::default()
};

let _logger = LoggerManager::with_config(config).await?;

🗄️ Database Logging

use inklog::{DatabaseSinkConfig, InklogConfig};

let config = InklogConfig {
    database_sink: Some(DatabaseSinkConfig {
        enabled: true,
        url: "postgresql://localhost/logs".to_string(),
        pool_size: 10,
        batch_size: 100,
        flush_interval_ms: 1000,
        ..Default::default()
    }),
    ..Default::default()
};

let _logger = LoggerManager::with_config(config).await?;

🏥 HTTP Health Endpoint

use axum::{routing::get, Json, Router};
use inklog::LoggerManager;
use std::sync::Arc;

let logger = Arc::new(LoggerManager::new().await?);

let app = Router::new().route(
    "/health",
    get({
        let logger = logger.clone();
        || async move { Json(logger.get_health_status()) }
    }),
);

// Start HTTP server...

🎨 Custom Format

use inklog::{InklogConfig, config::GlobalConfig};

let format_string = "[{timestamp}] [{level:>5}] {target} - {message}";

let config = InklogConfig {
    global: GlobalConfig {
        level: "debug".into(),
        format: format_string.to_string(),
        masking_enabled: true,
        ..Default::default()
    },
    ..Default::default()
};

let _logger = LoggerManager::with_config(config).await?;

🔍 Data Masking

use inklog::{InklogConfig, config::GlobalConfig};

let config = InklogConfig {
    global: GlobalConfig {
        level: "info".into(),
        format: "{timestamp} {level} {message}".to_string(),
        masking_enabled: true,  // Enable PII masking
        ..Default::default()
    },
    ..Default::default()
};

let _logger = LoggerManager::with_config(config).await?;

// Sensitive data will be automatically masked
log::info!("User email: user@example.com");
// Output: User email: ***@***.***

📦 Runnable Examples

The examples/ crate provides 10 dedicated examples demonstrating specific features. Run them with cargo run --example <name> (from the examples/ directory or with --package inklog-examples).

Example	Description	Run Command
`object_pool`	Object pool reuse for allocation-heavy paths	`cargo run --example object_pool`
`path_validator`	Path validation for safe file sink targets	`cargo run --example path_validator`
`log_sanitizer`	Log input sanitization to prevent log injection	`cargo run --example log_sanitizer`
`log_adapter`	Bridging `log` and `tracing` ecosystems	`cargo run --example log_adapter`
`compression`	File sink compression (ZSTD/GZIP/Brotli/LZ4)	`cargo run --example compression`
`rotation`	Size-based and time-based file rotation	`cargo run --example rotation`
`ring_buffered_file`	Ring-buffered file sink for high throughput	`cargo run --example ring_buffered_file`
`config_file`	TOML configuration file loading	`cargo run --example config_file`
`metrics`	Health metrics and Prometheus export	`cargo run --example metrics`
`circuit_breaker`	Sink circuit breaker and failure recovery	`cargo run --example circuit_breaker`

📂 View all examples →

Note: inklog-examples is now part of the workspace.

🏗️ Architecture

🏗️ System Architecture

flowchart TD
    App["Application Layer<br/>(Your code using log! macros)"]
    API["Inklog API Layer<br/>- LoggerManager, LoggerBuilder<br/>- Configuration management<br/>- Health monitoring"]
    Sink["Sink Abstraction Layer<br/>- ConsoleSink<br/>- FileSink (rotation, compression)<br/>- DatabaseSink (batch writes)<br/>- AsyncFileSink<br/>- RingBufferedFileSink"]
    Core["Core Processing Layer<br/>- Log formatting & templates<br/>- Data masking (PII redaction)<br/>- Encryption (AES-256-GCM)<br/>- Compression (ZSTD, GZIP, Brotli)"]
    IO["Concurrency & I/O<br/>- Tokio async runtime<br/>- Crossbeam channels<br/>- Rayon parallel processing"]
    Store["Storage & External Services<br/>- Filesystem<br/>- Database (PostgreSQL, MySQL, SQLite)<br/>- Parquet (analytics)"]

    App --> API --> Sink --> Core --> IO --> Store

Layer-by-Layer Explanation

Application Layer

Application code uses standard log! macros from the log crate
Compatible with existing Rust logging patterns

Inklog API Layer

LoggerManager: Main orchestrator for all logging operations
LoggerBuilder: Fluent builder pattern for configuration
Health status tracking and metrics collection

Sink Abstraction Layer

Multiple sink implementations for different output targets
Console output for development
File output with rotation, compression, and encryption
Database output with batch writes (PostgreSQL, MySQL, SQLite)
Async and buffered file sinks for high-throughput scenarios

Core Processing Layer

Template-based log formatting
Regex-based PII data masking (emails, SSNs, credit cards)
AES-256-GCM encryption for sensitive logs
Multiple compression algorithms (ZSTD, GZIP, Brotli, LZ4)

Concurrency & I/O Layer

Tokio async runtime for non-blocking I/O
Crossbeam channels for inter-task communication
Rayon for CPU-intensive parallel processing

Storage & External Services Layer

Local filesystem access
Database connectivity via Sea-ORM
Parquet format for analytics workflows

🔒 Security

🛡️ Security Features

Inklog is built with security as a top priority:

🔒 Encryption

AES-256-GCM: Military-grade encryption for log files
Key Management: Environment variable-based key injection
Zeroized Memory: Secrets are securely cleared after use via zeroize crate
SHA-256 Hashing: Integrity verification for encrypted logs

🎭 Data Masking

Regex-Based Patterns: Automatic PII detection and redaction
Email Masking: user@example.com → ***@***.***
SSN Masking: Credit card and social security number redaction
Custom Patterns: Configurable regex patterns for sensitive data

🔐 Secure Key Handling

// Set encryption key securely from environment
std::env::set_var("INKLOG_ENCRYPTION_KEY", "base64-encoded-32-byte-key");

// Key is automatically zeroized after use
// Never hardcode keys in your application

🛡️ Security Best Practices

No hardcoded secrets: Keys loaded from environment variables
Minimal privileged operations: Only necessary file/database access
Audit logging: Debug feature for security audit trails
Compliance-ready: Supports GDPR, HIPAA, PCI-DSS logging requirements

🧪 Testing

🎯 Run Tests

# Run all tests with default features
cargo test --all-features

# Run tests with specific features
cargo test --features "http,cli"

# Run tests in release mode
cargo test --release

# Run benchmarks
cargo bench

Test Coverage

Inklog targets 95%+ code coverage:

# Generate coverage report
cargo tarpaulin --out Html --all-features

Linting and Formatting

# Format code
cargo fmt --all

# Check formatting without changes
cargo fmt --all -- --check

# Run Clippy (warnings as errors)
cargo clippy --all-targets --all-features -- -D warnings

Security Audit

# Run cargo deny for security checks
cargo deny check

# Check for advisories
cargo deny check advisories

# Check for banned licenses
cargo deny check bans

Dependency Injection Testing

Inklog provides Mock implementations for unit testing without external dependencies:

use inklog::{LoggerManager, LoggerDependencies};
use inklog::infrastructure::{MockCache, MockConfig, MockDatabaseAdapter};
use std::sync::Arc;

#[tokio::test]
async fn test_with_mocks() -> Result<(), Box<dyn std::error::Error>> {
    // Create Mock dependencies
    let deps = LoggerDependencies {
        cache: Some(Arc::new(MockCache::new())),
        config: Some(Arc::new(MockConfig::new())),
        database: Some(Arc::new(MockDatabaseAdapter::new())),
    };

    // Inject dependencies to create logger
    let logger = LoggerManager::with_dependencies(deps).await?;

    // Test logging...
    log::info!("Test message");

    Ok(())
}

Mock Implementations:

MockCache: In-memory HashMap with delay simulation
MockConfig: Runtime-modifiable configuration
MockDatabaseAdapter: In-memory log storage with health state control

See User Guide for detailed usage.

Integration Tests

# Run integration tests
cargo test --test '*'

# Run with Docker services (PostgreSQL, MySQL)
docker-compose up -d
cargo test --all-features
docker-compose down

🤝 Contributing

Contributions are welcome! 详见 CONTRIBUTING.md

Development Setup

# Clone repository
git clone https://github.com/Kirky-X/inklog.git
cd inklog

# Install pre-commit hooks (if available)
./scripts/install-pre-commit.sh

# Run tests
cargo test --all-features

# Run linter
cargo clippy --all-features

# Format code
cargo fmt --all