telemetry 스탠자

telemetry 스탠자 (stanza)

telemetry 스탠자는 Vault가 메트릭을 업스트림 시스템에 게시하기 위한 다양한 구성을 지정합니다. 사용 가능한 Vault 메트릭은 Telemetry internals 문서에서 찾을 수 있습니다.

출처: 문서

본문

telemetry {
  statsite_address = "statsite.company.local:8125"
}

Leader vs Standby 노드의 메트릭 telemetry 엔드포인트의 메트릭은 노드별입니다. 대부분의 경우 active leader 노드의 텔레메트리가 특히 초기 시작 후에 가장 유용합니다. 일부 메트릭(예: active vault.identity.* 메트릭)은 오직 leader 노드만 보고합니다.

`telemetry` 파라미터

telemetry 스탠자에 구성 가능한 파라미터가 많기 때문에 이 페이지의 파라미터는 텔레메트리 공급자별로 그룹화되어 있습니다.

공통(Common)

다음 옵션은 모든 텔레메트리 구성에서 사용할 수 있습니다.

usage_gauge_period (string: "10m") - 토큰 수, 엔티티 수, 시크릿 수 같은 높은 카디널리티 사용량 데이터를 수집하는 간격을 지정합니다. "none" 값은 수집을 비활성화합니다. 기간 형식 문자열(duration format strings)을 사용합니다.
maximum_gauge_cardinality (int: 500) - 게이지 라벨의 최대 카디널리티입니다.
disable_hostname (bool: false) - 게이지 값에 로컬 호스트 이름을 접두사로 붙일지 여부를 지정합니다.
enable_hostname_label (bool: false) - 모든 메트릭 값이 로컬 호스트 이름을 가진 host 라벨을 포함해야 하는지 여부를 지정합니다. 이 옵션을 사용한다면 disable_hostname을 활성화하는 것을 권장합니다.
metrics_prefix (string: "vault") - 메트릭 값에 사용되는 접두사를 지정합니다. 기본적으로 메트릭은 "vault"로 접두사가 붙습니다.
lease_metrics_epsilon (string: "1h") - 향후 임대 만료를 측정하는 데 사용되는 버킷의 크기를 지정합니다. 예를 들어 기본값 1시간의 경우 vault.expire.leases.by_expiration 메트릭은 현재 시간부터 1시간 버킷으로 만료되는 임대의 총 수를 집계합니다. 임대는 반올림하여 버킷에 넣습니다. 예를 들어 lease_metrics_epsilon이 1h이고 임대 A가 지금부터 25분 후 만료되고 임대 B가 35분 후 만료된다면 임대 A는 0-30분에 해당하는 첫 번째 버킷에, 임대 B는 31-90분에 해당하는 두 번째 버킷에 들어갑니다. 기간 형식 문자열을 사용합니다.
num_lease_metrics_buckets (int: 168) - 임대의 만료 버킷 수입니다. 예를 들어 기본값의 경우 vault.expire.leases.by_expiration 메트릭에 대해 168개의 값 라벨이 보고되며, 각 버킷은 lease_metrics_epsilon 파라미터만큼 시간상 분리됩니다. lease_metrics_epsilon의 기본 1시간 값과 num_lease_metrics_buckets의 기본값의 경우 vault.expire.leases.by_expiration은 현재 시간부터 일주일 후까지 각 시간 내에 만료되는 총 임대 수를 보고합니다.
add_lease_metrics_namespace_labels (bool: false) - 이 값이 true로 설정되면 vault.expire.leases.by_expiration이 만료되는 임대를 시간과 namespace로 구분합니다. 이 파라미터는 활성화하면 대규모 카디널리티 메트릭이 될 수 있으므로 기본적으로 비활성화되어 있습니다.
add_mount_point_rollback_metrics (bool: false) - 이 값이 true로 설정되면 모든 마운트 지점에 대해 vault.rollback.attempt.{MOUNT_POINT} 및 vault.route.rollback.{MOUNT_POINT} 메트릭이 보고됩니다. 이 파라미터가 false이면 메트릭 이름에 마운트 지점이 없는 vault.rollback.attempt 및 vault.route.rollback 메트릭이 대신 보고됩니다. 이 파라미터는 이러한 메트릭의 높은 카디널리티 때문에 Vault 1.15부터 기본적으로 비활성화되어 있습니다.
filter_default (bool: true) - 필터로 지정되지 않은 메트릭을 허용할지 여부를 제어합니다. 기본값은 true이며, 필터가 제공되지 않을 때 모든 메트릭을 허용합니다. 필터가 없는 상태에서 false로 설정하면 어떤 메트릭도 전송되지 않습니다.
prefix_filter (string array: []) - 접두사로 메트릭을 허용/차단하기 위한 필터 규칙 목록으로, 다음 형식입니다:
```
["+vault.token", "-vault.expire", "+vault.expire.num_leases"]
```
선행 "+"는 주어진 접두사의 모든 메트릭을 활성화하고, 선행 "-"는 차단합니다. 두 규칙이 겹치면 더 구체적인 규칙이 우선합니다. 같은 접두사가 여러 번 나열되면 차단이 우선합니다.

