Teleport는 정상 상태를 확인하고 트래픽을 처리할 준비가 되었는지 검증하기 위한 헬스 체크 메커니즘을 제공합니다. 메트릭, 추적, 프로파일링은 클러스터 성능과 응답성을 추적하는 심층 데이터를 제공합니다.

헬스 모니터링 활성화#

Teleport 인스턴스의 상태를 모니터링하는 방법입니다.

Teleport의 진단 HTTP 엔드포인트는 기본적으로 비활성화되어 있습니다. 다음을 통해 활성화할 수 있습니다:

Command line

진단 엔드포인트가 수신 대기할 로컬 주소로 `--diag-addr` 플래그를 설정하여
`teleport` 인스턴스를 시작합니다:

```code
$ sudo teleport start  --diag-addr=127.0.0.1:3000
```

Config file

`teleport` 인스턴스의 구성 파일(기본값 `/etc/teleport.yaml`)을 편집하여
다음을 포함시킵니다:

```yaml
teleport:
    diag_addr: 127.0.0.1:3000
```

디버그 로그를 활성화하려면:

```yaml
log:
    severity: DEBUG
```

이제 Teleport가 진단 엔드포인트를 제공하고 있는지 확인합니다:

```code
$ curl http://127.0.0.1:3000/healthz
```

이제 여러 엔드포인트에서 모니터링 정보를 수집할 수 있습니다. Kubernetes 프로브 등에서 Teleport 프로세스의 상태를 모니터링하는 데 사용할 수 있습니다.

/healthz#

http://127.0.0.1:3000/healthz 엔드포인트는 프로세스가 실행 중이면 {"status":"ok"} 본문과 HTTP 200 OK 상태 코드로 응답합니다.

이는 Teleport 프로세스가 아직 실행 중인지 확인하는 데 적합한 간단한 체크입니다.

/readyz#

http://127.0.0.1:3000/readyz 엔드포인트는 /healthz와 유사하지만, 응답에 프로세스의 상태 정보가 포함됩니다.

응답 본문은 다음 형식의 JSON 객체입니다:

{ "status": "a status message here"}

/readyz와 하트비트#

Teleport 구성 요소가 하트비트 절차를 실행하지 못하면 저하 상태에 진입합니다. 하트비트가 성공적으로 완료되면 Teleport는 이 상태에서 회복을 시작합니다.

첫 번째 성공적인 하트비트는 Teleport를 회복 상태로 전환합니다. 두 번째 연속 성공적인 하트비트는 Teleport를 OK 상태로 전환합니다.

Teleport 하트비트는 정상 상태일 때 약 60초마다 실행되며, 실패한 하트비트는 약 5초마다 재시도됩니다. 이는 하트비트 타이밍에 따라 연결이 복구된 후 /readyz가 다시 정상 상태를 보고하기까지 60-70초가 걸릴 수 있음을 의미합니다.

상태 코드#

응답의 상태 코드는 다음 중 하나일 수 있습니다:

• HTTP 200 OK: Teleport가 정상적으로 작동 중입니다
• HTTP 503 Service Unavailable: Teleport에 연결 오류가 발생하여 저하 상태로 실행 중입니다. Teleport 하트비트가 실패할 때 발생합니다.
• HTTP 400 Bad Request: Teleport가 초기 시작 단계에 진입 중이거나 저하 상태에서 회복을 시작했습니다.

동일한 상태 정보는 /metrics 엔드포인트 아래의 process_state 메트릭을 통해서도 확인할 수 있습니다.

메트릭#

Teleport는 모든 구성 요소에 대한 메트릭을 노출하여 클러스터 상태에 대한 인사이트를 제공합니다. 이 가이드는 Teleport 클러스터에서 수집할 수 있는 메트릭을 설명합니다.

메트릭 활성화#

Teleport의 진단 HTTP 엔드포인트는 기본적으로 비활성화되어 있습니다. 다음을 통해 활성화할 수 있습니다:

Command line

진단 엔드포인트가 수신 대기할 로컬 주소로 `--diag-addr` 플래그를 설정하여
`teleport` 인스턴스를 시작합니다:

