ShedLock으로 다중 인스턴스 환경에서 단일 스케줄러 동작 보장하기

개요

스프링에서 제공하는 @EnableScheduling 어노테이션은 간편하게 스케줄링 작업을 설정할 수 있게 해 주지만, 다중 인스턴스 환경에서는 동일한 작업이 여러 번 실행될 수 있다는 문제가 존재합니다.

이 문제를 해결하기 위해선 다양한 방법이 있지만, ShedLock이라는 오픈소스 라이브러리를 사용하면 손쉽게 해결할 수 있습니다. ShedLock은 스프링 스케줄링과 함께 사용될 수 있으며, 여러 인스턴스가 동일한 스케줄링 작업을 동시에 실행하는 것을 방지해 줍니다. 

테스트 코드는 깃허브에서 확인하실 수 있습니다.

 

 

ShedLock 이해하기

ShedLock은 분산된 시스템 환경에서 동일한 스케줄링 작업이 중복으로 수행되는 것을 방지하는 라이브러리입니다. 이 라이브러리는 지정된 작업에 잠금 메커니즘을 적용하여, 해당 작업이 완전히 종료될 때까지 다른 인스턴스에서는 동일한 작업을 수행할 수 없게 합니다.

ShedLock의 내부 동작 방식은 다음과 같습니다:

1. 잠금 획득: ShedLock은 데이터베이스, Redis, Zookeeper 등의 외부 저장소를 사용하여 잠금 상태를 관리합니다. 스케줄링 작업이 실행되기 전에 ShedLock은 먼저 외부 저장소에서 해당 작업의 잠금 상태를 확인합니다. 만약 해당 작업에 대한 잠금이 이미 획득되어 있는 경우, 다른 인스턴스에서는 해당 작업을 수행하지 않습니다.
2. 잠금 유지: 스케줄링 작업이 시작되면, 잠금을 획득한 인스턴스는 작업을 수행합니다. 이때, ShedLock은 잠금을 유지하여 다른 인스턴스에서 동일한 작업을 중복으로 실행하지 못하도록 합니다. 잠금은 외부 저장소에 저장되며, 일정 시간 동안 유지됩니다.
3. 잠금 갱신: 스케줄링 작업의 실행 시간이 잠금의 유지 시간보다 길 경우, ShedLock은 잠금을 갱신하여 작업이 완료될 때까지 다른 인스턴스에서 작업을 수행하지 못하도록 합니다. 이를 통해 작업의 중복 실행을 방지합니다.
4. 잠금 해제: 스케줄링 작업이 완료되면, ShedLock은 잠금을 자동으로 해제합니다. 잠금은 외부 저장소에서 제거되어 다음 실행 주기에서 다른 인스턴스가 작업을 수행할 수 있게 됩니다.

ShedLock은 분산된 환경에서 스케줄링 작업의 중복 실행을 방지하여 시스템의 안정성과 일관성을 보장합니다. 외부 저장소를 사용하여 잠금 상태를 관리하므로, 여러 인스턴스 간에 잠금 정보를 공유할 수 있습니다. 이를 통해 동일한 작업이 중복으로 실행되는 것을 방지하고, 작업의 실행 순서와 일관성을 유지할 수 있습니다.

 

 

ShedLock 사용하기

ShedLock은 다양한 RDBMS, NOSQL, In-Memory DB 등 다양한 데이터베이스에서 사용될 수 있는데, 테스트는 MariaDB를 사용하는 환경에서 진행해 보겠습니다.

의존성 추가

Gradle에 아래 라이브러리를 추가합니다.

implementation 'net.javacrumbs.shedlock:shedlock-spring:5.10.0'
implementation 'net.javacrumbs.shedlock:shedlock-provider-jdbc-template:5.10.0'

lockProvider 정의

다음으로 Config를 설정합니다. 

@Configuration
@EnableScheduling
@EnableSchedulerLock(defaultLockAtMostFor = "PT30S")
public class ScheduleConfig implements SchedulingConfigurer {

    @Override
    public void configureTasks(ScheduledTaskRegistrar taskRegistrar) {
        ThreadPoolTaskScheduler scheduler = new ThreadPoolTaskScheduler();
        scheduler.setPoolSize(10);
        scheduler.setThreadNamePrefix("scheduled-task-pool-");
        scheduler.initialize();
        taskRegistrar.setTaskScheduler(scheduler);
    }

    @Bean
    public LockProvider lockProvider(DataSource dataSource) {
        return new JdbcTemplateLockProvider(
                JdbcTemplateLockProvider.Configuration.builder()
                        .withJdbcTemplate(new JdbcTemplate(dataSource))
                        .usingDbTime()
                        .build()
        );
    }
}

위의 코드에서 @EnableSchedulerLock(defaultLockAtMostFor = "PT30S")를 통해 ShedLock의 스케줄러 잠금 기능을 활성화하며, defaultLockAtMostFor는 기본 잠금의 최대 유지 시간을 설정합니다.

