티스토리 뷰

Server

[Redis] Lettuce 라이브러리 내부 구성에 대한 이해 및 Connection is already closed 로그 발생 원인 분석

망나니개발자 2026. 9. 15. 10:00

 

 

1.Lettuce 라이브러리 내부 구성에 대한 이해와 
Connection is already closed 로그 발생 원인 분석


[ 레디스 클러스터 환경 ]

일반적으로 운영 환경에서는 레디스 클러스터를 사용한다. 클러스터 구조를 사용하면 데이터가 여러 서버에 쪼개져 관리된다. 키마다 슬롯 번호(0~16383)가 계산되고, 슬롯을 담당하는 서버가 정해져 있다. 그리고 각 마스터마다 복제본을 두어 마스터에 장애가 생기면 복제본을 승격시킨다. 참고로 클러스터는 이 페일오버를 자체적으로 처리하기 때문에 센티넬 구조와는 별개이다.

 

 

이 그림에서 가장 중요한 것은, 애플리케이션 서버가 마스터 노드와 실제적인 연결을 맺어야 한다는 것이다. 만약 마스터가 N개인 레디스 클러스터와 M개의 애플리케이션 서버를 구동하는 환경이라면, 각 애플리케이션 M개의 서버들이 N개의 레디스 마스터와 연결을 맺는다.

 

 

 

[ Lettuce의 커넥션 모델 ]

StatefulRedisConnectionImpl: 노드 커넥션

레디스 라이브러리를 사용하지 않는다면, Redis 서버 한 대에 명령을 보내기 위해 소켓을 열어 TCP 연결을 맺고, 요청을 쓰고, 읽는 작업 등을 직접 구현해야 한다. 하지만 우리는 Lettuce와 같은 레디스 라이브러리를 사용하기 때문에, 이런 코드를 직접 작성할 일이 없다.

val socket = Socket("redis-01", 6379)
socket.outputStream.write("SET user:1 hello\r\n".toByteArray())
val response = socket.inputStream.read()

 

 

이 정도는 할 수 있다고 생각하겠지만, 실제로 서비스에 이용하려면 이 정도로 부족하다. 최소한 이만큼이 더 필요하다.

  • 명령을 Redis 프로토콜 형식으로 바꾸는 인코더
  • 응답을 파싱하는 디코더
  • 여러 스레드가 동시에 이 소켓에 쓰려 할 때의 잠금
  • 응답을 기다리는 요청들의 큐 (보낸 순서대로 응답이 오므로 짝을 맞춰야 한다)
  • 연결이 끊겼을 때 재연결
  • 끊긴 동안 들어온 명령을 버릴지 쌓아둘지 정하는 정책

 

 

위의 여섯 가지를 소켓 하나에 딸려 다니게 묶어야 하는데, 이를 매번 개발자가 직접 구현하려면 번거롭다. 따라서 Lettuce 와 같은 레디스 클라이언트 라이브러리는 이를 묶어 노드 단위로 커넥션을 관리할 수 있는 노드 커넥션 클래스(StatefulRedisConnectionImpl)를 제공한다.

 

 

PooledClusterConnectionProvider: 노드 커넥션 모음

우리 서버가 3개의 노드 커넥션을 직접 다루려면 번거롭다. 따라서 3개의 커넥션을 한번에 관리해주면서, 슬롯 번호를 주면 그 슬롯 담당 노드 커넥션을 돌려주는 노드 커넥션 모음 클래스(PooledClusterConnectionProvider) 역시 존재한다. provider 컴포넌트는 내부에서 슬롯 번호를 기반으로 노드 커넥션에 바로 접근할 수 있도록 배열 16384칸을 잡아둔다. 그래서 슬롯 번호로 노드 커넥션을 O(1)에 찾는다.

// PooledClusterConnectionProvider:84, 86, 100
private final CompletableFuture<StatefulRedisConnection<K,V>> writers[] = new CompletableFuture[16384];
private final CompletableFuture<StatefulRedisConnection<K,V>> readers[][] = new CompletableFuture[16384][];
private final AsyncConnectionProvider<ConnectionKey, ...> connectionProvider;

 

 

실제로 레디스 클러스터 서버가 16384개가 되지는 않을 것이기에, 같은 마스터가 담당하는 슬롯 수천 개가 같은 커넥션 객체 하나를 가리킨다.

