`debug` — 디버그 패키지 수집하기

vault debug는 Vault 서버를 모니터링하고, 특정 기간 동안 그 서버에 대한 정보를 수집하는 프로세스를 시작하는 명령어예요.

Vault 클러스터의 상태에 대한 정보를 모으려면 운영자(operator)가 다양한 API 호출과 터미널 명령을 통해 필요한 모든 정보에 접근해야 하는 경우가 많아요. debug 명령어는 일관된 출력을 만들어 운영자가 해당 서버에 대한 정보를 검색하고 공유하는 데 도움을 주는 간단한 워크플로우를 제공하는 것을 목표로 해요.

debug 명령어는 기본 명령어가 허용하는 변수들과 동일한 변수를 존중해요. 예를 들어 이전 login으로 저장된 토큰이나 VAULT_TOKEN, VAULT_ADDR 환경 변수 등이에요. 사용된 토큰이 권한을 결정하고, 따라서 debug가 수집할 수 있는 정보를 결정해요. 지정된 주소는 프로빙(probe)할 대상 서버를 결정해요.

명령어가 중단되면 그 시점까지 수집된 정보가 출력 디렉터리에 저장돼요.

출처: 문서

본문

권한 (Permissions)

특정 대상(target)이 주어졌는지와 관계없이, 대상의 데이터를 가져올 수 있는 debug의 능력은 제공된 토큰에 달려 있어요. server-status 같은 일부 대상은 인증되지 않은 엔드포인트를 조회하는데, 이는 항상 조회할 수 있다는 뜻이에요. 다른 대상은 적절한 응답을 받으려면 토큰이 일치하는 엔드포인트를 조회할 수 있는 ACL 권한을 요구해요. 권한이나 다른 이유로 캡처 중 발생한 오류는 index 파일에 기록돼요.

모든 대상으로 디버그 패키지를 생성할 때 쓸 수 있는 정책은 다음과 같아요:

path "auth/token/lookup-self" {
  capabilities = ["read"]
}

path "sys/pprof/*" {
  capabilities = ["read"]
}

path "sys/config/state/sanitized" {
  capabilities = ["read"]
}

path "sys/monitor" {
  capabilities = ["read"]
}

path "sys/host-info" {
  capabilities = ["read"]
}

path "sys/in-flight-req" {
  capabilities = ["read"]
}

캡처 대상 (Capture targets)

-target 플래그는 여러 번 지정해서 debug 실행 중 특정 정보를 캡처할 수 있어요. 기본적으로는 모든 정보를 캡처해요.

참고로 config, host, metrics, pprof 대상은 정보가 로컬 노드에 관한 것이고 요청이 전달되지 않아야 하기 때문에 활성(active) 노드와 퍼포먼스 스탠바이(performance standby) 노드에서만 조회돼요.

추가로, host 정보는 cgo를 활성화하지 않고 데이터를 가져오는 라이브러리 제한 때문에 OpenBSD 플랫폼에서는 사용할 수 없어요.

[Enterprise] unauthenticated_metrics_access가 활성화되어 있으면 DR 세컨더리 활성 노드에서도 metrics 대상으로 텔레메트리(telemetry)를 수집할 수 있어요.

출력 구조 (Output layout)

묶인 정보의 출력은 압축을 풀면 하나의 디렉터리에 담겨요. 프로파일링 데이터를 제외한 각 대상은 단일 파일로 캡처돼요. 각 대상의 수집은 JSON 배열 객체로 표현되며, 각 간격(interval)마다 캡처된 각 항목이 JSON 객체로 담겨요.

$ tree vault-debug-2019-10-15T21-44-49Z/
vault-debug-2019-10-15T21-44-49Z/
├── 2019-10-15T21-44-49Z
│   ├── goroutine.prof
│   ├── heap.prof
│   ├── profile.prof
│   └── trace.out
├── 2019-10-15T21-45-19Z
│   ├── goroutine.prof
│   ├── heap.prof
│   ├── profile.prof
│   └── trace.out
├── 2019-10-15T21-45-49Z
│   ├── goroutine.prof
│   ├── heap.prof
│   ├── profile.prof
│   └── trace.out
├── 2019-10-15T21-46-19Z
│   ├── goroutine.prof
│   ├── heap.prof
│   ├── profile.prof
│   └── trace.out
├── 2019-10-15T21-46-49Z
│   ├── goroutine.prof
│   └── heap.prof
├── config.json
├── host_info.json
├── index.json
├── metrics.json
├── replication_status.json
└── server_status.json

예시 (Examples)

합리적인 기본값으로 디버그를 시작해요:

$ vault debug

다른 기간(duration), 간격(interval), 메트릭 간격 값을 사용하고 압축을 건너뛰고 디버그를 시작해요:

$ vault debug -duration=1m -interval=10s -metrics-interval=5s -compress=false

특정 대상으로 디버그를 시작해요:

$ vault debug -target=host -target=metrics

사용법 (Usage)

모든 명령어에 기본으로 포함된 표준 플래그 외에 다음 플래그들을 추가로 사용할 수 있어요.

커맨드 옵션 (Command options)

-compress (bool: true) — 출력 패키지를 압축할지 여부를 전환해요. 기본값은 true예요.
-duration (int 또는 시간 문자열: "2m") — 명령어를 실행할 기간. 기본값은 2m0s예요.
-interval (int 또는 시간 문자열: "30s") — 프로파일링 데이터와 서버 상태를 수집할 폴링 간격. 기본값은 30s예요.
-log-format (string: "standard") — log 대상을 지정했을 때 캡처할 로그 형식. 지원 값은 "standard"와 "json". 기본값은 "standard"예요.
-metrics-interval (int 또는 시간 문자열: "10s") — 메트릭 데이터를 수집할 폴링 간격. 기본값은 10s예요.
-output (string) — 디버그 패키지의 출력 경로를 지정해요. 기본값은 시간 기반으로 생성된 파일 이름.
-target (string: 모든 대상) — 캡처할 대상. 지정하지 않으면 전부로 기본 설정돼요. 여러 대상을 캡처하려면 여러 번 지정할 수 있어요. 사용 가능한 대상: config, host, metrics, pprof, replication-status, server-status.

더 알아보기 (Learn more)

vault monitor — 서버 로그 실시간 확인
vault status — 서버 상태 확인
Vault 운영 문서

`debug` — 디버그 패키지 수집하기