lockProvider는 ShedLock이 잠금 상태를 관리하는 데 사용되는 bean입니다. 여기서는 JdbcTemplateLockProvider를 사용하여 데이터베이스 연결을 관리하는 DataSource를 인자로 받습니다. 이를 통해 ShedLock은 데이터베이스를 이용하여 잠금 상태를 관리할 수 있습니다.

위에 적힌 설정 말고도 JdbcTemplateLockProvider에 들어갈 수 있는 옵션들은 아래와 같습니다.

• withJdbcTemplate(JdbcTemplate jdbcTemplate): JdbcTemplate 객체를 설정.
• usingDbTime(): 데이터베이스 서버의 시간을 사용하도록 설정. 이 옵션을 사용하면 애플리케이션 서버와 데이터베이스 서버 간의 시간 차이를 고려하지 않아도 된다.
• withLockId(String lockId): 잠금의 ID를 설정. 동일한 ID를 가진 잠금은 동일한 레코드를 사용.
• withColumnNames(ColumnNameProvider columnNames): 사용할 테이블의 컬럼 이름을 설정. ColumnNameProvider 인터페이스를 구현하여 사용.
• usingDbTime(ZoneId zone): 데이터베이스 서버의 시간대를 설정. 이 옵션은 usingDbTime()와 같이 사용되지만, 특정 시간대를 설정할 수 있다.
• withTimeZone(TimeZone timeZone): 데이터베이스의 시간대를 설정.
• withTableName(String tableName): 잠금을 저장할 테이블 이름을 설정.
• withIsolationLevel(IsolationLevel isolationLevel): 트랜잭션 격리 수준을 설정.
• withTransactionManager(PlatformTransactionManager transactionManager): 트랜잭션 관리자를 설정.

@SchedulerLock 설정

@Slf4j
@Component
public class Scheduling {
    @Scheduled(cron = "*/5 * * * * *")
    @SchedulerLock(name = "scheduled1", lockAtMostFor = "PT2S", lockAtLeastFor = "PT2S")
    public void schedule2() {
        log.info("Scheduled task executed at {}", LocalDateTime.now());
    }
    
    @Scheduled(cron = "*/5 * * * * *")
    @SchedulerLock(name = "scheduled2", lockAtMostFor = "PT2S", lockAtLeastFor = "PT2S")
    public void schedule2() {
        log.info("Scheduled task executed at {}", LocalDateTime.now());
    }
    
    @Scheduled(cron = "*/5 * * * * *")
    @SchedulerLock(name = "scheduled3", lockAtMostFor = "PT2S", lockAtLeastFor = "PT2S")
    public void schedule3() {
        log.info("Scheduled task executed at {}", LocalDateTime.now());
    }
}

위의 코드는 @Scheduled와 @SchedulerLock 어노테이션을 사용하여 스케줄링 작업을 정의한 예제입니다. @SchedulerLock 어노테이션에는 다음과 같은 속성들이 있습니다.

• name (필수): 잠금의 이름을 지정합니다. 같은 이름을 가진 잠금은 동일한 레코드를 사용하며, 고유해야 합니다.
• lockAtMostFor (필수): 잠금이 최대로 유지되는 시간을 지정합니다. 이 시간 이후에는 잠금이 자동으로 해제되며, 이 속성은 'PT30S', '10m', '2h' 등의 ISO 8601 형식의 문자열을 사용하여 지정합니다. 이 값은 반드시 작업의 예상 최대 실행 시간보다 커야 하는데, 만약 작업이 이 시간을 초과하여 실행된다면, 다른 인스턴스에서 잠금을 획득하고 동일한 작업을 실행할 수 있습니다.
• lockAtLeastFor(선택): 잠금이 최소로 유지되는 시간을 지정합니다. 잠금이 획득된 후, 이 시간 이내에는 잠금이 해제되지 않으며, 이 속성 또한 ISO 8601 형식의 문자열을 사용하여 지정할 수 있습니다. 이 값을 설정하면, 작업이 빠르게 수행된 후에도 일정 시간 동안은 다른 인스턴스에서 동일한 작업이 실행되지 않도록 할 수 있습니다.
• mode(선택): 잠금 모드를 설정합니다. 기본값은 'IMMEDIATE'로, 이 모드에서는 잠금을 즉시 획득하려고 시도하는데, 만약 잠금을 획득하지 못하면 작업은 즉시 실패합니다. 다른 옵션으로는 'EAGER'가 있으며, 이 모드에서는 잠금을 획득하기 위해 지정된 시간 동안 대기합니다.

ShedLock 테이블 생성

-- MySQL, MariaDB
CREATE TABLE shedlock
(
    name       VARCHAR(64)  NOT NULL,
    lock_until TIMESTAMP(3) NOT NULL,
    locked_at  TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
    locked_by  VARCHAR(255) NOT NULL,
    PRIMARY KEY (name)
);

