에이전트 게이트웨이는 컨트롤 플레인입니다. 도구를 인증하고 모델 호출을 팬아웃하며 예산을 강제합니다. 로그는 사고 뒤의 이야기지만 Prometheus 지표는 아무도 페이지를 울리기 전에 지연이 서서히 표류했는지 보여줍니다. 2026년 성숙한 OpenClaw 배포는 /metrics(또는 형제 관리 포트)에 텍스트 지표를 노출해 SRE가 예측 가능한 카디널리티와 일관된 이름으로 스크레이프하고 추적이 켜졌을 때만 exemplar를 붙입니다. 이 글은 스크레이프 토폴로지, 히스토그램과 서머리의 트레이드오프, 라벨 위생, 기존 헬스 체크·로그 파이프라인과의 짝짓기, LaunchAgent 타이머로 Mac mini에서 프로덕션 간격을 재현하는 방법을 다룹니다. 서문에서 함께 읽을 게이트웨이 헬스 모니터링과 업타임 프로브, 로그 마스킹과 logrotate 규율, 업그레이드·이전 체크리스트, nginx 롤링 컷오버를 위한 트래픽 드레인을 병행하면 배포 창에서 알림·로그·지표의 세 축이 맞습니다.
가격 맥락: MacHTML 클라우드 Apple Silicon은 대략 $16.9/일로 디자이너 노트북을 빌리지 않고도 프로덕션과 동일한 스크레이프 설정을 돌릴 전용 리허설 호스트를 유지할 수 있습니다.
게이트웨이에 일급 Prometheus가 필요한 이유
모놀리식 웹앱과 달리 게이트웨이는 수많은 비동기 스트림을 멀티플렉스합니다. WebSocket 도구 호출, HTTP 배칭, 공급자 재시도, 파일 부작용이 겹칩니다. 단일 p99 스파이크가 집계 CPU 차트에 안 보일 수 있는데 작업이 워커 사이로 옮겨졌기 때문입니다. Prometheus 카운터와 히스토그램은 신중한 계기부착으로 요청량·에러 코드·큐 깊이·공급자별 백오프 창을 낮은 오버헤드로 포착합니다. 없으면 운영자는 꼬리 샘플링에 의존해 청구서가 오기 전까지 드물지만 비싼 도구 호출을 놓칩니다.
OpenClaw 아키텍처는 부분 장애도 전제합니다. 한 공급자가 저하되어도 다른 곳은 건강할 수 있습니다. 지표는 라우트별 성공 비율을 보여주되 수천 가지 라벨 조합은 만들고 싶지 않습니다. 관측 가능성 대 카디널리티 긴장이 아래 모든 절의 줄기입니다.
정적 호스팅이나 CDN과 병행할 때도 CDN에 풀 APM을 두기 어려워도 게이트웨이 프로세스 안에 큐와 오류의 최소 집합을 남기면 나중에 마스킹된 로그에 앵커를 걸 수 있습니다.
/metrics 리스너 스크레이프 설계
mTLS와 엄격한 ACL이 보장되지 않는 한 지표를 고객 트래픽과 같은 소켓에 두지 마세요. 관례는 게이트웨이 호스트의 127.0.0.1:9108에 바인딩하고 node_exporter 사이드카나 Prometheus 에이전트가 SSH 터널이나 VPC 피어링으로 긁어갑니다. 원격 공개가 필요하면 nginx에서 TLS를 종료하고 내부 PKI 클라이언트 인증서를 요구합니다.
scrape_configs:
- job_name: openclaw-gateway
scrape_interval: 15s
metrics_path: /metrics
static_configs:
- targets: ['gateway-prod.internal:9108']Prometheus의 stale 의미를 존중하세요. 배포 중 스크레이프가 실패하면 그래프는 거짓이 아니라 비어야 합니다. 스크레이프 간격을 systemd나 LaunchAgent 재시작 예산과 맞추고 부팅 직후 첫 스크레이프가 차가운 JIT 스파이크와 겹쳐 오토스케일러를 속이지 않게 합니다.
서비스 디스커버리로 여러 인스턴스를 등록한다면 instance와 job을 일관되게 두고 relabel로 환경 비밀을 제거합니다. 다중 리전이면 region 같은 저카디널리티 차원으로 면을 나누세요.
2026년 히스토그램과 서머리
네이티브 히스토그램은 서버가 구조화된 버킷을 내고 Prometheus가 레플리카 간에 일관되게 분위수를 계산합니다. 클라이언트 서머리는 사전 계산 분위수를 내지만 Pod 간에 안전하게 평균할 수 없습니다. OpenClaw 게이트웨이에서는 요청 지연과 도구 지속 시간에 히스토그램을 선호하고 버킷 경계를 SLO 임계에 맞춥니다(예 250ms,500ms,1s,2s,5s). 제어할 수 없는 SDK에는 서머리도 허용되나 같은 메트릭 이름에 둘을 섞지 마세요.
Exemplar는 추적으로 다리를 놓습니다. 꼬리 샘플링이 허용할 때만 trace id를 붙이고 민감한 고객 식별자는보내기 전에 제거합니다. macOS 리허설 호스트에서는 기본으로 exemplar를 끄고 로컬 TSDB를 작게 유지합니다.
Grafana 히트맵과 알림 임계를 문서화해 운영·개발이 같은 SLO 사전을 공유하면 리뷰가 빨라집니다.
카디널리티 가드레일
고유 라벨 집합마다 시계열이 생깁니다. 게이트웨이는 API 키·모델 이름·테넌트 UUID·파일 경로로 라벨하고 싶어집니다—하지 마세요. 대신 provider="anthropic" 같은 유계 라벨을 내고 고카디널리티 차원은 로그 기사에서 설명한 위생으로 마스킹된 구조화 로그로 보냅니다. 커스텀 지표는 프로세스당 활성 200 시리즈 미만( Go 런타임 기본 제외) 같은 단단한 예산을 둡니다.
레코딩 룰로 도구 호출을 코호트로 접습니다: sum by (route)(rate(openclaw_tool_calls_total[5m]))는 컴파일 타임에 닫힌 열거가 아니면 도구 ID별로 보내기보다 안전합니다.
멀티테넌트 SaaS에서 “테넌트별 지연”이 꼭 필요하면 Prometheus에 테넌트 라벨을 늘리기 전에 쿼리 계층이나 과금 웨어하우스를 검토하세요. 인기 테넌트가 스크레이프 비용과 압축 지연을 부풀립니다.
헬스 체크·로그와 짝짓기
지표는 합성 프로브 트래픽을 복제하지 말고 보완해야 합니다. 헬스 체크는 밖에서 “포트가 열렸나”, 카운터는 안에서 “큐가 줄었나”에 답합니다. 프로브가 빨갛게 바뀔 때 gateway_errors_total이 오르고 히스토그램이 멈추도록 대시보드를 배선합니다. 링크된 이전 체크리스트를 따르는 업그레이드에서는 스크레이프 성공률이 두 간격 이상 다섯 아홉 아래로 떨어지면 오토스케일을 잠시 멈춥니다.
로그 파이프라인에 새 마스킹 규칙이 들어가면 “어떤 라벨이 어떤 로그 필드와 조인되는지” 표를 남겨 심야 당직이 임시 쿼리를 발명하지 않게 합니다.
nginx 드레인 중 스크레이프 조정
롤링 컷오버는 프로세스가 나가기 전에 업스트림 가중치를 옮깁니다. 서비스 디스커버리가 늦으면 Prometheus가 종료 중인 Pod에 잠깐 맞을 수 있습니다. 드레인이 시작되는 순간 엔드포인트가 SD에서 사라지게 레디니스 게이트를 쓰고 서문의 nginx 가이드와 맞춥니다. nginx를 통해 스크레이프한다면 전용 location과 IP 허용 목록을 추가하고 무관한 일정으로 돌아가는 공개 TLS 인증서를 재사용하지 마세요.
듀얼 홈이나 다중 입구면 Grafana 주석에 가중치 변경 타임스탬프를 남겨 스크레이프 실패 창과 트래픽 곡선을 사후에 맞춥니다.
로컬 스크레이퍼 LaunchAgent
개발자 노트북과 클라우드 Mac mini에서는 LaunchAgent가 cron보다 타이밍이 정확하고 unified logging으로 흘립니다. 매분 localhost에 가벼운 promtool check metrics curl을 돌려 CI보다 먼저 exposition 퇴행을 잡습니다.
<key>StartInterval</key>
<integer>60</integer>에이전트는 비특권으로 두고 bearer 토큰을 plist에 쓰지 마세요. 권한이 맞는 작은 헬퍼가 키체인에서 읽습니다.
같은 호스트에서 카나리와 스테이블을 병행하면 metrics 포트를 나누고 plist 라벨로 섞임을 방지합니다.
클라우드 Mac 패리티 테스트
클라우드 Mac mini는 Apple 스케줄러와 파일 시스템 대소문자 기본값, TLS 스택 특이를 재현합니다. 보존 기간을 줄인 프로덕션 스크레이프 설정을 미러링하고 부하 생성기를 돌리며 TSDB 압축 지연을 봅니다. 대략 $16.9/일이면 공유 스테이징에 부담스러운 며칠짜리 소크도 현실적입니다.
리허설 스크립트에 케이블 분리, DNS 전환, 공급자 응답 인공 지연을 넣어 버킷이 여전히 실행 가능한 신호를 내는지 검증합니다.
보안: TLS와 관리면 분리
지표 엔드포인트는 운영 세부를 새어 나옵니다: 큐 이름, 의존 버전, 서킷 브레이커 상태. 네트워크 정책, SSH 터널, 제로트러스트 메시로 보호합니다. JSON 디버그와 Prometheus 텍스트를 나란히 두면 content-type이 충돌하지 않게 하고 DNS 전환 중 실수로 노출된 관리 포트가 크롤러에 긁히지 않게 합니다.
규제 산업에서는 비즈니스 API뿐 아니라 metrics URL에 접근한 주체도 감사 로그에 남겨야 합니다.
SLO: 번 레이트와 레코딩 룰
게이트웨이 지연과 오류 비율에 SLI를 정의하고 다중 창 번 알람으로 사상합니다. 레코딩 룰로 5분·1시간 비율을 미리 계산해 대시보드를 가볍게 합니다. 임계값은 추측이 아니라 과거 사고로 검증하고 메트릭 패널에서 요청 ID로 필터한 로그로 이어지는 런북 링크를 둡니다.
인간 지원 시간대와 야간 배치에서 타는 패턴이 다르면 규칙을 나눠 야간의 합법적 스파이크가 주간 체감을 지우지 않게 합니다.
매트릭스:보낼 것과 버릴 것
| 신호 | 보낼까 | 메모 |
|---|---|---|
| 요청 UUID | 아니오 | 마스킹 로그로. |
| 큐 깊이 게이지 | 예 | 백프레셔 가시성 핵심. |
| 공급자 429 카운터 | 예 | 유계 라벨. Retry-After와 상관. |
| 힙 샘플 | 아니오 | pprof는 별도 인증. |
번호 매긴 롤아웃 체크리스트
- 기존 지표를 재고하고 예산을 넘는 시리즈를 삭제합니다.
- 히스토그램 버킷을 SLO 임계에 맞추고 경계를 문서화합니다.
- TLS·ACL·비밀을 벗기는 relabel이 있는 스크레이프 구성을 배선합니다.
- 드레인 동작을 시험해 종료된 Pod가 스크레이프가 돌아오기 전에 SD에서 사라지는지 확인합니다.
- 클라우드 Mac에서 합성 부하 아래 프로브와 지표를 함께 검증합니다.
- 배포 창 주석이 달린 Grafana를 출하합니다.
- macOS 호스트에서 LaunchAgent 카나리로 exposition 드리프트를 일찍 잡습니다.
- 보존 정책을 검토하고 로컬 연습 Prometheus는 공격적으로 다운샘플합니다.
자주 묻는 질문
게이트웨이 호스트에 Prometheus를 둘까요?
보통 아니오. 중앙 TSDB로 원격 스크레이프해 폭발 반경을 줄입니다.
OpenTelemetry는요?
OTLP는 보완입니다. PromQL 표준 팀을 위해 exposition으로 변환할 수 있습니다.
CI에서 카디널리티 퇴행을 어떻게 테스트하나요?
통합 테스트 후 시리즈 수를 스냅샷하고 검토 없는 새 라벨이면 빌드를 실패시킵니다.
신뢰할 수 있는 지표는 업타임 체크와 구조화 로그와 같은 신뢰성 프로그램의 일부입니다. MacHTML 전용 Mac mini(대략 $16.9/일)에서 스크레이프 경로를 리허설하면 프로덕션 Prometheus에 도착하기 전에 TLS·네트워크·타이밍 이슈를 잡을 수 있습니다.
클라우드 Mac mini에서 OpenClaw 지표 리허설
프로덕션 스크레이프 설정을 미러링하고 TSDB 카디널리티를 프로파일하며 실제 macOS에서 LaunchAgent 간격을 검증한 뒤 관측 가능성 변경을 머지하세요.