Monitor Data Connectivity Proxy

Monitor Data Connectivity Proxy (데이터 연결 프록시 모니터링)

DCP는 SQL 인터페이스와 에이전트의 Prometheus 메트릭 엔드포인트를 통해 관측성을 제공해요. DCP 클라이언트의 상태를 확인하고, 이벤트·연결 기록을 조회하며, 라우트 도달 가능성을 진단할 수 있어요.

출처: Snowflake Documentation

본문

DCP 클라이언트 설명

DESCRIBE DATA CONNECTIVITY PROXY로 DCP 클라이언트의 현재 상태를 확인해요. 이 명령은 행 하나를 반환해요. 객체에 대한 USAGE(DESCRIBE에 필요한 권한)가 필요해요. 클라이언트 이름을 따옴표로 묶어야 한다면 문장에서 따옴표를 사용해요:

DESCRIBE DATA CONNECTIVITY PROXY my_dcp_client;

DESCRIBE DATA CONNECTIVITY PROXY "quoted_client_name";

AGENT_HEALTH는 보고된 상태들의 파생 요약이에요. 자체 저장 필드가 아니며, 값은 HEALTHY, DEGRADED, DOWN이에요.

  • DOWN: AGENT_STATUS가 DCP_AGENT_LIFECYCLE_CONNECTED가 아님(상태를 한 번도 보고하지 않은 클라이언트 포함).
  • HEALTHY: 클라이언트가 연결되었고, bootstrap이 성공했으며, 인증서 교체가 실패하지 않았고, 데이터 경로가 실패하거나 진행 중이지 않음.
  • DEGRADED: 클라이언트가 연결되었지만 bootstrap 성공이 확인되지 않았거나, 인증서 교체나 데이터 경로가 건강하지 않음.

보고되지 않은 데이터 경로는 비정상으로 간주하지 않아요. 진행 중인 인증서 교체는 트래픽이 여전히 현재 인증서를 사용하므로 상태를 낮추지 않아요. LAST_HEARTBEAT_AT는 마지막 하트비트 타임스탬프이며, 하트비트는 이미 AGENT_HEALTH에 반영돼 있어요.

현재 상태에는 DESCRIBE를 사용해요. 이벤트 기록은 상태가 언제 진입했는지 기록하지, 지금 실제로 어떤 상태인지는 알려 주지 않아요.

출력에는 다음 컬럼이 포함돼요:

컬럼 설명
NAME DCP 클라이언트 이름
ENABLED 클라이언트가 활성화되었는지 여부
EXTERNAL_ACCESS_INTEGRATIONS 클라이언트와 연결된 외부 접근 통합. CREATE 또는 ALTER DATA CONNECTIVITY PROXY로 설정.
NETWORK_POLICY 클라이언트에 연결된 네트워크 정책(있는 경우)
COMMENT 클라이언트에 대한 메모(있는 경우)
AGENT_STATUS 컨트롤 플레인 수명 주기 상태(예: DCP_AGENT_LIFECYCLE_CONNECTED)
BOOTSTRAP_STATUS 최신 bootstrap 상태(예: DCP_AGENT_BOOTSTRAP_SUCCEEDED)
BOOTSTRAP_FAILURE_REASON 최신 bootstrap 실패 이유(있는 경우)
LAST_BOOTSTRAP_AT 최신 bootstrap 상태가 기록된 시각
CERT_ROTATION_STATUS 최신 컨트롤 플레인 인증서 교체 상태
LAST_CERT_ROTATION_AT 최신 인증서 교체 상태가 기록된 시각
OPERATIONAL_CERT_EXPIRES_AT 에이전트 현재 운영 인증서의 만료 시각
LAST_AUTH_FAILURE_REASON 최신 인증 실패 이유(있는 경우)
LAST_AUTH_FAILURE_AT 최신 인증 실패가 기록된 시각
DATA_PATH_STATUS 최신 데이터 경로 상태
AGENT_HEALTH 파생 요약: HEALTHY, DEGRADED, DOWN
AGENT_VERSION 클라이언트가 마지막으로 보고한 에이전트 버전
LAST_HEARTBEAT_AT 클라이언트가 마지막으로 하트비트를 보낸 시각
POLICY_APPLIED_EPOCH 에이전트가 마지막으로 적용한 정책 에포크
AUTH_TOKEN_EXPIRES_AT 에이전트 현재 인증 토큰의 만료 시각
POLICY_EPOCH 클라이언트의 현재 정책 에포크(정책 스냅샷이 전달될 때까지 NULL)
REACHABLE_DESTINATIONS 현재 정책이 허용하는 목적지(정책 스냅샷이 전달될 때까지 NULL)

이벤트 기록 조회

INFORMATION_SCHEMA.DCP_CLIENT_EVENT_HISTORY는 DCP 클라이언트의 기록된 상태 전환마다 행 하나를 반환해요. AGENT_ID는 필수이며 DESCRIBE에서 사용하는 것과 같은 DCP 클라이언트 이름이에요. 해당 클라이언트에 대한 USAGE가 필요해요. 없으면 Snowflake는 객체가 존재하지 않는 것처럼 처리해요.