-- Postgres
CREATE TABLE shedlock
(
    name       VARCHAR(64)  NOT NULL,
    lock_until TIMESTAMP    NOT NULL,
    locked_at  TIMESTAMP    NOT NULL,
    locked_by  VARCHAR(255) NOT NULL,
    PRIMARY KEY (name)
);

-- Oracle
CREATE TABLE shedlock
(
    name       VARCHAR(64)  NOT NULL,
    lock_until TIMESTAMP(3) NOT NULL,
    locked_at  TIMESTAMP(3) NOT NULL,
    locked_by  VARCHAR(255) NOT NULL,
    PRIMARY KEY (name)
);

-- MS SQL
CREATE TABLE shedlock
(
    name      VARCHAR(64)  NOT NULL,
    lock_until datetime2 NOT NULL,
    locked_at datetime2 NOT NULL,
    locked_by VARCHAR(255) NOT NULL,
    PRIMARY KEY (name)
);

-- DB2
CREATE TABLE shedlock
(
    name       VARCHAR(64)  NOT NULL PRIMARY KEY,
    lock_until TIMESTAMP    NOT NULL,
    locked_at  TIMESTAMP    NOT NULL,
    locked_by  VARCHAR(255) NOT NULL
);

shedlock 데이터 확인

실제 shedlock의 데이터는 위와 같이 저장되는데, 여기서 중요한 사실은 ShedLock은 스케줄링 작업이 실행될 때마다 새로운 레코드를 생성하는 것이 아닌, 해당 작업의 잠금 레코드를 업데이트한다는 점입니다. 이는 데이터베이스의 부하를 줄이는 데 도움이 되며, 동시에 수행되는 작업을 효과적으로 관리할 수 있습니다.(따라서 작업의 실행 로그를 기록하려면 별도로 별도의 로깅 시스템을 구축하거나, 스케줄링 작업 내에서 로그를 기록하도록 코드를 작성해야 합니다.)

 

 

에러 해결 과정

여기부터는 제가 ShedLock을 적용하면서 겪었던 에러에 대해 정리합니다.

1. 의존성 버전 에러

버전 에러

프로젝트의 JDK 버전과 ShedLock 라이브러리의 빌드된 JDK 버전이 일치하지 않아 발생하는 에러입니다. 이 경우, 프로젝트의 JDK 버전에 맞는 ShedLock 라이브러리의 버전을 사용해야 합니다. 예를 들어, JDK 17 버전 이전을 사용하는 경우 ShedLock 라이브러리 v4.44.0을 사용해야 합니다. 이 정보는 ShedLock의 README의 VERSION 목차에서 확인할 수 있습니다.

JDK 버전에 따른 의존성 버전 확인

깃허브를 보면 JDK 17 버전 이전은 v4.44.0, 이후는 v5.1.0을 써야 한다고 명시되어 있습니다.

2. shedlock 테이블 찾을 수 없음

ERROR 14:15:00 [scheduled-task-1] n.j.s.p.j.JdbcTemplateStorageAccessor, insertRecord at line 73; Unexpected exception
org.springframework.jdbc.UncategorizedSQLException: PreparedStatementCallback; uncategorized SQLException for SQL [INSERT IGNORE INTO shedlock(name, lock_until, locked_at, locked_by) VALUES(?, TIMESTAMPADD(MICROSECOND, ?, UTC_TIMESTAMP(3)), UTC_TIMESTAMP(3), ?)]; SQL state [3D000]; error code [1046]; No database selected; nested exception is java.sql.SQLException: No database selected
	at org.springframework.jdbc.core.JdbcTemplate.translateException(JdbcTemplate.java:1542)
	at org.springframework.jdbc.core.JdbcTemplate.execute(JdbcTemplate.java:667)
	at org.springframework.jdbc.core.JdbcTemplate.update(JdbcTemplate.java:960)
	at org.springframework.jdbc.core.JdbcTemplate.update(JdbcTemplate.java:981)
...

데이터베이스가 shedlock 테이블을 찾지 못해 발생하는 에러입니다. 이 경우, DataSource 초기화 시에 스키마를 지정해 주어야 합니다. 예를 들어, jdbc:mysql://localhost:3306/my_schema와 같이 지정할 수 있습니다. 

하지만, 더 깔끔한 해결 방법은 ShedLock 설정에서 withTableName메서드를 사용하여 스키마와 테이블 이름을 지정하는 것입니다. 다음과 같이 설정할 수 있습니다.(공식문서의 Configure LockProvider 부분에 자세히 나와있습니다.)

    @Bean
    public LockProvider lockProvider(DataSource dataSource) {
        return new JdbcTemplateLockProvider(
                JdbcTemplateLockProvider.Configuration.builder()
                        .withTableName("schema.shedlock")
                        .withJdbcTemplate(new JdbcTemplate(dataSource))
                        .usingDbTime()
                        .build()
        );
    }

위 설정에서 "schema.shedlock"은 {스키마}.{테이블명}의 형태로 지정되어 있습니다. 이렇게 하면, 특정 스키마 내의 shedlock 테이블을 정확히 찾아 사용할 수 있습니다.