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은 채우지 않고 행마다 길이가 들쭉날쭉한 채로 준다. 내 코드는 폭을 “헤더 행의 길이”로 잡고 있었다. 헤더 행이 데이터 행보다 짧은 탭을 배치로 읽으면 헤더 뒤쪽의 컬럼이 조용히 잘렸다. 개별로 읽을 때는 헤더도 채워져서 오기 때문에 잘리지 않았다.
# 전: 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건의 시간과 왕복 횟수부터 잰다.
- 라이브러리의 편한 메서드는 뒤에서 몇 번 왕복하는지 확인하고 쓴다. 이번에는 탭을 이름으로 찾는 한 줄이 호출의 절반이었다.
- 캐시를 넣으면 그 대상을 바꾸는 동작을 전부 찾아 무효화를 붙인다. 생성만 챙기고 삭제, 복제, 이름 변경을 빠뜨렸었다.