이 문서에서는 Spanner 큐를 사용하는 방법을 설명합니다. 큐를 만들고, 메시지를 보내고 받고, 메시지 임대를 연장하고, 메시지를 확인하는 방법을 설명합니다. 또한 권장사항, 큐 모니터링에 대한 정보, 문제 해결 안내도 포함되어 있습니다.
큐 만들기
큐를 만들려면 CREATE QUEUE 문을 사용합니다.
GoogleSQL
-- Example table for interleaving
CREATE TABLE Users (
UserId INT64 NOT NULL,
UserName STRING(MAX)
) PRIMARY KEY (UserId);
-- Queue for processing user-related tasks
-- NOTE: Queues do not have to be interleaved, but for locality and
-- pre-warming purposes, it's recommended if you are inserting into a table
-- and a queue simultaneously.
CREATE QUEUE UserTasks (
UserId INT64 NOT NULL,
MessageId STRING(36) NOT NULL, -- UUID recommended
Payload BYTES(MAX) NOT NULL -- Also: Proto, JSON, String are possible.
) PRIMARY KEY (UserId, MessageId),
INTERLEAVE IN PARENT Users ON DELETE CASCADE;
PostgreSQL
-- Example table for interleaving
CREATE TABLE users (
userid bigint NOT NULL,
username varchar,
PRIMARY KEY (userid)
);
-- Queue for processing user-related tasks
-- NOTE: Queues do not have to be interleaved, but for locality and
-- pre-warming purposes, it's recommended if you are inserting into a table
-- and a queue simultaneously.
CREATE QUEUE usertasks (
userid bigint NOT NULL,
messageid varchar(36) NOT NULL, -- UUID recommended
payload bytea NOT NULL, -- Also: text, varchar, jsonb are possible.
PRIMARY KEY (userid, messageid)
) INTERLEAVE IN PARENT users ON DELETE CASCADE;
CREATE
QUEUE 문에서 명시적으로 만들 필요가 없는 유일한 열은 GoogleSQL에서는 DeliverTime, PostgreSQL에서는 deliver_time라고 합니다. Spanner에서 자동으로 생성됩니다.
큐는 TTL(수명) 정책을 지원하므로 오래된 미확인 메시지의 메시지 백로그를 관리하는 데 도움이 될 수 있습니다.
메시지 보내기
큐에 메시지를 보내려면 INSERT DML 문을 사용합니다.
GoogleSQL
-- Send message immediately
INSERT INTO Users (UserId) VALUES (123);
INSERT INTO UserTasks (UserId, MessageId, Payload, DeliverTime)
VALUES (123, 'some-unique-id-1', b'Your task payload here', CURRENT_TIMESTAMP());
-- Schedule a message delivery
INSERT INTO UserTasks (UserId, MessageId, Payload, DeliverTime)
VALUES (123, 'some-unique-id-2', b'Scheduled task', TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR));
PostgreSQL
-- Send message immediately
INSERT INTO users (userid) VALUES (123);
INSERT INTO usertasks (userid, messageid, payload, deliver_time)
VALUES (123, 'some-unique-id-1', CAST('Your task payload here' AS bytea), CURRENT_TIMESTAMP);
-- Schedule a message delivery
INSERT INTO usertasks (userid, messageid, payload, deliver_time)
VALUES (123, 'some-unique-id-2', CAST('Scheduled task' AS bytea), CURRENT_TIMESTAMP + INTERVAL '1 HOUR');
또는 클라이언트 라이브러리 Send 변형을 사용하여 메시지를 삽입합니다.
Go
m := spanner.Send("UserTasks", spanner.Key{int64(123), "some-unique-id-1"}, []byte("Your task payload here"), spanner.WithDeliveryTime(futureTime))
_, err := client.Apply(ctx, []*spanner.Mutation{m})
자바
dbClient.write(
Collections.singletonList(
Mutation.newSendBuilder("UserTasks")
.setKey(Key.of(123L, "some-unique-id-1"))
.setPayload(Value.bytes(ByteArray.copyFrom("message3")))
.setDeliveryTime(futureTime)
.build()));
메시지 수신하기
ExecuteStreamingSQL와 함께 RECEIVE_QUEUE_NAME() 테이블 값 함수(TVF)를 사용하여 메시지를 수신합니다. 이는 장기 실행 호출입니다. 작업자당, 큐당 이러한 호출 중 하나를 루프 방식으로 실행해야 합니다. Spanner는 비활성 읽기를 거부하므로 강력 읽기를 사용하여 쿼리를 실행합니다.
GoogleSQL
-- SQL query to stream messages
SELECT
UserId,
MessageId,
Payload,
DeliverTime,
SpannerLeaseExpirationTimestamp,
SpannerLeaseToken
FROM RECEIVE_UserTasks(max_duration=>'20m');
PostgreSQL
-- SQL query to stream messages
SELECT
userid,
messageid,
payload,
deliver_time,
spanner_lease_expiration_timestamp,
spanner_lease_token
FROM spanner.receive_usertasks(
max_batch_size=>NULL, priority=>NULL, max_duration=>'20m');
클라이언트 코드는 스트리밍 쿼리를 사용하여 결과를 반복해야 합니다. 반환된 각 행은 메시지입니다.
일괄 메시지 수신
여러 메시지를 함께 처리하여 처리량을 늘리려면 max_batch_size 인수를 지정하여 메시지를 일괄 수신하면 됩니다. max_batch_size을 생략하거나 NULL로 설정하면 기본값은 30입니다.
GoogleSQL
-- SQL query to stream messages
SELECT
UserId,
MessageId,
Payload,
DeliverTime,
SpannerLeaseExpirationTimestamp,
SpannerLeaseToken,
SpannerLastBatchMessage -- Special boolean column returns TRUE if the
-- last message is in a batch.
FROM RECEIVE_UserTasks(max_duration=>'20m', max_batch_size=>20);
PostgreSQL
-- SQL query to stream messages
SELECT
userid,
messageid,
payload,
deliver_time,
spanner_lease_expiration_timestamp,
spanner_lease_token,
spanner_last_batch_message -- Special boolean column returns TRUE if the
-- last message is in a batch.
FROM spanner.receive_usertasks(
max_batch_size=>20, priority=>NULL, max_duration=>'20m');
또는 클라이언트 라이브러리를 사용합니다. 이 Go 예시에서는 큐에서 메시지를 스트리밍하고, 임대 만료를 확인하고, 메시지를 비동기식으로 확인하는 방법을 보여줍니다.
// import "cloud.google.com/go/spanner"
// import "google.golang.org/api/iterator"
stmt := spanner.Statement{SQL: "SELECT * FROM RECEIVE_UserTasks(max_duration=>'20m')"}
iter := client.Single().Query(ctx, stmt)
defer iter.Stop()
for {
row, err := iter.Next()
if err == iterator.Done {
break // Or potentially restart the query
}
if err != nil {
// Handle error
return err
}
var userId int64
var messageId string
var payload []byte
var deliverTime time.Time
var leaseExpiration time.Time
var leaseToken string
var lastBatchMessage bool
if err := row.Columns(&userId, &messageId, &payload, &deliverTime, &leaseExpiration, &leaseToken, &lastBatchMessage); err != nil {
// Handle column parsing error
return err
}
if time.Now().After(leaseExpiration) {
log.Printf("Lease expired for message %s, skipping", messageId)
continue
}
// Process and acknowledge the message asynchronously so that we don't
// block receiving subsequent messages.
go func(userId int64, messageId string, payload []byte) {
// Process the message (payload)
// ... potentially long-running work ...
// Need to extend the lease if processing is long
// Acknowledge the message upon success
_, err := client.Apply(ctx, []*spanner.Mutation{
spanner.Ack("UserTasks", spanner.Key{userId, messageId}),
})
if err != nil {
// Handle ack error
}
}(userId, messageId, payload)
}
메시지 임대 연장
메시지를 처리하는 데 초기 임대(10초)보다 오래 걸리는 경우 다음 문법을 사용합니다.
GoogleSQL
-- Extends the lease and returns new expiration time lease_token.
-- The lease will be extended by 10s (not configurable).
SELECT * FROM RENEWLEASE_UserTasks(lease_tokens => ['token1', ..., 'tokenN'])
-- Returns rows of tokens and whether they were successfully extended
SpannerOldLeaseToken SpannerNewLeaseToken SpannerLeaseExpirationTimestamp
<old_token1> <new_token1> "2025-09-27T12:10:00.0Z"
'token2' <NULL> "2025-09-27T12:09:51.0Z"
...
'tokenN' 'tokenN_new' "2025-09-27T12:10:01.0Z"
PostgreSQL
-- Extends the lease and returns new expiration time lease_token.
-- The lease will be extended by 10s (not configurable).
SELECT * FROM spanner.renewlease_usertasks(lease_tokens => ARRAY['token1', ..., 'tokenN'])
-- Returns rows of tokens and whether they were successfully extended
spanner_old_lease_token spanner_new_lease_token spanner_lease_expiration_timestamp
<old_token1> <new_token1> "2025-09-27T12:10:00.0Z"
'token2' <NULL> "2025-09-27T12:09:51.0Z"
...
'tokenN' 'tokenN_new' "2025-09-27T12:10:01.0Z"
임대 토큰은 다음 로직에 따라 반환됩니다.
- 파싱할 수 없는 임대 토큰은 행을 반환하지 않습니다.
- 이미 만료된 임대 토큰은 행을 반환하지 않습니다.
- 갱신할 수 없는 임대 토큰은
SpannerNewLeaseToken이 NULL인 행을 반환합니다. 메시지가 이미 확인되었지만 임대 토큰이 만료되지 않은 경우에 이러한 상황이 발생할 수 있습니다.
또는 클라이언트 라이브러리를 사용합니다. 이 Go 예시에서는 메시지 임대를 확장하는 방법을 보여줍니다.
// Inside message processing loop...
// Before leaseExpiration, for example, in a separate goroutine or timed check
// leaseToken is from the SELECT query
extendStmt := spanner.Statement{
SQL: "SELECT * FROM RENEWLEASE_UserTasks(lease_tokens => [@token1])",
Params: map[string]interface{}{
"token1": leaseToken,
},
}
_, err := client.Single().Query(ctx, extendStmt).Next() // Simplified call
if err != nil {
log.Printf("Failed to extend lease for %s: %v", messageId, err)
// Processing should probably stop as redelivery is likely
} else {
// New lease expiration is typically approximately 10s from now
log.Printf("Lease extended for %s", messageId)
// Update local leaseExpiration time if needed
}
메시지 확인
DELETE DML을 사용하여 메시지를 확인합니다. 이는 메시지 처리와 관련된 다른 쓰기와 트랜잭션이어야 합니다.
GoogleSQL
-- DML for acknowledging
DELETE FROM UserTasks WHERE UserId = @userId AND MessageId = @messageId ASSERT_ROWS_MODIFIED 1;
PostgreSQL
-- DML for acknowledging
DELETE FROM usertasks WHERE userid = $1 AND messageid = $2 ASSERT_ROWS_MODIFIED 1;
또는 클라이언트 라이브러리 Ack 변형을 사용하여 메시지를 확인합니다.
Go
_, err := client.Apply(ctx, []*spanner.Mutation{
spanner.Ack("UserTasks", spanner.Key{1}),
})
자바
dbClient.write(
Collections.singletonList(
Mutation.newAckBuilder("UserTasks")
.setKey(Key.of(2L))
.build()));
권장사항
다음은 Spanner 큐 사용에 대한 권장사항입니다.
- 작은 페이로드: 큐 메시지 페이로드를 4KB 미만으로 작게 유지합니다. 더 큰 데이터에는 대역 외 스토리지 패턴을 사용합니다.
- 임대 관리: 기본 메시지 임대 시간인 10초를 초과할 수 있는 태스크의 임대를 연장합니다. 메시지 임대를 연장하지 않으면 재전송 및 이중 처리가 발생할 수 있습니다.
- 오류 처리: Spanner는 처음 1시간 이내에 백오프를 사용하여 처리에 실패한 메시지를 재시도하고, 오래된 메시지는 1시간에 한 번씩 재시도합니다. 영구적으로 실패한 메시지를 별도의 큐로 이동하는 것이 좋습니다.
- 모니터링: 큐 깊이와 확인되지 않은 가장 오래된 메시지 기간을 모니터링하여 수신자가 파이프라인 수집을 제한하지 않는지 확인합니다.
- 멱등성: 최소 1회 전송은 가끔 중복이 발생할 수 있으므로 반복 작업을 허용하도록 메시지 프로세서를 설계합니다. 자세한 내용은 정확히 한 번 처리 및 최대 한 번 확인 페이지를 참조하세요.
- 테이블 값 함수 기간: 테이블 값 함수의 기간이 너무 짧거나 너무 길지 않도록 합니다. 20분과 같은 적당한 시간이 권장됩니다.
- 배치 크기 조정: 워크로드에 맞게
max_batch_size를 조정합니다. 팬아웃이 높은 이벤트에는 더 작은 배치를 사용하여 공유 행의 잠금 경합을 방지합니다. 독립적인 초당 쿼리 수가 많은 작업에는 더 큰 배치를 사용합니다. 최상의 성능을 위해 단일 트랜잭션에서 배치의 메시지 임대를 확인하거나 연장합니다.
모니터링
Spanner 내부 검사 테이블을 사용하여 큐 작업을 모니터링할 수 있습니다. 이러한 테이블에는 큐별 열이 포함되지 않지만 다음 테이블에서 사용자 정의 큐 이름을 검색하여 큐 활동을 식별할 수 있습니다.
다음 Spanner 큐 측정항목은 Cloud Monitoring의 spanner.googleapis.com/queue/* 프리픽스 아래에 있습니다.
buffered_ready_messages: (게이지, INT64, 1) 메모리에 보관되고 수신자에게 전송할 준비가 된 메시지 수입니다.message_send_count: (DELTA, INT64, 1) 큐 간격 동안 Spanner에서 전송된 메시지 수입니다.message_ack_count: (DELTA, INT64, 1) 큐의 간격 동안 Spanner에서 확인된 메시지 수입니다.oldest_unacked_message_age: (GAUGE, INT64, 1) 큐에서 가장 오래된 미확인 메시지의 경과 시간(초)입니다.lease_expiration_count: (DELTA, INT64, 1) 큐 간격 동안 Spanner에서 임대가 만료된 횟수입니다.
이전 측정항목은 모두 약 60초마다 샘플링됩니다. 샘플링 후 최대 120초 동안 데이터가 표시되지 않을 수 있습니다. Spanner 감사 로깅은 큐의 쓰기, 읽기, 스키마 작업을 다룹니다.
문제 해결
다음 섹션에서는 Spanner 큐를 사용할 때 일반적인 문제를 식별하고 해결하는 방법을 설명합니다.
메시지 백로그가 증가함
진단
oldest_unacked_message_age 및 buffered_ready_messages 모두 상승합니다. 이는 메시지 전송 속도와 애플리케이션의 메시지 프로세서 용량 간의 불균형을 나타냅니다.
해결 방법
이 문제를 해결하려면 다음 단계를 따르세요.
- 확인 속도 확인:
message_ack_count측정항목이 감소한 경우 클라이언트 작업자가 제대로 실행 중이고 중단되거나 비정상 종료되지 않았는지 확인합니다. - 전송 속도 확인:
message_send_count가 급증한 경우 메시지 처리 작업자를 확장하여 증가한 부하를 처리합니다. - 리소스 소진 확인:
buffered_ready_messages및lease_expiration_count수가 증가했는지 확인합니다. 이 조합은 활성 테이블 반환 함수(TVF) 수신자가 부족하거나 클라이언트 처리가 느리다는 것을 나타냅니다.
개별 메시지가 전송되지 않음
진단
oldest_unacked_message_age 측정항목은 높지만 buffered_ready_messages은 낮거나 안정적입니다. 이는 전체 용량 병목 현상이 아니라 개별 메시지가 처리 또는 확인되지 않음을 나타냅니다.
해결 방법
이 문제를 해결하려면 다음 단계를 따르세요.
중단된 메시지 식별: 큐 테이블을 쿼리하고 배송 시간별로 결과를 정렬하여 확인되지 않은 가장 오래된 메시지를 찾습니다.
GoogleSQL
SELECT * FROM UserTasks ORDER BY DeliverTime ASC LIMIT 10;PostgreSQL
SELECT * FROM usertasks ORDER BY deliver_time ASC LIMIT 10;처리 실패 조사: 애플리케이션 로그를 확인하여 작업자가 식별된 메시지를 확인하지 않는 이유를 파악합니다. 확인되지 않은 메시지는 임대가 만료된 후 자동으로 다시 전송됩니다.
처리가 완료되기 전에 메시지 임대가 만료됨
진단
lease_expiration_count 측정항목이 상승하거나 증가하고 있습니다. 이는 작업자가 메시지를 확인하기 전에 메시지 처리 시간이 임대 기간(기본값 10초)을 초과함을 나타냅니다.
해결 방법
이 문제를 해결하려면 다음 단계를 따르세요.
- 사전 임대 갱신: 메시지 처리에 10초 이상 걸리는 경우
RENEWLEASE_QUEUE_NAME()TVF를 주기적으로 호출합니다. 네트워크 지연 시간을 안전하게 고려하기 위해 처리 후 약 7~8초 후에 임대를 갱신합니다. - 느린 처리 조사: 애플리케이션이 이미 리스를 적극적으로 갱신하지만
lease_expiration_count가 높은 상태로 유지되는 경우 백엔드 코드에서 처리 병목 현상, 느린 RPC 호출 또는 교착 상태를 확인합니다.
메시지 전송 속도를 확장할 수 없음
진단
전송 속도를 높이려고 하면 message_send_count 측정항목이 처리량 정체에 도달하거나 게시 요청에서 쓰기 지연 시간이 증가합니다.
해결 방법
이 문제를 해결하려면 다음과 같은 구조적 변경을 고려하세요.
- 컴퓨팅 리소스 수직 확장: Spanner 인스턴스에 노드 또는 처리 단위를 추가하여 전체 데이터베이스 용량을 늘립니다.
- 분할 확인: 분할을 더 추가하여 여러 서버에 쓰기 부하를 분산할 수 있는지 평가합니다.
- 라우팅 최적화: 게시 애플리케이션이 Spanner 인스턴스의 리더 리전에 직접 작성하여 쓰기 지연 시간을 최소화합니다.
준비 메시지가 처리되지 않음
진단
buffered_ready_messages 측정항목이 높고 증가하고 있습니다. 이는 메시지가 버퍼링되고 메모리에 전송할 준비가 되었지만 수신자 작업자가 이를 가져오지 않음을 나타냅니다.
해결 방법
이 문제를 해결하려면 다음 단계를 따르세요.
- 활성 TVF 연결 확인: 활성 수신자 TVF 수를 확인하여 리더 작업자가 메시지를 적극적으로 연결하고 가져오는지 확인합니다. 작업자가 연결 해제되었거나 동시
RECEIVE_QUEUE_NAME()쿼리를 충분히 실행하지 않는 경우 메시지가 버퍼에서 폴링되지 않은 상태로 유지됩니다.
다음 단계
- Spanner 큐 시나리오 및 예시 더 둘러보기
- 정확히 한 번 처리 및 최대 한 번 확인에 대해 알아보세요.
- 큐에 대한 세분화된 액세스 제어로 액세스 제어를 구성합니다.