writers[1150]  ─┐
writers[3421]  ─┼─→ 커넥션 A   (redis-01:6379, WRITE)
writers[5000]  ─┘
writers[12494] ───→ 커넥션 B   (redis-03:6379, WRITE)

 

 

이러한 구조를 그림으로 표현하면 다음과 같다.

 

 

ClusterDistributionChannelWriter: 슬롯 계산기

이제 우리는 모든 요청을 provider 컴포넌트에게 슬롯 번호로 전달하기만 하면 된다. 따라서 이제 요청 명령을 슬롯 번호로 계산하는 작업이 필요한데, 이는 Writer 컴포넌트가 갖는다.

 

 

writer 컴포넌트는 다음과 같은 체인 구조로 되어 있다.

  ClusterDistributionChannelWriter   ← 슬롯 계산, 키가 있는 명령은 노드 커넥션으로 전달
    └ CommandListenerWriter          ← 명령 전후 리스너 호출
        └ CommandExpiryWriter        ← 명령 타임아웃 감시
            └ DefaultEndpoint        ← 클러스터 커넥션 자신의 소켓 쓰기 (키가 없는 명령)

 

 

실제 코드를 보면 여러 겹의 writer 컴포넌트를 체인 구조로 만들고, 이를 활용해 Provider 컴포넌트를 생성함을 알 수 있다.

 

 

참고로 writer 내부에서 슬롯을 계산할 때는 기본적으로 키를 CRC16 으로 해싱하고 16384로 나눈 나머지를 쓴다. 물론 키에 해시 태그({ })가 포함된 경우에는 중괄호 안쪽만 해싱하므로 결과가 달라지는데, 이는 나중에 알아보도록 하자.

 

 

이러한 방식은 서버와의 통신 필요 없이 클라이언트가 혼자 계산하는 구조이므로, 레디스 클라이언트 라이브러리 내부에 구현이 되어 있다.

 

 

StatefulRedisClusterConnectionImpl: 클러스터 커넥션

최종적으로는 사용할 API(동기, 비동기, 리액티브)를 제공하고, close()와 closeAsync(), isOpen() 등의 메서드를 통해 클러스터 커넥션의 생명주기를 관리하는 클러스터 커넥션인 StatefulRedisClusterConnectionImpl가 존재한다.

connection.sync()     // 동기
connection.async()    // 비동기
connection.reactive() // 리액티브

 

 

클러스터 커넥션은 요청 시에 명령을 Writer부터 최종 커넥션 객체에 전달하며, 종료할 때는 자신이 거느린 Writer 와 Provider 까지 함께 닫는 출발점이 된다. 물론 우리는 이보다 추상화된 RedisTemplate과 같은 spring-data-redis의 클래스를 사용할 것이다.

 

 

참고로 PING 처럼 키가 없는 명령은 어느 노드로 보내도 되니 슬롯 계산이 필요 없다. 이런 명령은 writer(ClusterDistributionChannelWriter)가 필드로 들고 있는 defaultWriter 로 보내지고, defaultWriter 가 쓰는 채널이 클러스터 커넥션 자신의 소켓이다.

 

 

RedisClusterClient: 커넥션을 만들고 정리하는 클라이언트

지금까지 본 클러스터 커넥션, writer, provider, 노드 커넥션은 모두 누군가가 만들어 줘야 한다. 이 역할을 하는 lettuce 클래스가 RedisClusterClient다. RedisClusterClient는 커넥션 자체가 아니라, 커넥션을 만들고 만든 것들을 기억해 뒀다가 종료할 때 한꺼번에 닫는 객체다.

  1. 서버가 뜨면 LettuceConnectionFactory 가 start() 에서 RedisClusterClient 를 하나 만든다. 이때 레디스 노드 주소, 이벤트 루프 스레드, 토폴로지 조회 주기 같은 설정을 넘겨받는다.
  2. 처음 connect() 를 부르면 임시 커넥션으로 슬롯 배치를 조회해 보관하고, 이후 설정한 주기(30초)마다 다시 조회한다.
  3. connect() 는 클러스터 커넥션과 writer, provider 를 만들어 돌려준다. 노드 커넥션도 결국 이 클라이언트가 만든다.
  4. 만든 객체는 closeableResources 에 등록해 둔다.
  5. 서버가 종료되면 팩토리가 dispose(client) 로 shutdown() 을 호출하고, 클라이언트는 목록을 돌며 남은 객체를 모두 닫는다.

 