```code
$ sudo teleport start  --diag-addr=127.0.0.1:3000
```

Config file

`teleport` 인스턴스의 구성 파일(기본값 `/etc/teleport.yaml`)을 편집하여
다음을 포함시킵니다:

```yaml
teleport:
    diag_addr: 127.0.0.1:3000
```

디버그 로그를 활성화하려면:

```yaml
log:
    severity: DEBUG
```

이제 Teleport가 진단 엔드포인트를 제공하고 있는지 확인합니다:

```code
$ curl http://127.0.0.1:3000/healthz
```

이렇게 하면 http://127.0.0.1:3000/metrics 엔드포인트가 활성화되어 Teleport가 추적하는 메트릭을 제공합니다. Prometheus 수집기와 호환됩니다.

다음 메트릭을 사용할 수 있습니다:

Teleport Cloud는 Auth 서비스 및 Proxy 서비스에 대한 모니터링 엔드포인트를 노출하지 않습니다.

Auth Service 및 백엔드#

세션 녹화 요약기#

이 메트릭은 Auth Service에 의해 익스포트됩니다. 모든 메트릭에는 inference_model_name 레이블이 지정되며, 이는 해당 inference_model 리소스의 metadata.name 필드입니다.

일반 메트릭#

이 메트릭은 모든 추론(inference) 제공자에 적용됩니다.

OpenAI 전용 메트릭#

이 메트릭은 OpenAI 호환 프록시를 포함하여 OpenAI 추론 제공자를 사용해 실행된 작업에 적용됩니다.

향상된 세션 녹화 / BPF#

Proxy Service#

Database Service#

Kubernetes 액세스#

다음 표는 Teleport 클러스터에 하나 이상의 Kubernetes 클러스터가 등록된 경우 Teleport Proxy Service에서 사용할 수 있는 모든 메트릭을 나타냅니다.

클라이언트#

다음 표는 서비스가 업스트림 서버에 연결할 때 사용할 수 있는 모든 메트릭을 나타냅니다. proxy의 경우, 레거시 모드로 실행 중이라면 업스트림 서버는 kubernetes_service 또는 Kubernetes Cluster일 수 있습니다.

서버#

다음 표는 수신(incoming) 연결에 대해 사용할 수 있는 모든 메트릭을 나타냅니다.

Teleport SSH Service#

Teleport Kubernetes Service#

다음 표는 서비스가 업스트림 서버에 연결할 때 사용할 수 있는 모든 메트릭을 나타냅니다. kubernetes_service의 경우, 업스트림 서버는 항상 Kubernetes 클러스터입니다.

다음 표는 수신(incoming) 연결에 대해 사용할 수 있는 모든 메트릭을 나타냅니다.

모든 Teleport 인스턴스#

Teleport 상태 점검#

Go 런타임 메트릭#

이 메트릭은 Go 런타임에 의해 노출되며 Teleport에 국한되지 않습니다.

Prometheus#

분산 추적#

Teleport 인스턴스에 대한 분산 추적을 활성화하는 방법입니다.

Teleport는 OpenTelemetry를 활용하여 추적을 생성하고 OpenTelemetry Protocol (OTLP) 호환 내보내기로 내보냅니다. 텔레메트리 백엔드가 OTLP 추적 수신을 지원하지 않는 경우, OpenTelemetry Collector를 활용하여 OTLP에서 텔레메트리 백엔드가 허용하는 형식으로 추적을 프록시할 수 있습니다.

Teleport 구성#

teleport 인스턴스에 대한 추적을 활성화하려면 해당 인스턴스의 구성 파일(/etc/teleport.yaml)에 다음 섹션을 추가합니다. 이러한 구성 필드에 대한 자세한 설명은 구성 참조 페이지를 참조하세요.

tracing_service:
   enabled: true
   exporter_url: grpc://collector.example.com:4317
   sampling_rate_per_million: 1000000

샘플링 속도#

샘플링 속도를 신중하게 선택하는 것이 중요합니다. 100% 속도로 샘플링하면 클러스터 성능에 부정적인 영향을 줄 수 있습니다. Teleport는 들어오는 요청에 포함된 샘플링 속도를 준수합니다. 즉, tracing_service가 활성화되고 샘플링 속도가 0이더라도, Teleport가 샘플링된 스팬이 있는 요청을 수신하면 Teleport는 해당 요청에 대응하여 생성된 모든 스팬을 샘플링하고 내보냅니다.

