2026년 OpenClaw Gateway Prometheus 지표와 Grafana 보기: 원격 물리 Mac 7×24에서 /metrics 스크랩·알림 임계값·전형적 오탐 분기(복붙 scrape·패널 쿼리 + FAQ)

2. 페인 포인트

1. 제약: 바인드 주소 vs Prometheus 위치. 게이트웨이가 127.0.0.1에만 있고 Prometheus가 컨테이너나 별도 관측 호스트에 있으면 스크랩은 실패(up=0)하지만 Mac 로컬 curl은 성공합니다.
2. 숨은 비용: 고카디널리티 라벨·과도한 scrape_interval. 경로나 API 키 조각을 라벨에 넣으면 TSDB 카디널리티가 폭발하고, 1초 스크랩·Wi‑Fi·터널은 지터가 Grafana 차트에 “털”로 남습니다.
3. 안정성·오탐: macOS 절전·배포 창. 디스플레이 절전, 디스크 절전, 핫 리로드가 p95를 잠깐 올릴 수 있고 for: 0s 알림은 새벽 온콜을 시끄럽게 합니다.

3. 스크랩·알림 의사결정 매트릭스

가동 전에 「누가 어떤 네트워크 네임스페이스에서 스크랩하는지」와 알림이 업무 시간을 존중할지 합의하세요.

4. 7단계 런북(원격 물리 Mac)

1. 엔드포인트·바인드 확인. 게이트웨이 설정에서 메트릭 활성화, metrics_path(보통 /metrics)와 리슨 IP 확인. 원격 스크랩이면 스크래퍼와 네임스페이스를 공유하지 않는 한 127.0.0.1 전용은 피합니다.
2. 로컬 스모크. curl -sS http://127.0.0.1:<port>/metrics | head -n 40로 HTTP·프로세스 메트릭의 HELP/TYPE 줄 확인.
3. 스크래퍼 위치 선택. 단일 노드 PoC: 공존 Prometheus. 다수 노드: vmagent remote-write 또는 방화벽 허용이 있는 중앙 Prometheus.
4. 스크랩 설정 작성(아래). scrape_interval: 15s–30s, 적절한 scrape_timeout, 안정적인 instance relabel.
5. Grafana 연결. Prometheus 데이터 소스 추가, 전역 RPS·p95·5xx 비율·up·스크랩 지속 시간 패널.
6. 알림·라우트. 오류 비율과 raw up에 서로 다른 for, 배포 중엔 Alertmanager 침묵 또는 CI 유지보수 플래그.
7. macOS 7×24 설정 정렬. 유선 이더넷 선호, 디스크 절전 끄기, 타임존·NTP 고정. 스크랩은 정상인데 앱이 500을 내는 경우 메트릭보다 애플리케이션 로그를 먼저 봅니다.

5. 복붙 scrape·PromQL·알림

5.1 Prometheus scrape_configs 조각

targets와 포트를 게이트웨이 주소에 맞게 바꿉니다. 역프록시 뒤라면 /metrics 경로를 통과시키고 해당 경로는 캐시 비활성화.

scrape_configs:
  - job_name: openclaw-gateway
    scrape_interval: 15s
    scrape_timeout: 10s
    metrics_path: /metrics
    static_configs:
      - targets:
          - '127.0.0.1:18789'
        labels:
          env: prod
          role: gateway
    # relabel_configs:
    #   - source_labels: [__address__]
    #     target_label: instance

5.2 Grafana 패널 쿼리(호스트 메트릭 이름에 맞게 치환)

• 초당 요청(RPS): sum(rate(http_requests_total{job="openclaw-gateway"}[5m]))
• p95 지연(히스토그램): histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket{job="openclaw-gateway"}[5m])) by (le))
• 5xx 비율(예시): sum(rate(http_requests_total{job="openclaw-gateway",status=~"5.."}[5m])) / sum(rate(http_requests_total{job="openclaw-gateway"}[5m]))
• 스크랩 상태: up{job="openclaw-gateway"} 및 scrape_duration_seconds{job="openclaw-gateway"}

5.3 알림 규칙(Prometheus rule_files)

groups:
  - name: openclaw_gateway
    rules:
      - alert: GatewayScrapeDown
        expr: up{job="openclaw-gateway"} == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "OpenClaw metrics endpoint not reachable"
      - alert: GatewayHigh5xxRatio
        expr: sum(rate(http_requests_total{job="openclaw-gateway",status=~"5.."}[5m])) / sum(rate(http_requests_total{job="openclaw-gateway"}[5m])) > 0.05
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "5xx ratio > 5% (adjust labels to your schema)"

메트릭이 status 대신 code나 outcome 라벨을 쓰면 셀렉터를 고칩니다. 알림으로 올리기 전에 Grafana Explore에서 빈 벡터가 아닌지 확인하세요.

6. 전형적 오탐 트리아지

7. 인용 가능 임계값

• scrape_interval: 프로덕션 15s(게이트웨이 꼬리 지연 없이 더 빠르게 쓸 이유가 없으면); 대륙 간 링크는 30s.
• scrape_timeout: scrape_interval의 ~2/3 이하 유지, 터널 경로는 10s부터.
• 알림 for: 가용성 스타일 2m, 비율 규칙 5m 후 SLO 번 레이트에 맞춰 조정.

8. FAQ

9. 마무리·노드 선택

OpenClaw Gateway의 HTTP·프로세스 메트릭이 Prometheus·Grafana에 들어오면 24/7 물리 노드의 장애 대응이 「SSH로 감」에서 up·오류율·p95가 함께 움직이는지 확인하는 쪽으로 바뀝니다. 반복되는 포인트는 바인드 주소와 스크래퍼 네트워크 경로 일치, 알림에 for, macOS 절전·배포 창을 SLO 노이즈에서 분리입니다.

이 「게이트웨이 + 관측 스택」 흐름은 macOS와 잘 맞습니다. launchd, 로그, Unix 도구가 한 스택에 있고, Apple 실리콘은 대기 전력이 매우 낮아 상시 게이트웨이에 적합합니다. 비슷한 가격대의 작은 x86 박스보다 안정성·전력 효율에서 유리한 경우가 많고, Gatekeeper·SIP·FileVault가 자격 증명과 터미널 엔드포인트를 단단히 해 원격 운영자에게 중요합니다.

이 글의 스크랩 설정과 대시보드를 조용하고 효율적이며 7×24에 견디는 하드웨어에서 돌리고 싶다면 2026년 기준 Mac mini M4는 여전히 가성비 좋은 출발점입니다. ZoneMac으로 원격 물리 Mac을 쓰면 게이트웨이 메트릭을 프로덕션 기준선에 한 번에 넣기 좋습니다.