// LettuceConnectionFactory 안에서 만든 클라이언트를 꺼내 쓸 수도 있다
val client = redisConnectionFactory.nativeClient as RedisClusterClient
val connection = client.connect(codec)

 

 

참고로 클러스터가 아닌 단일 레디스에 붙을 때는 RedisClient 를 쓴다. 두 클래스 모두 AbstractRedisClient 를 상속하므로, 클라이언트 객체마다 종료 목록을 따로 가진다.

 

 

 

[ 클러스터의 슬롯 배치를 위한 임시 커넥션 ]

레디스 클러스터는 언제든지 마스터 노드가 빠졌다가 투입되는 등의 행동이 일어날 수 있다. 또한 여러 노드들 중에서 어떠한 노드가 마스터이고, 어떤 노드가 어느 범위의 슬롯을 담당하는지는 레디스만이 알고 있다. 따라서 Lettuce 라이브러리는 클러스터의 슬롯 배치를 포함한 정보들을 획득하기 위한 임시 커넥션을 관리한다.

redis.cluster.nodes = redis-alpha1:6379, redis-alpha2:6379, ... (9개)

 

 

해당 정보는 서버가 처음 기동될 때 그리고 설정에 따라 주기적으로 임시 커넥션을 맺고 요청을 보내 알게 된다. 마스터가 페일오버로 바뀌거나 노드가 추가되는 것이 감지되는 주기와 동일하다.

redis.cluster.refreshPeriod=30

 

 

임시 커넥션을 통해서는 크게 2가지 명령을 보내게 된다.

 

 

슬롯 지도에는 노드 한 줄씩, 다음과 같은 형식으로 응답을 받아 클러스터 전체 구성표를 갖게 된다. 이를 통해 다음과 같은 정보들을 얻을 수 있다. Lettuce 는 이걸 파싱해서 Partitions 객체로 만들어 provider 컴포넌트가 사용하게 한다.

  • 어느 노드가 마스터이고 어느 노드가 복제본인지 (master / slave 플래그)
  • 복제본이 어느 마스터에 딸렸는지 (네 번째 칸의 마스터 ID)
  • 각 마스터가 어느 슬롯 범위를 담당하는지 (마지막 칸)
  • 노드가 살아 있는지 (connected / disconnected)

 

 

  <노드ID> <ip:port@버스포트> <플래그> <마스터ID> <ping> <pong> <에포크> <링크상태> <슬롯범위...>

  a1b2c3... 10.0.1.1:6379@16379 master        - 0 1699... 3 connected 0-5460
  d4e5f6... 10.0.1.2:6379@16379 slave  a1b2c3 0 1699... 3 connected
  g7h8i9... 10.0.2.1:6379@16379 master        - 0 1699... 4 connected 5461-10922

 

 

그 다음 노드 상태로는 여러 값들이 있지만, 2가지 값만을 사용한다.

  • 접속 클라이언트 수(connected_clients): 이 노드에 몇 개의 클라이언트가 붙어 있는지를 알려줌. 클러스터 커넥션이 최초 접속할 노드를 골라 부하를 분산시킴
  • 복제 오프셋(master_repl_offset): 복제가 어디까지 진행됐는지를 나타내는 위치값으로, 여러 노드의 응답이 엇갈릴 때 어느 것이 더 최신인지 판단하는 데 쓰임

 

 

해당 명령은 모든 노드에게 질의하게 되는데, 페일오버 중이면 어떤 노드는 옛 정보를, 어떤 노드는 새 정보를 갖고 있어, 노드마다 답이 다를 수 있기 때문이다. 전부에게 묻고 응답을 대조해서 가장 신뢰할 만한 것을 고르는 것이다. 그와 함께 응답 지연 시간도 함께 재서(TimedAsyncCommand), 나중에 노드를 지연 순으로 정렬할 때 사용한다.

 

 

[ Lettuce의 종료 목록 관리 ]

일반적으로 우리는 spring-data-redis가 제공하는 LettuceConnectionFactory를 통해 레디스 연결이 자동 구성된다. 그래서 내부적으로 Lettuce 클라이언트 연결 설정들이 자동으로 맺어진다.

Lettuce 클라이언트는 자신이 만든 연결들 중에서 “나중에 닫아야 할 것들”을 closeableResources라는 이름의 Set에 모아둔다. 이를 통해 종료 시점에 리소스 누수가 없도록 처리한다.

 

 