`statsite`

이 telemetry 파라미터는 statsite에 적용됩니다.

statsite_address (string: "") - 메트릭 데이터를 전달할 statsite 서버의 주소를 지정합니다.

telemetry {
  statsite_address = "statsite.company.local:8125"
}

`statsd`

이 telemetry 파라미터는 statsd에 적용됩니다.

statsd_address (string: "") - 메트릭을 전달할 statsd 서버의 주소를 지정합니다.

telemetry {
  statsd_address = "statsd.company.local:8125"
}

`circonus`

이 telemetry 파라미터는 Circonus에 적용됩니다.

circonus_api_token (string: "") - check를 생성/관리하는 데 사용되는 유효한 Circonus API 토큰을 지정합니다. 제공되면 메트릭 관리를 활성화합니다.
circonus_api_app (string: "nomad") - API 토큰과 연결된 유효한 앱 이름을 지정합니다.
circonus_api_url (string: "https://api.circonus.com/v2") - Circonus API에 접촉하는 데 사용할 기본 URL을 지정합니다.
circonus_submission_interval (string: "10s") - 메트릭이 Circonus에 제출되는 간격을 지정합니다.
circonus_submission_url (string: "") - 이전에 생성된 HTTPTRAP check에서 Check API 객체의 check.config.submission_url 필드를 지정합니다.
circonus_check_id (string: "") - 이전에 생성된 HTTPTRAP check에서 Check ID(check bundle 아님)를 지정합니다. Check API 객체에서 check._cid 필드의 숫자 부분입니다.
circonus_check_force_metric_activation (bool: false) - 이미 존재하지만 현재 활성화되지 않은 메트릭의 강제 활성화 여부를 지정합니다. check 관리를 활성화하면 기본 동작은 만나는 새 메트릭을 추가하는 것입니다. 메트릭이 이미 check에 존재하면 활성화되지 않습니다. 이 설정은 그 동작을 재정의합니다.
circonus_check_instance_id (string: "<hostname>:<application>") - 이 인스턴스에서 오는 메트릭을 고유하게 식별하는 역할을 합니다. 인프라 내에서 이동하는 임시(transient/ephemeral) 인스턴스의 메트릭 연속성을 유지하는 데 사용할 수 있습니다. 기본적으로 hostname:application name(예: "host123:nomad")으로 설정됩니다.
circonus_check_search_tag (string: <service>:<application>) - Submission URL이나 Check ID가 제공되지 않을 때 인스턴스 ID와 결합해 검색 결과를 좁히는 데 도움이 되는 특수 태그를 지정합니다. 기본적으로 service:app(예: "service:nomad")으로 설정됩니다.
circonus_check_display_name (string: "") - check가 생성될 때 지정할 이름을 지정합니다. 이 이름은 Circonus UI Checks 목록에 표시됩니다.
circonus_broker_id (string: "") - 새 check를 만들 때 사용할 특정 Circonus Broker의 ID를 지정합니다. Broker API 객체에서 broker._cid 필드의 숫자 부분입니다. 메트릭 관리가 활성화되고 Submission URL이나 Check ID가 제공되지 않으면 Instance ID와 Search Tag를 사용해 기존 check를 검색하려 시도합니다. 찾지 못하면 새 HTTPTRAP check가 생성됩니다. 기본적으로 무작위 Enterprise Broker 또는 기본 Circonus Public Broker가 선택됩니다.
circonus_broker_select_tag (string: "") - Broker ID가 제공되지 않을 때 Circonus Broker를 선택하는 데 사용할 특수 태그를 지정합니다. 가장 좋은 사용은 이 특정 인스턴스가 실행 중인 위치(예: 특정 지리적 위치나 데이터 센터, dc:sfo)에 기반해 어떤 broker를 사용할지에 대한 힌트로 사용하는 것입니다.

`dogstatsd`

이 telemetry 파라미터는 DogStatsD에 적용됩니다.

dogstatsd_addr (string: "") - DogStatsD 인스턴스의 주소를 제공합니다. DogStatsD는 프로토콜 호환 statsd의 변형으로, 메트릭에 태그와 이벤트 정보를 붙일 수 있는 추가 기능이 있습니다. 제공되면 Vault는 다양한 텔레메트리 정보를 집계를 위해 그 인스턴스로 보냅니다. 런타임 정보를 캡처하는 데 사용할 수 있습니다.
dogstatsd_tags (string array: []) - DogStatsD로 전송되는 모든 텔레메트리 패킷에 추가될 전역 태그 목록을 제공합니다. 각 문자열이 "my_tag_name:my_tag_value"처럼 보이는 문자열 목록입니다.