행은 클라이언트가 OCCURRED_AT 시점에 해당 STATUS에 진입했음을 의미해요. 현재 상태가 아니에요. 현재 상태는 DESCRIBE를 사용해요. 인증 실패는 DESCRIBE(LAST_AUTH_FAILURE_REASON와 LAST_AUTH_FAILURE_AT)에 나타나며, 게시된 이벤트 유형이 아니에요.

SELECT *
FROM TABLE(INFORMATION_SCHEMA.DCP_CLIENT_EVENT_HISTORY(
  AGENT_ID => 'my_dcp_client'
))
ORDER BY occurred_at DESC;

컬럼: AGENT_ID, OCCURRED_AT, EVENT_TYPE, STATUS, REASON, RECORDED_AT.

EVENT_TYPE 값:

이벤트 유형 설명
BOOTSTRAP 에이전트 등록 및 bootstrap
CONTROL_PLANE 컨트롤 연결 수명 주기
CERT_ROTATION 컨트롤 플레인 자격 증명 갱신. Snowflake는 교체가 발생했을 때만 교체 행을 기록.
DATAPLANE_CERT_ROTATION 데이터 터널 자격 증명 갱신
DATA_PATH 데이터 경로 상태

STATUS 값: SUCCESS, FAILURE, PENDING, IN_PROGRESS. PENDING과 IN_PROGRESS는 행이 기록될 때 작업이 끝나지 않았음을 의미해요. 이후 행이 결과를 담아요.

REASON은 실패 시 DCP 오류 코드(예: DCP_BOOTSTRAP_TOKEN_INVALID, DCP_BOOTSTRAP_NETWORK_POLICY_BLOCKED)이거나 NULL이에요.

라우트 도달 가능성 확인

INFORMATION_SCHEMA.DCP_CLIENT_ROUTE_CHECK는 실시간 진단이에요. Snowflake에서 명명된 DCP 클라이언트를 거쳐 목적지까지의 라우트 각 단계마다 행 하나를 반환해요. 두 인자 모두 필수 상수예요. AGENT_ID는 DCP 클라이언트 이름, DESTINATION은 host:port예요. 클라이언트에 대한 USAGE가 필요해요.

SELECT *
FROM TABLE(INFORMATION_SCHEMA.DCP_CLIENT_ROUTE_CHECK(
  AGENT_ID => 'my_dcp_client',
  DESTINATION => 'my-private-db.internal:5432'
))
ORDER BY stage_order;

컬럼: AGENT_ID, STAGE_ORDER, STAGE, STATUS, DETAIL, REASON, CHECKED_AT.

순서대로 단계: EGRESS_CONFIG, POLICY, BOOTSTRAP, CONTROL_PLANE, CERTIFICATES, DATA_PATH, SNOWFLAKE_INTERNAL, DESTINATION.

STATUS 값: SUCCESS, FAILURE, IN_PROGRESS, SKIPPED, UNKNOWN.

  • SKIPPED: 이전 단계가 해결되지 않아 이 단계가 시도되지 않음. DETAIL이 먼저 고칠 게이트를 지목.
  • IN_PROGRESS: 호출자의 행동으로 여전히 답을 얻을 수 있음. DETAIL이 그 행동을 지목.
  • UNKNOWN: 사용자가 바꿀 수 있는 것이 이 단계의 답을 만들어내지 않음.

일부 단계는 클라이언트 텔레메트리를 사용해요. 해당 행은 계정에 텔레메트리가 도달 가능해질 때까지 비어 있거나 UNKNOWN이에요.

커넥터가 사설 소스에 도달할 수 없을 때 이 기능을 사용해요.

연결 기록 조회

INFORMATION_SCHEMA.DCP_CLIENT_CONNECTION_HISTORY는 DCP 클라이언트의 닫힌 연결마다 행 하나를 반환해요. 행은 계정 이벤트 테이블의 에이전트 텔레메트리 스팬(dcp.connection)에서 나와요. 클라이언트에 대한 USAGE가 필요해요. AGENT_ID는 필수(DCP 클라이언트 이름)이며, TIME_RANGE_HOURS는 선택 사항: 기본 24, 최소 1, 최대 2160(90일). 시간 창은 시작 시간이 아니라 기록 시간 기준이므로 STARTED_AT가 창보다 앞설 수 있어요.

SELECT *
FROM TABLE(INFORMATION_SCHEMA.DCP_CLIENT_CONNECTION_HISTORY(
  AGENT_ID => 'my_dcp_client',
  TIME_RANGE_HOURS => 24
))
ORDER BY recorded_at DESC;

컬럼: AGENT_ID, CONNECTION_ID, WORKLOAD_ID, DESTINATION_HOST, DESTINATION_PORT, STATUS, REASON, STARTED_AT, ENDED_AT, RECORDED_AT, SETUP_DURATION_MS, BYTES_TO_DESTINATION, BYTES_FROM_DESTINATION.