닫기 목록에 등록되는 경로는 크게 2가지다. 첫 번째는 레디스 커넥션이 연결에 성공한 직후 자기 자신을 등록하는 것이다. 이 코드는 채널 초기화 콜백 안에 있어서, 소켓을 여는 커넥션이면 종류를 가리지 않고 탄다. 우리에게는 클러스터 커넥션과 노드 커넥션이 있는데, 노드 커넥션은 마스터마다 하나씩, 클러스터 커넥션은 defaultWriter 가 쥔 소켓 하나를 갖고 있으므로 두 종류 모두 이 경로로 등록된다.

 

 

두 번째는 클러스터 커넥션이 만들어질 때, 나와 함께 종료될 짝꿍들을 등록하는 것이다. writer와 provider 컴포넌트가 종료 대상에 등록된다. 이 둘은 소켓을 직접 열지 않아 첫 번째 경로를 타지 못하지만, 정리해야 할 자원을 갖고 있다. provider는 노드 커넥션들을 보관하고 있고, writer는 defaultWriter 를 통해 소켓 하나를 쥐고 있기 때문이다.

 

 

참고로 노드 커넥션은 provider가 슬롯을 처음 요구하는 시점에 만들어져서, 초기화 이후에 closeableResources에 없을 수 있다. 따라서 종료 목록에는 일반적으로 다음의 것들이 들어가게 된다. 종료 목록은 Set 이므로 아래 나열 순서는 등록 순서나 닫는 순서와 관계없다.

StatefulRedisClusterConnectionImpl    클러스터 커넥션
ClusterDistributionChannelWriter      writer
PooledClusterConnectionProvider       provider
StatefulRedisConnectionImpl           노드 커넥션 (최대 마스터 수만큼)
StatefulRedisConnectionImpl
StatefulRedisConnectionImpl

 

 

하지만 우리가 레디스를 활용하는 새로운 도구가 필요한 경우, LettuceConnectionFactory를 통한 RedisTemplate 등을 이용하지 않고 Lettuce 라이브러리의 클라이언트 객체(RedisClusterClient)를 꺼내 직접 만드는 상황도 있다. 보통 이렇게 하는 이유는 LettuceConnectionFactory에 설정된 커넥션과 다른 코덱을 사용해야 하기 때문인데, 다음과 같이 LettuceConnectionFactory에서 클라이언트를 꺼내 직접 커넥션을 열게 된다.

val client = redisConnectionFactory.nativeClient as RedisClusterClient
val connection = client.connect(RedisCodec.of(StringCodec(), ByteArrayCodec()))

 

 

이렇게 직접 connect를 하게 되면, 같은 종료 목록(closeableResources) 하나에 다음 항목들이 함께 들어간다.

============ 스프링 자동 구성으로 등록된 항목 ==============
StatefulRedisClusterConnectionImpl    클러스터 커넥션
ClusterDistributionChannelWriter      writer
PooledClusterConnectionProvider       provider
StatefulRedisConnectionImpl           노드 커넥션 (최대 마스터 수만큼)
StatefulRedisConnectionImpl
StatefulRedisConnectionImpl
...

============ 직접 connect 로 등록된 항목 ==============
StatefulRedisClusterConnectionImpl    connect() 로 새로 만들어진 클러스터 커넥션
ClusterDistributionChannelWriter      함께 생성된 writer
PooledClusterConnectionProvider       함께 생성된 provider
StatefulRedisConnectionImpl           이 커넥션으로 명령이 나가면 만들어지는 노드 커넥션 (최대 마스터 수만큼)
StatefulRedisConnectionImpl
StatefulRedisConnectionImpl
...

 

 

[ Lettuce의 종료 처리 흐름 ]

LettuceConnectionFactory를 통해 등록된 커넥션들의 종료 흐름

서버가 종료 신호를 받으면 SpringApplicationShutdownHook 이 스프링 컨텍스트를 닫는다. 컨텍스트는 크게 두 단계로 빈을 정리한다. LettuceConnectionFactory 는 SmartLifecycle 을 구현하므로 첫 번째 단계에서 멈춘다.

SpringApplicationShutdownHook
  └ AbstractApplicationContext.doClose()
      ├ 1. lifecycleProcessor.onClose()   SmartLifecycle 을 구현한 빈을 멈춘다
      └ 2. destroyBeans()                 @PreDestroy, DisposableBean 을 호출한다

 

 

