# logback-disruptor-appender

**Repository Path**: myprofile/logback-disruptor-appender

## Basic Information

- **Project Name**: logback-disruptor-appender
- **Description**: Support for asynchronous Logback appender,using disruptor implements
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2022-04-12
- **Last Updated**: 2026-02-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Logback Disruptor Appender

基于 LMAX Disruptor 的高性能异步 Logback Appender。

## 快速开始

### XML 配置示例

```xml
<?xml version="1.0" encoding="utf-8" ?>
<configuration>

    <!-- 定义日志格式 -->
    <property name="CONSOLE_LOG_PATTERN"
              value="%red(%d{yyyy-MM-dd HH:mm:ss}) %green([%thread])|-%highlight(%-5level) %boldMagenta(%logger{50})-%cyan(%msg%n)"/>

    <!-- 1. 定义实际输出的 Appender (如 ConsoleAppender) -->
    <appender name="consoleLog" class="ch.qos.logback.core.ConsoleAppender">
        <layout class="ch.qos.logback.classic.PatternLayout">
            <pattern>${CONSOLE_LOG_PATTERN}</pattern>
        </layout>
    </appender>

    <!-- 2. 定义 Disruptor 异步 Appender -->
    <appender name="disruptorAsyncAppender" class="com.lhstack.logback.disruptor.DisruptorAsyncAppender">
        <!-- 引用实际的一个或多个 Appender -->
        <appender-ref ref="consoleLog"/>
        
        <!-- 环形队列大小 (必须是 2 的幂次方, 默认 1024) -->
        <!-- 如果生成速度超过消费速度，RingBuffer 满时会根据 WaitStrategy 阻塞或自旋 -->
        <ringBufferSize>1024</ringBufferSize>

        <!-- 等待策略 (默认: SleepingWaitStrategy) -->
        <!-- 详见下文 "等待策略说明" -->
        <waitStrategy>SleepingWaitStrategy</waitStrategy>
        
        <!-- 线程拒绝策略 (默认: CallerRunsPolicy - 当队列满或线程池关闭时由调用线程执行) -->
        <threadRejectStrategy>CallerRunsPolicy</threadRejectStrategy>
    </appender>

    <root level="info">
        <appender-ref ref="disruptorAsyncAppender"/>
    </root>
</configuration>
```

## 等待策略说明 (WaitStrategy)

`waitStrategy` 决定了当没有日志事件处理时，消费者线程如何等待。这直接影响 **CPU 资源占用** 和 **日志延迟**。

| 策略名称 | 中文说明 | 适用场景 | 备注 |
| :--- | :--- | :--- | :--- |
| `SleepingWaitStrategy` | **休眠等待 (推荐)** | **大多数生产环境** | **默认值**。在性能和 CPU 资源之间取得最佳平衡。先自旋，不成功则 yield，最后 sleep。 |
| `BlockingWaitStrategy` | 阻塞等待 | 资源受限环境 | CPU 占用最低，但延迟最高。使用锁机制等待。 |
| `YieldingWaitStrategy` | 屈服等待 | 低延迟系统 | 延迟极低，但 CPU 占用较高（空闲时尝试 yield）。适合核心数充足的机器。 |
| `BusySpinWaitStrategy` | 忙自旋等待 | !!! 极度敏感 !!! | 延迟最低，但空闲时会**跑满一个 CPU 核心**。通常不推荐用于日志。 |
| `LiteBlockingWaitStrategy` | 轻量阻塞 | 通用 | 类似 Blocking，但在无竞争时尝试减少唤醒消耗。 |
| `PhasedBackoffWaitStrategy`| 阶段退避 | 复杂场景 | 自定义自旋 -> yield -> 阻塞的降级过程。 |

## 高级配置 (系统属性/System Properties)

可以通过 `-Dkey=value` 调整特定策略的参数：

### SleepingWaitStrategy (默认)
*   **`logback.disruptor.wait.sleeping.retries`**: 自旋次数 (默认: 200)
*   **`logback.disruptor.wait.sleeping.sleepTimeNs`**: 睡眠时间(纳秒) (默认: 100)

### PhasedBackoffWaitStrategy
*   **`logback.disruptor.wait.phased.spin.timeout`**: 自旋超时(秒) (默认: 3)
*   **`logback.disruptor.wait.phased.yield.timeout`**: Yield 超时(秒) (默认: 1)
*   **`logback.disruptor.wait.phased.fallback`**: 降级策略名称 (默认: YieldingWaitStrategy)

### LiteTimeoutBlockingWaitStrategy
*   **`logback.disruptor.wait.lite.timeout`**: 超时时间(秒) (默认: 15)

### TimeoutBlockingWaitStrategy
*   **`logback.disruptor.wait.timeout`**: 超时时间(秒) (默认: 15)
## DisruptorAsyncAppender 额外配置

以下为 `DisruptorAsyncAppender` 的 XML 字段配置：

- **`workerThreads`**（int，默认 1）：消费者线程数；当 `strictOrder=true` 时会被强制为 1。
- **`workerQueueCapacity`**（int，默认 1）：WorkerPool 线程池任务队列容量。
- **`overflowPolicy`**（BLOCK | DISCARD | SYNCHRONOUS，默认 BLOCK）：RingBuffer 满时的处理策略。
- **`strictOrder`**（boolean，默认 true）：严格顺序；开启后所有 appender 串行执行。
- **`shutdownTimeoutMillis`**（long，默认 30000）：停止时最大等待时间；0 表示立即 halt。
- **`slowAppenderThresholdMillis`**（long，默认 0）：慢 appender 监测阈值，>0 才启用。
- **`slowAppenderMaxCount`**（int，默认 3）：连续慢次数达到后自动 detach。
- **`slowAppenderWarnIntervalMillis`**（long，默认 30000）：慢 appender 告警最小间隔。
- **`slowAppenderStopOnDetach`**（boolean，默认 true）：自动 detach 时是否 stop。

注意事项：
- 严格顺序意味着 **所有 appender 串行执行**，其中任一 appender 慢会阻塞整条链路。
- 慢检测只能在 `doAppend` 返回后生效，无法中断卡死的 appender。