내보내기 URL#

exporter_url 설정은 Teleport가 스팬을 전송할 위치를 나타냅니다. 지원되는 스킴은 grpc://, http://, https://, file://입니다(스킴이 제공되지 않으면 grpc://가 사용됩니다).

file://을 사용할 때, URL은 Teleport에 쓰기 권한이 있는 디렉터리 경로여야 합니다. 스팬은 제공된 디렉터리 내의 파일에 저장되며, 각 파일에는 줄당 하나의 proto 인코딩된 스팬이 포함됩니다. 파일이 100MB를 초과하면 교체됩니다. 기본 제한을 재정의하려면 exporter_url에 ?limit=<desired_file_size_in_bytes>를 추가합니다(예: file:///var/lib/teleport/traces?limit=100).

기본적으로 내보내기에 대한 연결은 안전하지 않습니다. TLS를 지원하려면 tracing_service 구성에 다음을 추가합니다:

   # 선택 사항: 내보내기 유효성 검사에 사용되는 CA 인증서 경로
  ca_certs:
    - /var/lib/teleport/exporter_ca.pem
  # 선택 사항: 내보내기에 대한 mTLS를 활성화하는 TLS 인증서 경로
  https_keypairs:
    - key_file: /var/lib/teleport/exporter_key.pem
      cert_file: /var/lib/teleport/exporter_cert.pem

teleport.yaml을 업데이트한 후 새 구성을 적용하려면 teleport 인스턴스를 시작합니다.

tsh#

tsh에서 추적을 캡처하려면 명령에 --trace 플래그를 추가합니다. tsh --trace로 생성된 모든 추적은 명령이 실행 중인 클러스터의 Auth 서비스에 정의된 exporter_url로 프록시됩니다.

$ tsh --trace ssh root@myserver
$ tsh --trace ls

Auth 서비스 구성에 정의된 것과 다른 내보내기로 tsh에서 추적을 내보내는 것도 --trace-exporter 플래그를 통해 가능합니다. tracing_service의 exporter_url과 동일한 형식을 따르는 URL을 제공해야 합니다.

$ tsh --trace --trace-exporter=grpc://collector.example.com:4317 ssh root@myserver
$ tsh --trace --trace-exporter=file:///var/lib/teleport/traces ls

프로파일 수집#

Teleport 인스턴스에서 런타임 프로파일링 데이터를 수집하는 방법입니다.

Teleport는 Go의 진단 기능을 활용하여 프로파일링 데이터를 수집하고 내보냅니다. 프로파일은 CPU 급증의 원인, 메모리 누수의 출처 또는 교착 상태의 이유를 식별하는 데 도움이 됩니다.

Debug 서비스 사용#

Teleport Debug 서비스를 사용하면 관리자가 시작 시 pprof 엔드포인트를 활성화하지 않고도 진단 프로파일을 수집할 수 있습니다. 기본적으로 활성화된 서비스는 로컬 전용 접근을 보장하며 동일한 인스턴스 내에서만 사용해야 합니다.

teleport debug profile은 pprof 프로파일 목록을 수집합니다. STDOUT으로 압축된 tarball(.tar.gz)을 출력합니다. tar를 사용하여 압축을 풀거나 결과를 파일로 보내면 됩니다.

기본적으로 goroutine, heap, profile 프로파일을 수집합니다.

수집된 각 프로파일은 tarball 내의 해당 파일을 가집니다. 예를 들어, goroutine,trace,heap을 수집하면 goroutine.pprof, trace.pprof, heap.pprof 파일이 생성됩니다.

# 기본 프로파일을 수집하여 파일에 저장합니다.
$ teleport debug profile > pprof.tar.gz
$ tar xvf pprof.tar.gz

# 기본 프로파일을 수집하고 압축을 풉니다.
$ teleport debug profile | tar xzv -C ./

