Sheets API 호출 14번을 1번으로 줄였다

Sheets API 호출 1건은 약 0.3초였다. 컨테이너에서 실제 시트를 상대로 잰 값이다. 이 시간은 거의 전부 왕복 지연이고, 읽는 데이터의 크기와는 거의 무관했다.

커뮤니티용 텔레그램 봇은 Google Sheets에서 데이터를 읽어 응답한다. 시트를 여러 탭 읽는 명령들이 눈에 띄게 느려서 2026년 7월 하순에 재 봤다. 탭 7개를 읽어 하나로 취합하는 명령이 4.5초 걸렸다. 탭 하나하나는 크지 않다. 그런데 이 명령은 API를 14번 부르고 있었다. 탭은 7개인데 호출은 그 두 배였다.

탭을 찾을 때마다 메타데이터를 통째로 받고 있었다

봇은 gspread를 쓴다. 탭 하나를 읽는 평범한 코드는 이렇게 생겼다.

ws = sh.worksheet("탭 이름")      # 왕복 1회: 스프레드시트 메타데이터
rows = ws.get_all_values()        # 왕복 1회: 값

sh.worksheet(title)과 sh.get_worksheet_by_id(gid)는 호출할 때마다 스프레드시트 메타데이터를 통째로 다시 받아 그 안에서 탭을 찾는다. 그래서 탭 하나를 읽는 데 왕복이 2회 나가고, 탭 7개면 14회다. 절반은 “어떤 탭이 있는지”를 매번 다시 묻는 데 쓰이고 있었다.

스프레드시트를 여는 open_by_key도 메타데이터를 받아 오므로 그 자체가 왕복 1회다. 한 명령 안에서 같은 스프레드시트를 두세 번 열면 그만큼 더 느려진다.

핸들은 스레드별로, 탭 목록은 300초

같은 키의 스프레드시트는 스레드당 한 번만 연다.

_tls = threading.local()

def open_sheet(key: str):
    cache = getattr(_tls, "sheets", None)
    if cache is None:
        cache = _tls.sheets = {}
    sh = cache.get(key)
    if sh is None:
        sh = cache[key] = service_account().open_by_key(key)
    return sh

봇은 시트 호출을 asyncio.to_thread로 스레드 풀에 넘기는데, 풀의 스레드는 재사용되므로 두 번째부터는 여는 왕복이 0회다. 전역 하나로 공유하지 않고 스레드별로 둔 이유는 gspread가 쓰는 requests.Session을 여러 스레드가 함께 쓰면 완전히 안전하지 않은 경우가 있어서다.

메타데이터에서 필요한 것은 탭 이름과 속성의 목록이다. 이것만 스프레드시트 id별로 300초 동안 캐시했다.

def tab_props(sh, *, refresh: bool = False) -> dict[str, dict]:
    if not refresh:
        with _meta_lock:
            hit = _meta_cache.get(sh.id)
        if hit and (time.monotonic() - hit[0]) < _META_TTL:
            return hit[1]
    return _remember_meta(sh.id, sh.fetch_sheet_metadata())

def worksheet(sh, title: str):
    props = tab_props(sh)
    if title not in props:
        props = tab_props(sh, refresh=True)   # 캐시에 없으면 한 번 갱신해 확인
    if title not in props:
        raise gspread.WorksheetNotFound(title)
    return gspread.Worksheet(sh, props[title], sh.id, sh.client)

캐시에 없는 탭을 찾으면 바로 예외를 던지지 않고 한 번 새로 받아 확인한다. 방금 만들어진 탭을 “없다”고 답하지 않기 위해서다.

sh.worksheet(...) 호출은 10여 개 파일에 흩어져 있었다. 호출부를 전부 고치는 대신, 모듈을 불러올 때 gspread.Spreadsheet의 탭 조회 메서드 두 개를 위 함수로 바꿔 끼웠다. 반환값과 예외는 원래와 같고 사라지는 것은 메타데이터 왕복뿐이다. 라이브러리 클래스를 바꿔 끼우는 방식이라 gspread를 올릴 때 다시 확인해야 한다는 부담은 남는다.

같은 자리에서 하나를 더 얻었다. 스프레드시트를 여는 순간 gspread가 받아 온 메타데이터에는 탭 목록이 들어 있는데 쓰지 않고 버린다. 메타데이터를 받는 메서드도 감싸서 그 결과를 캐시에 넣었다. 연 직후의 첫 탭 조회도 왕복 없이 끝난다.

