봇을 위한 구조화 로깅과 관측가능성

-

🌐 English

봇이 새벽 3시에 이상한 주문을 냈습니다. 다음 날 원인을 찾으려는데 로그가 println("주문함") 한 줄뿐이라면, 그 사고는 영원히 미제로 남습니다. 무인 운영 봇에게 로그는 사치가 아니라 블랙박스입니다.

⚠️ 실거래 자동매매는 소프트웨어·네트워크 장애로 손실이 발생할 수 있습니다. 이 글은 교육·정보 목적입니다.

1. 로그 레벨 — 노이즈와 신호 분리

모든 걸 같은 톤으로 찍으면 정작 중요한 게 묻힙니다. 최소한 네 단계는 나눕니다.

  • DEBUG: 개발·재현용 상세(호가 스냅숏, 계산 중간값). 평소엔 끔.
  • INFO: 정상 흐름의 이정표(진입·청산·재연결 성공).
  • WARN: 이상하지만 계속 가능(미체결 취소, 데이터 지연).
  • ERROR: 개입 필요(주문 실패, 인증 만료, 패닉 복구).

운영 중엔 INFO 이상만 파일에 남기고 DEBUG는 스위치로 켜는 구조가 편합니다. 레벨은 나중에 필터링할 수 있게 하는 인덱스입니다.

2. 왜 구조화(JSON) 로그인가

사람이 읽는 문장 로그는 기계가 검색·집계하기 어렵습니다. 필드를 가진 JSON으로 남기면, 나중에 "오늘 ERROR만" "종목 A의 체결만" 같은 질의가 즉시 됩니다.

// 문자열 로그 (검색 지옥)

log.Printf("종목 %s 매수 %d주 @ %.0f", code, qty, price)

// 구조화 로그 (필드로 질의 가능)

logEvent(map[string]any{

    "level":  "INFO",

    "event":  "order_filled",

    "code":   code,

    "side":   "buy",

    "qty":    qty,

    "price":  price,

    "trace":  traceID,

})

// → {"level":"INFO","event":"order_filled","code":"069500","qty":200,...}

Go 표준 라이브러리라면 log/slog로 바로 이 형태를 얻습니다. 굳이 무거운 프레임워크가 필요 없습니다.

logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))

logger.Info("order_filled",

    "code", code, "qty", qty, "price", price, "trace", traceID)

3. 상관관계 추적 — 한 결정의 전체 궤적

봇의 한 사이클은 신호 → 검증 → 주문 → 체결 → 상태 저장으로 이어집니다. 이 흐름에 같은 trace ID를 달면, 사고가 났을 때 그 결정의 처음부터 끝까지를 한 줄로 이어 볼 수 있습니다.

trace := newTraceID()               // 한 사이클 = 하나의 ID

logger.Info("signal_fired",  "trace", trace, "gap", gap)

logger.Info("depth_check",   "trace", trace, "askQty", askQty)

logger.Info("order_sent",    "trace", trace, "qty", qty)

logger.Warn("order_timeout", "trace", trace)   // ← 여기서 꼬였다

logger.Info("order_cancel",  "trace", trace)

나중에 trace로 필터링하면 "왜 그 주문이 미체결로 취소됐나"의 전체 맥락이 시간순으로 복원됩니다. 로그가 흩어진 점이 아니라 이어진 선이 됩니다.

4. 무엇을 남기고 무엇을 버리나

다 남기면 디스크가 터지고 정작 중요한 게 안 보입니다. 기준은 "이 줄이 사고를 설명하는 데 필요한가"입니다.

  • 반드시 남긴다: 모든 상태 전이(진입/청산/정지), 모든 외부 부작용(주문·취소·API 호출 결과), 모든 ERROR/WARN.
  • 버리거나 DEBUG로: 초당 수십 개 들어오는 호가 원본, 루프마다 도는 계산 중간값. 필요할 때만 켠다.
  • 절대 남기지 않는다: API 키·토큰·계좌번호 같은 비밀. 로그로 새는 것도 유출입니다.
// 민감정보는 마스킹해서만 기록

func maskSecret(s string) string {

    if len(s) <= 8 {

        return "****"

    }

    return s[:4] + "****" + s[len(s)-4:]

}

logger.Info("auth_ok", "key", maskSecret(appKey))

5. 운영 위생 — 로테이션과 알림

  • 로그 로테이션: 날짜·크기별로 파일을 나눠, 하나가 무한정 커지지 않게. 오래된 건 자동 삭제.
  • ERROR는 밖으로: 파일에만 쌓지 말고 메신저 알림으로 즉시 밀어냅니다. 사람이 하루 종일 로그를 볼 수 없으니까요.

정리

  • 레벨로 노이즈와 신호를 분리 — 운영은 INFO 이상, DEBUG는 스위치
  • JSON 구조화 로그로 나중에 질의·집계 가능하게 (Go는 slog면 충분)
  • trace ID로 한 결정의 전체 궤적을 이어서 복원
  • 상태 전이·외부 부작용·에러는 남기고, 비밀은 마스킹
  • 로테이션으로 디스크를 지키고, ERROR는 알림으로 밖에 알린다

관측가능성은 "봇이 무엇을 했는지 나중에 정확히 재구성할 수 있는가"입니다. 화려한 대시보드 이전에, 사고를 설명할 수 있는 로그 한 줄이 무인 운영의 안전망입니다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

