Package cloud.opencode.base.log.enhance

package cloud.opencode.base.log.enhance
Enhanced Logging - Advanced Logging Features 增强日志 - 高级日志功能

This package provides enhanced logging capabilities including structured JSON logging, data masking, and sampled logging.

本包提供增强的日志功能，包括结构化 JSON 日志、数据脱敏和采样日志。

Key Classes | 核心类

Structured Logging | 结构化日志

StructuredLog.info()
    .message("User login successful")
    .field("userId", "user123")
    .field("ip", "192.168.1.1")
    .field("duration", 150)
    .traceId("abc-123")
    .log();

// Output: {"message":"User login successful","traceId":"abc-123",
//          "userId":"user123","ip":"192.168.1.1","duration":150}

Data Masking | 数据脱敏

// Predefined masking strategies
LogMasking.mask("13812345678", MaskingStrategy.PHONE);    // 138****5678
LogMasking.mask("test@example.com", MaskingStrategy.EMAIL); // t***@example.com
LogMasking.mask("110101199001011234", MaskingStrategy.ID_CARD); // 110***********1234
LogMasking.mask("secret123", MaskingStrategy.PASSWORD);    // [PROTECTED]

// Register field-based masking
LogMasking.registerRule("phone", MaskingStrategy.PHONE);
LogMasking.registerRule("password", MaskingStrategy.PASSWORD);
String masked = LogMasking.maskByField("phone", "13812345678");

Sampled Logging | 采样日志

// Probability-based: 1% of messages
SampledLogger sampled = SampledLog.sample(0.01);
sampled.info("High frequency event: {}", eventId);

// Time-based: at most once per 5 seconds
SampledLogger rateLimited = SampledLog.sampleByTime(Duration.ofSeconds(5));
rateLimited.warn("Rate limited warning");

// Count-based: every 100th message
SampledLogger countBased = SampledLog.sampleByCount(100);
countBased.debug("Processing item {}", itemId);

Masking Strategies | 脱敏策略

  • FULL - Complete masking: ******
  • PHONE - Phone number: 138****5678
  • EMAIL - Email: u***@example.com
  • ID_CARD - ID card: 110***********1234
  • BANK_CARD - Bank card: ************1234
  • PASSWORD - Password: [PROTECTED]
  • NAME - Name: 张*三
  • ADDRESS - Address: 北京市海淀区****
Since:
JDK 25, opencode-base-log V1.0.0
Author:
OpenCode Cloud Group
See Also:
  • Class
    Description
    ConditionalLog
    Conditional Logging - Environment and Rate-based Logging 条件日志 - 基于环境和速率的日志
    ConditionalLog.ConditionalLogger
    Logger that only logs when a condition is true 仅在条件为真时记录日志的日志器
    ConditionalLog.OnceLogger
    Logger that logs only once per call site 每个调用点只记录一次的日志器
    ConditionalLog.RateLimitedLogger
    Logger that logs at most once per specified duration 每个指定时间段最多记录一次的日志器
    ExceptionLog
    Exception Logging Enhancement - Smart Exception Logging 异常日志增强 - 智能异常日志
    LogMasking
    Log Masking - Sensitive Data Masking Utility 日志脱敏 - 敏感数据脱敏工具
    LogMasking.Mask
    Annotation for marking fields that should be masked in logs.
    LogMasking.MaskingStrategy
    Masking strategies for different data types.
    LogMetrics
    Log Metrics - Logging with Built-in Metrics Collection 日志指标 - 带内置指标收集的日志
    LogMetrics.LogStats
    Log Statistics Snapshot 日志统计快照
    LogMetrics.TimingStats
    Timing Statistics 计时统计
    SampledLog
    Sampled Log - Rate-limited and Sampled Logging 采样日志 - 限流和采样的日志
    SampledLog.SampledLogger
    Sampled Logger Interface.
    ScopedLogContext
    Scoped Log Context - JDK 25+ ScopedValue-based Context 作用域日志上下文 - 基于 JDK 25+ ScopedValue 的上下文
    ScopedLogContext.Carrier
    Carrier for binding multiple values and executing tasks 用于绑定多个值和执行任务的载体
    StructuredLog
    Structured Log - JSON-style Structured Logging 结构化日志 - JSON 风格的结构化日志
    StructuredLog.Builder
    Structured Log Builder.
    VirtualThreadContext
    Virtual Thread Context Propagation - JDK 25+ 虚拟线程上下文传播 - JDK 25+