AI SDK 요청 로그 남기기 — 가로채는 층은 순서가 전부입니다

AI를 코드에 붙여 돌리다 보면 곧 같은 고민이 옵니다. 어느 요청이 얼마나 걸렸는지, 어느 기능에서 나간 건지 기록하고 싶어집니다. 요청마다 그 코드를 붙이자니 지저분하고요. 공식 라이브러리에는 요청이 나가기 직전과 응답이 돌아온 직후에 내 코드를 끼워 넣는 자리가 마련돼 있습니다. 반가운 소식은 일곱 언어 전부 된다는 것이고, 조심할 소식은 순서 규칙을 모르면 내가 단 코드가 엉뚱한 자리에 놓인다는 것입니다.

📌 30초 요약

• 보내기 전과 받은 뒤에 끼어드는 층입니다. 기록·표시 달기·자체 재시도·거절 대응에 씁니다.
• 일곱 언어 전부 지원합니다. 언어마다 되는 게 갈리던 다른 기능들과 다릅니다.
• 등록 순서대로 나가고 역순으로 돌아옵니다. 첫 번째로 등록한 것의 뒷부분이 가장 마지막에 돕니다.
• 클라이언트에 붙인 것이 요청 하나에만 붙인 것보다 먼저 돕니다. 반대로 알기 쉬운 부분입니다.
• HTTP 클라이언트를 갈아 끼우면 이 층들보다 뒤에 옵니다. 게다가 하나만 쓸 수 있어 기본 설정이 통째로 바뀝니다.

1. 요청을 가로채는 층이 뭐고 어디에 쓰나

구조는 단순합니다. 내 코드가 요청을 만들면, 그게 서버로 나가기 전에 내가 등록해 둔 함수를 한 번 거칩니다. 그 함수는 요청을 들여다보거나 아예 다른 요청으로 바꿔치기한 뒤, 다음으로 넘기는 호출을 합니다. 응답이 돌아오면 그 호출이 값을 돌려주고, 이번엔 응답을 손볼 기회가 생깁니다. 넘기기 전에 쓴 코드는 나가는 길에, 넘긴 뒤에 쓴 코드는 돌아오는 길에 돕니다.

쓰임새는 대체로 넷입니다. 첫째 기록 — 어떤 요청이 어디로 나갔고 얼마나 걸렸고 어떤 상태로 돌아왔는지를 한곳에서 남깁니다. 둘째 표시 달기 — 요청에 "이건 어느 기능에서 나간 것"이라는 꼬리표를 붙여 나중에 갈라 볼 수 있게 합니다. 셋째 내 방식대로의 재시도 — 기본 재시도 규칙 말고 서비스 사정에 맞는 규칙을 겁니다. 넷째 거절 대응 — 모델이 답하기를 거부했을 때 그냥 실패시키지 않고 다른 길을 텁니다.

비용을 다루는 일에도 잘 맞습니다. 요청마다 걸린 시간과 결과를 한곳에서 모으면 어느 기능이 돈을 제일 많이 먹는지가 보입니다. 도구별 요금과 한도를 비교해 예산을 짜 뒀다면, 그 예산이 실제로 어디서 새는지 확인하는 계측기를 여기에 다는 셈입니다.

2. 이번엔 일곱 언어 전부 됩니다

공식 라이브러리는 언어마다 되는 게 조금씩 다릅니다. 그런데 이 기능은 예외입니다. 문서가 일곱 언어 전부에 예제를 실어 놨습니다. 모양은 각 언어 관습을 따르지만 하는 일은 똑같습니다.

언어	붙이는 모양
파이썬 · 루비 · 타입스크립트	함수를 만들어 목록에 담아 클라이언트에 넘김
C#	처리기 목록에 만들어 넣는 방식, 취소 신호가 같이 옴
고	옵션으로 여러 번 등록 — 부를 때마다 이어붙음
자바	빌더에 가로채기를 더하는 방식, 동기 전용 표기 있음
PHP	요청 옵션에 함수를 담아 전달

눈여겨볼 건 고만 등록 방식이 다르다는 점입니다. 다른 언어는 목록 하나를 통째로 넘기는데, 고는 등록 함수를 여러 번 부르면 그때마다 뒤에 이어붙습니다. 클라이언트에서 부른 것이 먼저, 메서드에서 부른 것이 그다음이죠. 같은 코드를 언어만 바꿔 옮길 때 이 차이에서 순서가 뒤집히기 쉽습니다.

3. 순서가 전부입니다

여러 개를 붙이기 시작하면 여기서 헷갈립니다. 규칙 자체는 간단합니다 — 등록한 순서대로 나가고, 역순으로 돌아옵니다. 첫 번째로 등록한 것의 "보내기 전" 코드가 가장 먼저 돌고, 같은 것의 "받은 뒤" 코드가 가장 마지막에 돕니다. 뒤에 등록한 것일수록 안쪽에 놓여 서버와 가까워집니다.

그래서 전체를 감싸는 성격의 일은 앞쪽에 등록해야 합니다. 전체 소요 시간을 재거나, 무슨 일이 있어도 마지막에 기록을 남기고 싶다면 첫 번째 자리가 맞습니다. 반대로 서버에 나가기 직전 모습을 봐야 하는 일은 뒤쪽에 등록해야 실제로 나가는 형태를 볼 수 있습니다.