`prometheus`

이 telemetry 파라미터는 prometheus에 적용됩니다.

prometheus_retention_time (string: "24h") - Prometheus 메트릭이 메모리에 보존되는 시간을 지정합니다. 0으로 설정하면 Prometheus 텔레메트리를 비활성화합니다.
disable_hostname (bool: false) - 호스트 이름이 붙은 메트릭을 피하려면 disable_hostname 옵션도 활성화하는 것을 권장합니다.

/v1/sys/metrics 엔드포인트는 active 노드에서만 접근 가능하며 standby 노드에서는 자동으로 비활성화됩니다. 인증되지 않은 메트릭 접근을 활성화하면 standby 노드에서 /v1/sys/metrics 엔드포인트를 활성화할 수 있습니다. Standby 노드는 /v1/sys/metrics 요청을 leader 노드로 절대 포워딩하지 않습니다. 인증되지 않은 메트릭 접근이 활성화되면 standby 노드는 자체 메트릭으로 응답합니다. 인증되지 않은 메트릭 접근이 비활성화되면:

Vault Enterprise standby 노드는 요청을 처리하려 시도합니다.
Vault Community는 요청을 leader 노드로 리다이렉트합니다.

다음 헤더 중 하나로 /v1/sys/metrics를 조회하면:

Accept: prometheus/telemetry
Accept: application/openmetrics-text

Prometheus 형식 결과가 반환됩니다. 대부분의 Prometheus 서버는 기본적으로 이러한 헤더로 스크레이프 대상을 자동 조회합니다.

/v1/sys/metrics에는 capabilities = ["read", "list"]를 가진 Vault 토큰이 필요합니다. 스크레이프 작업에 Prometheus bearer_token 또는 bearer_token_file 옵션을 추가해야 합니다.

Vault는 기본 Prometheus 경로를 사용하지 않으므로 Prometheus가 기본 스크레이프 경로 대신 v1/sys/metrics를 스크레이프하도록 구성해야 합니다.

Prometheus 구성에 필요한 job_name 스탠자의 예시는 아래와 같습니다:

# prometheus.yml
scrape_configs:
  - job_name: 'vault'
    metrics_path: "/v1/sys/metrics"
    scheme: https
    tls_config:
      ca_file: your_ca_here.pem
    bearer_token: "your_vault_token_here"
    static_configs:
    - targets: ['your_vault_server_here:8200']

Vault 구성 파일에 추가할 텔레메트리 구성의 예시는 아래와 같습니다:

telemetry {
  prometheus_retention_time = "30s"
  disable_hostname = true
}

`stackdriver`

이 telemetry 파라미터는 Stackdriver Monitoring에 적용됩니다.

Stackdriver 텔레메트리 공급자는 공식 Google Cloud Golang SDK를 사용합니다. 즉 Google Cloud에 자격 증명을 제공하는 일반적인 방법을 지원합니다.

이 텔레메트리 공급자를 사용하려면 서비스 계정에 다음 최소 scope가 있어야 합니다:

https://www.googleapis.com/auth/cloud-platform
https://www.googleapis.com/auth/monitoring
https://www.googleapis.com/auth/monitoring.write

그리고 다음 IAM 역할:

roles/monitoring.metricWriter

stackdriver_project_id (string: "") - 텔레메트리 데이터를 보낼 Google Cloud 프로젝트 ID입니다.
stackdriver_location (string: "") - 모니터링되는 리소스의 GCP 또는 AWS 리전입니다.
stackdriver_namespace (string: "") - 텔레메트리 데이터의 namespace 식별자입니다.
stackdriver_debug_logs (bool: "false") - Vault가 표준 오류 출력(stderr)에 추가 stackdriver 관련 디버그 로그를 작성하는지 여부를 지정합니다.

disable_hostname 옵션도 활성화해 호스트 이름이 붙은 메트릭을 피하고 대신 enable_hostname_label을 활성화하는 것을 권장합니다.

telemetry {
  stackdriver_project_id = "my-test-project"
  stackdriver_location = "us-east1-a"
  stackdriver_namespace = "vault-cluster-a"
  disable_hostname = true
  enable_hostname_label = true
}

Vault의 메트릭은 Metrics Explorer에서 찾을 수 있습니다. 모든 메트릭은 generic_task의 리소스 유형으로 표시되며, 메트릭 이름은 custom.googleapis.com/go-metrics/로 접두사가 붙습니다.

더 알아보기

Vault 구성 파라미터

telemetry 스탠자