UCP Watchdog 구축하기: CI가 절대 잡아내지 못하는 운영 환경의 장애 포착하기

당신은 UCP 검증을 CI(지속적 통합)에 연결했습니다. 모든 푸시(push)마다 체크가 실행되고, 모든 PR(Pull Request)은 점수를 받으며, 잘못된 프로필은 머지(merge)되기 전에 빌드를 실패하게 만듭니다. 좋습니다. 그것이 올바른 기준선입니다.

하지만 이것이 잡아내지 못하는 것이 있습니다. 바로 아무도 코드를 건드리지 않을 때 발생하는 장애입니다.

여기서의 표준은 UCP (Universal Commerce Protocol)입니다. 이는 AI 쇼핑 에이전트에게 /.well-known/ucp 경로를 통해 상점에 대한 기계 판독 가능한(machine-readable) 진입점을 제공하는 개방형 표준입니다. (간단한 면책 조항: UCP는 Google과 Shopify가 소유하고 유지 관리합니다. 제가 작업하고 있는 UCPtools는 독립적인 커뮤니티 도구이며, 두 기업과 관련이 없습니다.)

CI 게이트(gate)는 당신의 커밋(commit)에 의해 트리거됩니다. 하지만 UCP 프로필은 라이브 운영 환경(production surface)이며, 이를 망가뜨리는 대부분의 요소는 커밋과 전혀 무관합니다:

TLS 인증서가 갱신되었으나, 오리진(origin)에는 전파되었지만 모든 CDN 에지(edge)에는 전파되지 않은 경우.
프로필이 참조하는 기능 스키마(capability schema) 호스트가 다운된 경우 - 타인의 장애가 당신의 프로필 장애로 이어집니다.
CDN 또는 DNS 변경으로 인해 /.well-known/ucp에서 캐시 페이지나 리다이렉트(redirect)가 서빙되기 시작한 경우.
당신의 플랫폼(Shopify, BigCommerce, WooCommerce 플러그인 업데이트 등)이 서빙되는 매니페스트(manifest)를 조용히 변경하거나 Content-Type: application/json 헤더를 제거한 경우.
인프라에서 **서명 키(signing key)가 로테이션(rotate)**되었으나 게시된 프로필에는 반영되지 않은 경우.

이 중 어느 것도 빌드를 트리거하지 않습니다. 왜냐하면 빌드 자체가 일어나지 않기 때문입니다. 당신의 CI는 초록불(green)입니다. 당신의 상점은 인간 브라우저에게는 잘 작동합니다. 유일하게 퇴보한 것은 그 어떤 인간도 방문하지 않는 기계 판독 가능한 레이어뿐이며, 여기에 접속하는 AI 에이전트는 버그 리포트를 제출하지 않습니다. 그저 프로필에 응답하는 다음 상인에게로 떠나버릴 뿐입니다.

CI는 머지 시점에 당신이 망가뜨린 것을 잡아냅니다. 와치독(watchdog)은 스스로 망가지는 것을 잡아냅니다. 당신에게는 둘 다 필요합니다.

와치독이 실제로 감시하는 것

머지 전 게이트(pre-merge gate)는 "내가 배포하려는 프로필이 유효한가?"라고 묻습니다. 와치독은 정해진 일정에 따라 다른 질문을 던집니다. "지금 당장 라이브 상태인 프로필이 외부에서, 즉 에이전트가 보는 방식 그대로 여전히 유효한가?"

두 가지 설계 규칙이 그 차이를 만듭니다:

자신의 네트워크 외부에서 확인하십시오 (Check from outside your network). 자체 인프라 내부에서 실행되는 체크는 따뜻한 캐시 (warm cache)를 타거나 내부 경로 (internal route)를 통해 접근하여, 외부 에이전트가 에러를 겪고 있음에도 정상(healthy)이라고 보고할 수 있습니다. 공용 인터넷을 통해 여러분의 퍼블릭 URL (public URL)을 호출하십시오.
단순히 통과/실패 여부만이 아니라, 기준점 (baseline)과 비교하십시오. 프로필의 점수가 A에서 C로 조용히 미끄러지는 동안에도 기술적으로는 유효한 상태를 유지할 수 있습니다. 단순한 하드 실패 (hard failures)뿐만 아니라, 이미 검증된 기준점 (baseline)으로부터의 퇴보 (regression)에 대해 알림을 설정하십시오.

두 가지 방식으로 구축해 보겠습니다: 의존성이 없는 cron 버전과 Slack 알림 기능이 포함된 GitHub Action 버전입니다.

10줄 버전: cron + curl

UCPtools는 라이브 도메인의 프로필을 가져와 서버 측에서 체크를 실행하는 퍼블릭 원격 검증 엔드포인트 (public remote-validation endpoint)를 제공합니다. curl과 jq를 실행할 수 있는 무엇이든 여기서 호출할 수 있습니다:

#!/usr/bin/env bash
# ucp-watch.sh - 라이브 UCP 프로필이 깨졌을 경우 알림을 보냅니다
DOMAIN="mystore.com"
...

엔드포인트는 다음과 같은 형태의 라이브 결과를 반환합니다:

