Spanner 큐 사용

이 문서에서는 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"

임대 토큰은 다음 로직에 따라 반환됩니다.

  1. 파싱할 수 없는 임대 토큰은 행을 반환하지 않습니다.
  2. 이미 만료된 임대 토큰은 행을 반환하지 않습니다.
  3. 갱신할 수 없는 임대 토큰은 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() 쿼리를 충분히 실행하지 않는 경우 메시지가 버퍼에서 폴링되지 않은 상태로 유지됩니다.

다음 단계