LettuceConnectionFactory는 RedisTemplate 들이 함께 쓰는 클러스터 커넥션을 직접 들고 있다. 이것을 공용 커넥션이라 부르며, 팩토리가 멈출 때는 다음의 종료 순서로 정리한다.

 

 

처음의 resetConnection()이 공용 커넥션을 닫으면, 클러스터 커넥션이 자신의 writer를 닫고, writer가 provider를, provider가 보관하던 노드 커넥션을 차례로 닫는다. 클러스터 커넥션이 닫힌 뒤에는 리스너들이 실행되어 closeableResources 에서 클러스터 커넥션, writer, provider 를 제거한다. 이 중 짝꿍 등록 때 붙은 리스너는 제거하기 전에 writer 와 provider 에 close 를 한 번 더 요청하지만, 이미 닫힌 상태라 아무 일도 일어나지 않는다. 이때 resetConnection() 은 공용 커넥션이 닫힐 때까지 기다린 뒤에 반환한다. 그 사이 함께 닫힌 노드 커넥션도 자기 리스너로 목록에서 빠진다. 실제 로그에서는 dispose(client) 가 시작되기 전에 모두 빠져 있었다.

 

 

이후 dispose(client)는 RedisClusterClient.shutdown() 을 호출한다. 클러스터 클라이언트는 토폴로지 조회를 먼저 멈추고 공통 종료 처리로 넘어간다. 이렇게 해서 앞서 본 임시 커넥션이 종료 도중에 새로 열리지 않는다.

 

 

그리고 closeResources()를 통해 closeableResources 종료 목록을 복사한 뒤 하나씩 닫는다. 이미 닫혔는지는 확인하지 않고, 목록에 남아 있으면 무조건 닫으라고 지시하고, 판단은 각 객체에 맡긴다. closeableResources 는 ConcurrentHashMap 기반 Set 이므로, 닫는 순서는 등록 순서와 다르다.

 

 

직접 RedisClusterClient를 connect 하여 등록된 커넥션들의 종료 흐름

직접 RedisClusterClient를 connect 하여 등록된 커넥션들은 LettuceConnectionFactory에 등록되어 있지 않다. 따라서 LettuceConnectionFactory의 resetConnection()을 통해 닫히지 않는다. 대신 LettuceConnectionFactory 내부에서 dispose(client)를 통해 RedisClusterClient를 종료할 때, 직접 연 커넥션들 역시 닫히게 된다.

 

 

문제는 dispose(client) 내부의 closeResources() 가 항목마다 closeAsync() 를 호출한 뒤 완료를 기다리지 않고 바로 다음 항목으로 넘어간다는 것이다. 종료 목록에서 닫힌 커넥션을 지우는 리스너는 소켓이 닫힌 뒤 이벤트 루프 스레드에서 나중에 실행된다. 그래서 순회가 도착할 때까지 노드 커넥션이 종료 목록에 남아 있다.

 

 

그래서 노드 커넥션은 클러스터 커넥션이 닫힐 때 provider 를 따라 한 번 닫히고, 아직 목록에서 빠지기 전에 closeResources() 순회가 노드 커넥션 차례에 도착해 한 번 더 닫으려 한다. 그리고 이때 다음의 레디스 WARN 로그가 발생한다.

Connection is already closed

 

 

참고로 같은 순회에서 writer 와 provider 도 두 번째 close 요청을 받는다. 각자의 클러스터 커넥션이 닫힐 때 이미 함께 닫혔는데도 목록에 자기 차례가 남아 있기 때문이다. 하지만 이들은 로그를 남기지 않는다. “이미 닫혔다”는 WARN 로그는 RedisChannelHandler 에만 있다. 이 클래스를 상속한 것은 클러스터 커넥션과 노드 커넥션인데, 클러스터 커넥션은 순회에서 한 번만 닫힌다. 따라서 두 번 닫혀서 로그가 남는 것은 노드 커넥션뿐이다.

 

따라서 해당 WARN 로그가 발생한다면 connect로 연결을 직접 맺는 코드를 정리할 수 있을지 검토해볼 필요가 있다.

 

댓글
공지사항
최근에 올라온 글
최근에 달린 댓글
Total
Today
Yesterday
링크
TAG more
«   2026/11   »
일 월 화 수 목 금 토
1 2 3 4 5 6 7
8 9 10 11 12 13 14
15 16 17 18 19 20 21
22 23 24 25 26 27 28
29 30
글 보관함