{
  "ok": false,
  "profile_url": "https://mystore.com/.well-known/ucp",
...

이를 스케줄링하면 워치독 (watchdog)이 완성됩니다:

*/15 * * * * SLACK_WEBHOOK_URL=https://hooks.slack.com/... /opt/ucp-watch.sh

이제 인증서 갱신 후 몇 시간이 지났고 별도의 배포(deploy)도 없었는데 새벽 3시에 UCP_SCHEMA_FETCH_FAILED나 UCP_ENDPOINT_NOT_HTTPS가 나타난다면, 에이전트 트래픽을 조용히 잃는 대신 여러분의 페이지가 호출될 것입니다.

GitHub Action 버전: 기준점이 포함된 스케줄링 방식

만약 여러분의 스토어가 이미 GitHub에 있다면, 동일한 아이디어를 schedule: 트리거로 실행하고 기존의 ucp-validate-action을 재사용할 수 있습니다. 이는 사람들이 CI에 넣는 것과 동일한 액션이지만, **라이브 프로덕션 도메인 (live production domain)**을 대상으로 하며 푸시(push) 시점이 아닌 시계(clock)에 따라 실행된다는 점이 다릅니다. 차이점은 전적으로 트리거와 결과를 처리하는 방식에 있습니다.

name: UCP Watchdog
on:
  schedule:
...

처음으로 상태가 정상(green)이 되었을 때, 한 줄짜리 기준점 (baseline) 파일을 커밋하십시오:

echo 90 > .ucp-baseline   # 검증된 양호한 점수

이 액션(action)은 score, grade, ucp-found, passed, 그리고 result-json을 노출하므로, 여러분이 원하는 어떤 경고 로직(alerting logic)이라도 그 위에 구축할 수 있습니다. 핵심은 트리거는 시계(clock)이고, 대상은 운영 환경(production)이며, 비교 대상은 마지막으로 확인된 양호한 상태(last known-good state)라는 점입니다.

경고 위생 (Alert Hygiene) (경고를 무시하는 습관이 들지 않도록)

양치기 소년처럼 울어대는 워치독(watchdog)은 음소거(muted) 처리되며, 음소거된 워치독은 없는 것보다 더 나쁩니다. 워치독의 신뢰성을 유지하기 위한 세 가지 요소는 다음과 같습니다:

단순한 통과/실패(pass/fail)가 아닌 기준점(baseline)을 활용하십시오. A 등급에서 C 등급으로 서서히 떨어지는 현상은 여러분이 가장 알고 싶어 하는 회귀(regression)이지만, 이진법적인 "여전히 유효한가?" 식의 체크는 이를 완전히 놓칠 것입니다. 점수(score)의 차이(diff)를 확인하십시오.
플랩(flaps, 상태가 급격히 변하는 현상)을 디바운스(debounce)하십시오. 단 한 번의 페치(fetch) 실패는 일시적인 네트워크 오류일 수 있습니다. 페이지(paging)를 보내기 전에 두 번 연속으로 잘못된 체크가 발생해야 하거나, 단일 데이터 포인트가 아닌 지속적인 하락에 대해 경고를 보내도록 설정하십시오.
개선되었을 때는 기준점을 높이십시오. 점수를 정당하게 높였다면, 동일한 PR에서 .ucp-baseline을 업데이트하십시오. 기준점은 래칫(ratchet)과 같습니다. 의도적으로 위로만 움직여야 합니다.

플랫폼 참고 사항

이 워치독은 플랫폼에 구애받지 않습니다(platform-agnostic). 플랫폼 내부 구조가 아닌 공개된 /.well-known/ucp 표준을 읽기 때문입니다. 하지만 여러분에게 페이지를 보내게 만드는 회귀(regression)의 양상은 스택(stack)마다 다를 수 있습니다:

WooCommerce: 캐싱 또는 보안 플러그인 업데이트로 인해 /.well-known/ucp를 캐시에서 제공하거나, 챌린지(challenge) 뒤에 숨기거나, text/html 형식으로 제공하기 시작하는 경우.
BigCommerce / headless: 프론트엔드 배포 또는 앱 변경으로 인해 프로필이 여전히 광고하고 있는 엔드포인트(endpoint)가 이동하거나, 스토어프론트 범위(storefront-scope) 불일치가 발생하는 경우.
Shopify: 플랫폼 측에서 well-known 경로에서 제공하는 내용을 여러분의 통제 밖에서 변경하는 경우.

모든 경우에서, 외부에서 라이브 프로필을 가져와 예상치와 비교하기 전까지는 실패가 보이지 않습니다. 그것이 바로 워치독의 전체 역할입니다.

CI는 당신이 작성한 프로필이 올바르다는 것을 증명합니다. 워치독(Watchdog)은 고객의 에이전트(agent)가 실제로 호출하는 프로필이 새벽 3시에도, 인증서(cert) 갱신 후에도, 그리고 아무도 아무것도 배포하지 않았을 때에도 여전히 올바른지를 증명합니다. 두 가지 모두 몇 줄의 YAML로 구현됩니다. 에이전트 기반 커머스(agentic-commerce) 전환기에서 승리할 상인들은 두 번째 요소를 가동 시간(uptime)처럼 취급할 것입니다. 왜냐하면 그것이 정확히 가동 시간 그 자체이기 때문입니다.

직접 운영하고 싶지 않다면, UCPtools는 4가지 모든 검증 단계에서 장애 알림(break-alerts)을 포함한 호스팅 모니터링을 제공합니다 - 여기서 시작하세요. 어떤 방식이든: 빌드(build)뿐만 아니라 라이브 프로필(live profile)을 감시하십시오.

UCP는 Google과 Shopify가 만든 오픈 표준입니다. UCPtools는 독립적인 커뮤니티 도구입니다.
_ UCPtools의 Peter가 제작했습니다._