값은 batchGet 한 번에 받고, 캐시하지 않는다

탭 목록을 알고 있으면 값도 한 번에 받을 수 있다. Sheets API의 values:batchGet은 범위 여러 개를 한 요청으로 읽는다. gspread에서는 values_batch_get이다.

want = ["탭A", "탭B", "탭C"]
vr = sh.values_batch_get([f"'{t}'" for t in want])["valueRanges"]
got = {t: (v.get("values") or []) for t, v in zip(want, vr)}

여러 탭을 읽던 명령들을 이 로더로 옮겼다. 탭 종류별로 있던 파서는 이미 읽어 둔 값을 받을 수 있게 바꿔서 배치 결과를 그대로 재사용한다.

캐시하는 것은 “어떤 탭이 있느냐”까지다. 셀 값은 캐시하지 않았다. 봇은 시트를 읽은 뒤 그 값을 바탕으로 되쓰기도 하는데, 값을 캐시하면 오래된 값을 읽고 그 위에 되쓰는 사고가 날 수 있다. 탭 구성은 실행 중에 거의 바뀌지 않으니 캐시해도 위험이 작고, 값은 계속 바뀌니 매번 새로 읽는다. 속도를 조금 더 얻는 것보다 이 선을 지키는 쪽이 중요하다고 봤다.

같은 환경에서 다시 쟀다.

작업전후
탭 7개 취합14회, 4.5초1회, 0.5초
조회 뷰 하나7회, 2.3초1회, 0.35초
기동 시 동기화7회, 2.2초2회, 0.95초
탭 1개 읽기2회, 0.65초1회, 0.31초

호출 수에 0.3초를 곱한 값과 대체로 맞는다. 처음에 잰 “1건에 약 0.3초”가 그대로 예측 도구가 됐다.

탭 24개를 두 방법으로 읽었더니 4개가 달랐다

읽는 경로가 개별 읽기와 배치 읽기 둘이 됐으니 결과가 같은지 확인해야 했다. 같은 날 스프레드시트의 탭 24개를 두 방법으로 읽어 전수 비교했고, 4개가 달랐다.

행의 폭 때문이었다. gspread의 get_all_values()는 짧은 행을 가장 넓은 행의 폭까지 빈 문자열로 채워서 준다. values:batchGet은 채우지 않고 행마다 길이가 들쭉날쭉한 채로 준다. Sheets API는 값을 읽을 때 끝쪽의 빈 행과 열을 생략한다. 내 코드는 폭을 “헤더 행의 길이”로 잡고 있었다. 헤더 행이 데이터 행보다 짧은 탭을 배치로 읽으면 헤더 뒤쪽의 컬럼이 조용히 잘렸다. 개별로 읽을 때는 헤더도 채워져서 오기 때문에 잘리지 않았다.

# 전: width = len(values[0])
width = max((len(r) for r in values), default=0)
header = (values[0] + [""] * width)[:width] if values else []
rows = [(r + [""] * width)[:width] for r in values[1:]]

폭을 가장 넓은 행 기준으로 바꾸자 불일치는 0건이 됐다. 달랐던 4개는 봇이 읽지 않는 미러 탭이어서 실제 오작동은 없었다. 다만 언젠가 그런 모양의 탭을 배치로 바꾸는 순간 조용히 터질 함정이었다. 비교하지 않았다면 몰랐을 것이다.

이 점검에서 하나를 더 고쳤다. 캐시를 비우는 동작이 탭 생성에만 붙어 있었다. 탭 삭제, 복제, 이름 변경에도 붙였다. 이름 변경은 캐시의 키가 옛 이름이라 TTL이 지날 때까지 새 이름으로 조회가 되지 않는 문제가 있었다.

그 뒤로 하는 것

  • 원격 API가 느리면 데이터 크기를 보기 전에 호출 1건의 시간과 왕복 횟수부터 잰다.
  • 라이브러리의 편한 메서드는 뒤에서 몇 번 왕복하는지 확인하고 쓴다. 이번에는 탭을 이름으로 찾는 한 줄이 호출의 절반이었다.
  • 캐시를 넣으면 그 대상을 바꾸는 동작을 전부 찾아 무효화를 붙인다. 생성만 챙기고 삭제, 복제, 이름 변경을 빠뜨렸었다.