STATUS 값: SUCCESS, FAILURE, UNKNOWN. UNKNOWN은 누락된 이유와 드레이닝 중인 에이전트(shutting_down)를 모두 포함해요. 둘 다 연결을 확정하지 못했어요.

WORKLOAD_ID, 목적지 호스트·포트, SETUP_DURATION_MS는 값이 생기기 전에 연결이 거부되면 NULL일 수 있어요. 바이트 수는 항상 존재해요(터널이 트래픽을 운반하지 않은 경우 0). REASON은 정상 종료 시 NULL이에요.

Prometheus 메트릭 (에이전트 측)

에이전트는 기본적으로 127.0.0.1:9092에 Prometheus 메트릭 엔드포인트를 노출해요. Prometheus, Datadog, Grafana Agent 등 Prometheus 호환 모니터링 스택으로 이 엔드포인트를 수집해요. 같은 주소가 /ready 상태 프로브도 제공해요.

기본 바인딩을 사용하는 컨테이너 호스팅 에이전트는 컨테이너 밖에서 도달할 수 없어요. DCP_METRICS_PORT를 설정해 모든 인터페이스에 바인딩하고 포트를 게시해요:

docker run -d \
  --name dcp-agent \
  -e DCP_METRICS_PORT=9092 \
  -p 9092:9092 \
  ... snowflakedb/dcp-client:latest

주요 메트릭:

메트릭 유형 설명
agent_connections_active Gauge 현재 활성 연결 수
agent_connections_total Counter 상태별 처리된 연결, reason이 원인 명명(예: verification_failed, internal_error)
agent_destination_connect_seconds Histogram 목적지까지의 TCP 연결 시간
agent_handshake_duration_seconds Histogram 연결 요청부터 연결 응답까지의 전체 터널 설정 시간
agent_destination_errors_total Counter error_type별 목적지로의 실패한 TCP 연결
dcp_agent_bootstrap_jwt_expires_at_seconds Gauge bootstrap JWT의 만료 시각(Unix 타임스탬프, 클레임이 없거나 파싱 불가 시 0)
agent_cert_rotation_total Counter 컨트롤 플레인이 트리거한 에이전트 신원 교체 횟수

Note

dcp_agent_bootstrap_jwt_expires_at_seconds에 임계값 알림을 설정해 만료 최소 24시간 전에 발화하게 해, 에이전트가 인증서 갱신 능력을 잃기 전에 토큰을 교체할 시간을 확보해요.

릴레이 경로 선택

에이전트는 아웃바운드 포트에 나열된 릴레이 호스트 이름 중 하나를 통해 릴레이에 연결하며, 네트워크가 허용하는 것에 따라 자동으로 선택해요. agent_proxy_dial_path_used_total은 각 경로로 설정된 세션 수를 세며, path="direct" 또는 path="fallback" 레이블이 붙어요.

둘 다 완전히 지원되는 운영 경로예요. path="fallback"은 오설정이 아닌 정상적인 정상 상태이며, 많은 배포가 전적으로 이 경로로 운영돼요. 경로 레이블에 알림을 설정하지 마세요. 처리량이나 지연 문제를 조사한다면 먼저 처리량 확장을 참고해요. 릴레이 경로는 일반적인 원인이 아니에요.

메트릭 엔드포인트 주소 변경

다른 주소나 포트에서 수신하려면 --metrics-addr 플래그 또는 DCP_METRICS_ADDRESS 환경 변수로 전체 host:port를 설정해요:

docker run ... snowflakedb/dcp-client:latest \
  ... \
  --metrics-addr 0.0.0.0:9100

DCP_METRICS_PORT는 일반적인 컨테이너 사례를 위한 단축키예요. 단순 포트를 받아 0.0.0.0:<port>에 바인딩해요. --metrics-addr와 DCP_METRICS_ADDRESS가 이를 우선해요. DCP_METRICS_ADDRESS를 빈 값으로 설정하면 메트릭과 /ready 엔드포인트가 모두 비활성화돼요.

상태 확인

데이터 플레인 워커를 시작하지 않고 연결성을 검증하려면 에이전트 상태 확인을 실행해요:

docker run --rm \
  -v /etc/dcp-agent/secrets:/etc/dcp-agent/secrets:ro \
  snowflakedb/dcp-client:latest \
  --health-check \
  --sf-bootstrap-credentials /etc/dcp-agent/secrets/dcp-bootstrap-token

상태 확인은 전체 bootstrap 시퀀스(컨트롤 플레인 도달 가능, 토큰 유효, 포털 도달 가능, 프록시 도달 가능 검증)를 실행하고 각 단계에 대한 구조화된 통과/실패 결과를 출력해요.

컨테이너 오케스트레이션 상태 프로브를 위해 에이전트의 127.0.0.1:9092/ready 로컬 HTTP 엔드포인트도 사용할 수 있어요.

더 알아보기 (Learn more)