한국투자증권 KIS API로 실시간 시세 받기 (WebSocket 실전)

-
🌐 English 주식 자동매매 봇의 심장은 실시간 시세 입니다. REST 폴링만으로는 초 단위 시그널을 만들 수 없습니다. 한국투자증권(KIS) 오픈API는 WebSocket으로 호가와 체결을 밀어주는데, 실전에서 부딪히는 지점들을 자동매매 봇을 만들며 정리한 노트입니다. ⚠️ 이 글은 교육·정보 제공 목적입니다. 투자 권유가 아니며, 투자 손실 책임은 본인에게 있습니다. 두 개의 TR을 구독한다 KIS 실시간에서 자주 쓰는 TR은 두 가지입니다. H0STASP0 — 실시간 호가 (매수·매도 1~10호가) H0STCNT0 — 실시간 체결가 (현재가, 시가, 전일종가, 누적거래량) 시가 기준 전략을 쓴다면 H0STCNT0 이 필수입니다. 체결 메시지 안에 시가(stck_oprc) 가 들어 있어서, 장 시작 첫 체결로 그날의 기준선을 잡을 수 있기 때문입니다. 종목당 두 TR을 구독하므로, 종목이 늘어나면 구독 건수가 빠르게 증가합니다. KIS는 한 연결에 동시 구독 한도(수십 건)가 있으니, 중복 종목은 seen 맵으로 걸러 한 번만 구독합니다. seen := make(map[string]bool) addSym := func(code string) { if code == "" || seen[code] { return // 빈 코드·중복은 skip } seen[code] = true subscribeKIS(conn, approvalKey, "H0STASP0", code) // 호가 time.Sleep(50 * time.Millisecond) subscribeKIS(conn, approvalKey, "H0STCNT0", code) // 체결 time.Sleep(50 * time.Millisecond) } 구독 사이에 짧은 sleep 을 두는 이유는, 여러 구독 프레임을 한...
자세한 내용 보기

파이썬으로 업비트 API 연동하기 — 시세 조회부터 주문까지 기초

-
🌐 English 코인 자동매매를 만들어 보려고 검색하면 대부분 "전략"부터 이야기합니다. 그런데 막상 코드를 짜려고 하면 거래소에 요청을 어떻게 보내는지 에서 먼저 막힙니다. 이 글은 그 첫 관문만 다룹니다. 파이썬으로 업비트 API에 붙어서 시세를 읽고, 잔고를 확인하고, 주문을 넣는 데까지입니다. 0. 준비물 필요한 건 두 가지뿐입니다. 파이썬 패키지 : pip install requests pyjwt — requests는 HTTP 요청 라이브러리, PyJWT는 인증 토큰을 만드는 라이브러리입니다. 업비트 API 키 : 업비트 웹사이트 → 마이페이지 → Open API 관리에서 발급합니다. 발급할 때 허용 IP를 반드시 등록 하고, 처음에는 자산조회·주문조회 권한만 켜세요. 주문 권한은 코드가 검증된 뒤에 켜도 늦지 않습니다. 발급받은 secret key는 발급 화면을 벗어나면 다시 볼 수 없습니다. 그리고 절대 소스코드에 직접 적지 마세요. 환경변수나 설정 파일로 분리합니다. import os ACCESS_KEY = os.environ["UPBIT_ACCESS_KEY"] # 실제 키는 환경변수로 SECRET_KEY = os.environ["UPBIT_SECRET_KEY"] SERVER_URL = "https://api.upbit.com" 1. 시세 조회 — 인증이 필요 없는 요청 가장 쉬운 것부터 합니다. 현재가 조회는 인증 없이 됩니다. 그냥 GET 요청 하나면 끝입니다. import requests def get_price(market="KRW-BTC"): url = f"{SERVER_URL}/v1/ticker" res = requests.get(url, params={"markets": market}, timeout=5) res.rais...
자세한 내용 보기

Go로 자동매매 신호봇 프레임워크 설계하기

-
🌐 English 자동매매 봇을 만들다 보면 전략 코드보다 주변 골격 에 시간을 더 쓰게 됩니다. 설정을 어떻게 읽지? 상태는 어디서 보지? 알림은? 이 글은 실제로 돌아가는 Go 선물 신호봇을 만들며 정리한, 재사용 가능한 프레임워크 뼈대입니다. 핵심 원칙은 하나입니다. 최소 의존성. 설정은 ini 하나, 웹은 표준 net/http , 알림은 텔레그램 REST 호출. 무거운 프레임워크 없이 단일 실행 파일로 끝냅니다. 1. 설정 로더 — config.ini 봇 파라미터는 코드가 아니라 파일에 둡니다. 재빌드 없이 값을 바꾸기 위해서죠. INI는 사람이 편집하기 쉽고 섹션으로 묶기 좋습니다. type AppConfig struct { APIKey, APISecret string Testnet bool LoopIntervalSec int NotionalPerEntry float64 Leverage int DashboardPort int DashboardKey string } func loadConfig(path string) (*AppConfig, error) { f, err := ini.Load(path) if err != nil { return nil, err } c := &AppConfig{} bi := f.Section("binance") c.APIKey = bi.Key("api_key").String() c.Testnet = bi.Key("testnet").MustBool(true) // 기본값을 안전한 쪽으로 tr := f.Section("trading") c.LoopIntervalSec = tr.Key("loop_interval_sec").MustInt(10) c.Leverage = tr.Key("l...
자세한 내용 보기