# "trace" 및 "mutex" 프로파일을 수집하여 파일에 저장합니다.
$ teleport debug profile trace,mutex > pprof.tar.gz

# 프로파일링 시간을 초 단위로 설정하여 프로파일을 수집합니다
$ teleport debug profile -s 20 trace > pprof.tar.gz

Kubernetes 클러스터에서 Teleport를 실행 중인 경우 인터랙티브 세션 없이 로컬 디렉터리로 직접 프로파일을 수집할 수 있습니다:

$ kubectl -n teleport exec my-pod -- teleport debug profile > pprof.tar.gz

내용을 추출한 후 go tool 명령을 사용하여 탐색하고 시각화할 수 있습니다:

# 터미널 인터랙티브 탐색기를 엽니다
$ go tool pprof heap.pprof

# 웹 시각화 도구를 엽니다
$ go tool pprof -http : heap.pprof

# 추적 프로파일을 시각화합니다
$ go tool trace trace.pprof

진단 엔드포인트 사용#

프로파일링 엔드포인트는 --debug 플래그가 제공된 경우에만 활성화됩니다.

Teleport의 진단 HTTP 엔드포인트는 기본적으로 비활성화되어 있습니다. 다음을 통해 활성화할 수 있습니다:

Command line

진단 엔드포인트가 수신 대기할 로컬 주소로 `--diag-addr` 플래그를 설정하여
`teleport` 인스턴스를 시작합니다:

```code
$ sudo teleport start --debug --diag-addr=127.0.0.1:3000
```

Config file

`teleport` 인스턴스의 구성 파일(기본값 `/etc/teleport.yaml`)을 편집하여
다음을 포함시킵니다:

```yaml
teleport:
    diag_addr: 127.0.0.1:3000
```

디버그 로그를 활성화하려면:

```yaml
log:
    severity: DEBUG
```

이제 Teleport가 진단 엔드포인트를 제공하고 있는지 확인합니다:

```code
$ curl http://127.0.0.1:3000/healthz
```

프로파일 수집#

Go의 표준 프로파일링 엔드포인트는 http://127.0.0.1:3000/debug/pprof/에서 제공됩니다. 프로파일을 검색하려면 원하는 프로파일 유형에 해당하는 엔드포인트에 요청을 보내야 합니다. 문제를 디버깅할 때 일정 기간 동안 일련의 프로파일을 수집하는 것이 유용합니다.

CPU#

CPU 프로파일은 사용자가 지정한 기간 동안 수집된 실행 통계를 보여줍니다:

# 프로파일을 파일로 다운로드합니다:
$ curl -o cpu.profile http://127.0.0.1:3000/debug/pprof/profile?seconds=30

# 프로파일을 시각화합니다
$ go tool pprof -http : cpu.profile

Goroutine#

Goroutine 프로파일은 시스템에서 실행 중인 모든 goroutine의 스택 추적을 보여줍니다:

# 프로파일을 파일로 다운로드합니다:
$ curl -o goroutine.profile http://127.0.0.1:3000/debug/pprof/goroutine

# 프로파일을 시각화합니다
$ go tool pprof -http : goroutine.profile

Heap#

Heap 프로파일은 시스템에 할당된 객체를 보여줍니다:

# 프로파일을 파일로 다운로드합니다:
$ curl -o heap.profile http://127.0.0.1:3000/debug/pprof/heap

# 프로파일을 시각화합니다
$ go tool pprof  -http : heap.profile

Trace#

Trace 프로파일은 사용자가 지정한 기간 동안 Go 런타임이 수집하는 스케줄링, 시스템 호출, 가비지 컬렉션, 힙 크기 및 기타 이벤트를 캡처합니다:

# 프로파일을 파일로 다운로드합니다:
$ curl -o trace.out http://127.0.0.1:3000/debug/pprof/trace?seconds=5

# 프로파일을 시각화합니다
$ go tool trace trace.out

추가 읽기#

• Go 에코시스템의 진단에 대한 자세한 정보: https://go.dev/doc/diagnostics
• Go의 프로파일링 엔드포인트: https://golang.org/pkg/net/http/pprof/
• Go 프로그램 프로파일링에 대한 심층 가이드: https://go.dev/blog/pprof