직관과 어긋나는 대목이 하나 있습니다. 클라이언트에 붙여 둔 것이, 요청 하나에만 따로 붙인 것보다 먼저 돕니다. "이번 요청만 특별하게 처리하자"며 요청 쪽에 코드를 달았는데, 그 코드가 손을 대기 전에 공통으로 걸어 둔 코드가 이미 요청을 한 번 만지고 지나간 상태라는 뜻입니다. 공통 코드가 요청에 무언가를 덧붙이고 있었다면, 개별 처리는 그걸 이미 반영된 상태에서 시작합니다.

정리하면 바깥에서 안쪽으로 — 공통이 바깥, 개별이 안쪽입니다. 이 그림만 머리에 넣어 두면 "왜 내 로그에 이 값이 이미 들어 있지" 같은 혼란이 사라집니다.

4. HTTP 클라이언트를 갈아 끼우면 이 층 뒤로 갑니다

회사망에서 프록시를 태우거나, 사설 인증서를 쓰거나, 연결을 재사용해 성능을 올리려면 HTTP를 담당하는 부품 자체를 직접 넣을 수 있습니다. 이때 위치가 중요합니다. 그 부품은 가로채는 층이 전부 끝난 다음에 요청을 받습니다.

⚠️ 두 가지를 같이 조심하세요

첫째, 감사나 보안 목적으로 요청을 기록한다면 이 층이 마지막 관문이 아닙니다. 뒤에 붙은 부품이 요청을 더 손볼 수 있으니, "여기서 본 것 = 실제로 나간 것"이라고 단정하면 안 됩니다. 둘째, HTTP 부품은 하나만 쓸 수 있어서 넣는 순간 기본이 통째로 교체됩니다. 기본에 들어 있던 제한 시간·연결 수 같은 설정이 같이 사라지니, 맨바닥부터 만들지 말고 기본 것을 감싸서 필요한 부분만 바꾸는 형태로 넣으세요.

반가운 것도 하나 있습니다. 이미 만들어져 딸려 오는 층이 하나 있습니다. 모델이 요청에 답하기를 거부했을 때, 그대로 실패시키지 않고 미리 정해 둔 다른 모델로 다시 시도해 주는 물건입니다. 직접 짜려면 거절인지 아닌지 판별하는 부분이 은근히 까다로운데, 그걸 회사가 만들어 넣어 놨습니다.

이 발상은 모델을 갈아 끼우는 습관과 잘 맞습니다. 무료 모델을 코딩 도구에 붙여 쓰는 방식에 익숙하다면, 여기서도 같은 그림으로 "평소엔 이 모델, 막히면 저 모델"을 코드 한 겹으로 만들 수 있습니다. 다만 대체 모델도 결국 돈이 드는 쪽일 수 있으니, 어떤 조건에서 넘어가는지는 직접 정해 두세요.

5. 자주 묻는 질문 (FAQ)

Q. 자동 재시도가 이미 있는데 왜 또 만드나요?

기본 재시도는 어느 서비스에나 무난한 규칙입니다. 실제로는 "이 기능은 실패해도 그냥 넘어가고, 저 기능은 오래 걸려도 꼭 성공시켜야 한다"처럼 갈리죠. 그런 규칙을 요청마다 코드에 심는 대신 한 겹으로 모으는 게 이 자리의 쓸모입니다.

Q. 한 글자씩 흘러나오는 응답도 가로챌 수 있나요?

문서의 예제는 상태만 확인하고 그대로 돌려주는 수준까지만 보여 줍니다. 흘러나오는 응답의 본문을 그 자리에서 통째로 읽어 버리면 뒤에서 한 조각씩 받아 갈 것이 남지 않으니, 본문에는 손대지 않는 편이 안전합니다. 기록이 필요하면 본문 대신 걸린 시간과 상태만 남기세요.

Q. 요청 내용을 통째로 로그에 남겨도 되나요?

권하지 않습니다. 사용자가 입력한 문장이 그대로 들어 있고, 거기에 개인정보나 사내 자료가 섞일 수 있습니다. 기록은 나간 곳·걸린 시간·결과 상태 정도로 좁히고, 내용이 꼭 필요하면 길이나 요약만 남기는 편이 낫습니다.

Q. 언어를 옮기면 코드도 그대로 옮겨지나요?

개념은 그대로지만 모양은 다시 써야 합니다. 특히 고는 등록 함수를 여러 번 부르면 이어붙는 방식이라 순서가 뒤집히기 쉽고, 자바는 동기 전용 표기가 따로 있습니다. 옮긴 뒤에는 기록이 나오는 순서부터 확인해 보세요.

✨ 정리하면

요청을 가로채는 층은 일곱 언어 전부에서 되는 몇 안 되는 기능입니다. 기억할 건 셋 — 등록 순서대로 나가 역순으로 돌아오고, 공통이 개별보다 먼저 돌고, HTTP 부품을 갈아 끼우면 이 층들보다 뒤에 옵니다. 거절 시 다른 모델로 넘기는 층은 이미 만들어져 있으니 가져다 쓰면 됩니다. AI에 드는 돈이 새는 자리를 순서대로 훑고 싶다면 AI 지출 관리 허브에 단계별로 모아 뒀습니다.

※ 2026년 9월 기준 공식 문서(라이브러리 가로채기 안내)를 바탕으로 정리했습니다. 흘러나오는 응답을 다루는 방식은 문서가 따로 설명하지 않아, 본문 취급에 관한 부분은 동작 원리에 근거한 권고입니다. 등록 방식과 옵션 이름은 갱신될 수 있으니 적용 전 최신 문서를 확인하세요.