ClickStack 기반 Temporal Cloud 메트릭 모니터링

경고Temporal 플랫폼의 OpenMetrics 지원은 현재 Public Preview 상태로 제공됩니다. 자세한 내용은 Temporal 문서를 참조하십시오.

Temporal은 간단하면서도 정교하고 복원력이 뛰어난 애플리케이션을 구축할 수 있도록 추상화 계층을 제공합니다.

TL;DROTel Prometheus 수신기를 사용해 ClickStack에서 Temporal Cloud 메트릭을 모니터링할 수 있습니다. 사전 구축된 대시보드도 포함되어 있습니다.

기존 Temporal Cloud와의 통합

이 섹션에서는 ClickStack OTel collector에서 Prometheus 수신기를 구성해 ClickStack을 설정하는 방법을 설명합니다.

사전 요구 사항

실행 중인 ClickStack 인스턴스
기존 Temporal Cloud 계정
ClickStack에서 Temporal Cloud에 대한 HTTP 네트워크 액세스

Temporal Cloud 키 생성

Temporal Cloud API Key가 있는지 확인하십시오. 이 키는 Temporal 문서의 Authentication guide를 따르면 생성할 수 있습니다.

키 파일이 자격 증명은 아래에서 생성할 구성 파일과 같은 디렉터리의 temporal.key 파일에 저장하십시오. 이 키는 앞뒤 공백 없이 일반 텍스트로만 저장해야 합니다.

사용자 지정 OTel collector 구성 만들기

ClickStack에서는 사용자 지정 설정 파일을 마운트하고 환경 변수를 설정해 기본 OpenTelemetry collector 구성을 확장할 수 있습니다. 사용자 지정 구성은 OpAMP를 통해 HyperDX가 관리하는 기본 구성에 머지됩니다.다음 구성으로 temporal-metrics.yaml 파일을 만드세요:

temporal-metrics.yaml

receivers:
  prometheus/temporal:
    config:
      scrape_configs:
      - job_name: 'temporal-cloud'
        scrape_interval: 60s
        scrape_timeout: 30s
        honor_timestamps: true
        scheme: https
        authorization:
          type: Bearer
          credentials_file: /etc/otelcol-contrib/temporal.key
        static_configs:
          - targets: ['metrics.temporal.io']
        metrics_path: '/v1/metrics'

processors:
  resource:
    attributes:
      - key: service.name
        value: "temporal"
        action: upsert

service:
  pipelines:
    metrics/temporal:
      receivers: [prometheus/temporal]
      processors:
        - resource
        - memory_limiter
        - batch
      exporters:
        - clickhouse

이 구성은 다음을 수행합니다:

metrics.temporal.io의 Temporal Cloud에 연결합니다
60초마다 메트릭을 수집합니다
주요 성능 메트릭을 수집합니다
OpenTelemetry semantic conventions에 따라 필수 service.name 리소스 속성을 설정합니다
전용 파이프라인을 통해 메트릭을 ClickHouse exporter로 전달합니다

사용자 지정 구성에서는 새 수신기, 프로세서, 파이프라인만 정의합니다
memory_limiter 및 batch 프로세서와 clickhouse exporter는 이미 기본 ClickStack 구성에 정의되어 있으므로 이름으로 참조만 하면 됩니다
resource 프로세서는 OpenTelemetry semantic conventions에 따라 필수 service.name 속성을 설정합니다
Temporal Cloud 계정이 여러 개인 경우 구분할 수 있도록 service.name을 사용자 지정하십시오(예: "temporal-prod", "temporal-dev")

사용자 지정 구성을 로드하도록 ClickStack 구성

기존 ClickStack 배포에서 사용자 지정 collector 구성을 활성화하려면 다음 작업을 수행해야 합니다.

사용자 지정 구성 파일을 /etc/otelcol-contrib/custom.config.yaml에 마운트합니다
환경 변수 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml를 설정합니다
temporal.key 파일을 /etc/otelcol-contrib/temporal.key에 마운트합니다
ClickStack과 Temporal 간에 네트워크 연결이 가능한지 확인합니다

모든 명령은 temporal-metrics.yaml 및 temporal.key가 저장된 sample 디렉터리에서 실행한다고 가정합니다.

옵션 1: Docker Compose

ClickStack 배포 구성을 업데이트합니다:

services:
  clickstack:
    # ... 기존 구성 ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
    volumes:
      - ./temporal-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - ./temporal.key:/etc/otelcol-contrib/temporal.key:ro
      # ... 기타 볼륨 ...

옵션 2: Docker run (all-in-one 이미지)

docker run으로 all-in-one 이미지를 사용하는 경우:

docker run --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/temporal-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/temporal.key:/etc/otelcol-contrib/temporal.key:ro" \
  clickhouse/clickstack-all-in-one:latest

HyperDX에서 메트릭 확인

구성이 완료되면 HyperDX에 로그인하여 메트릭이 정상적으로 수집되는지 확인합니다:

Metrics 탐색기로 이동합니다
temporal로 시작하는 메트릭을 검색합니다(예: temporal_cloud_v1_workflow_success_count, temporal_cloud_v1_poll_timeout_count)
설정한 수집 주기에 따라 메트릭 데이터 포인트가 표시되는지 확인합니다

대시보드 및 시각화

ClickStack로 Temporal Cloud 모니터링을 시작하는 데 도움이 되도록 Temporal 메트릭용 예시 시각화를 제공합니다.

하여 대시보드 구성 파일 받기

사전 구축된 대시보드 가져오기

HyperDX를 열고 Dashboards 섹션으로 이동합니다
오른쪽 상단의 줄임표 메뉴에서 Import Dashboard를 클릭합니다

temporal-metrics-dashboard.json 파일을 업로드한 다음 Finish Import를 클릭합니다

대시보드 보기

모든 시각화가 사전 구성된 상태로 대시보드가 생성됩니다:

문제 해결

사용자 지정 구성이 로드되지 않는 경우

환경 변수 CUSTOM_OTELCOL_CONFIG_FILE이 올바르게 설정되었는지 확인하세요:

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

사용자 정의 구성 파일이 /etc/otelcol-contrib/custom.config.yaml에 마운트되었는지 확인하세요:

docker exec <container-name> ls -lh /etc/otelcol-contrib/custom.config.yaml
# 보통, docker exec clickstack ls -lh /etc/otelcol-contrib/custom.config.yaml

사용자 지정 구성 내용이 정상적으로 읽히는지 확인합니다:

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml
# 보통, docker exec clickstack cat /etc/otelcol-contrib/custom.config.yaml

컨테이너에 temporal.key가 마운트되어 있는지 확인하십시오:

docker exec <container-name> cat /etc/otelcol-contrib/temporal.key
# 일반적으로, docker exec clickstack cat /etc/otelcol-contrib/temporal.key
# temporal.key 내용이 출력되면 정상입니다

HyperDX에 메트릭이 표시되지 않음

collector에서 Temporal Cloud에 접근할 수 있는지 확인하십시오:

# ClickStack 컨테이너에서 실행
docker exec <container-name> curl -H "Authorization: Bearer <API_KEY>" https://metrics.temporal.io/v1/metrics

Prometheus 메트릭이 연속으로 출력되는 것을 확인할 수 있습니다. 예:

temporal_cloud_v1_workflow_success_count{operation="CompletionStats",region="aws-us-east-2",temporal_account="l2c4n",temporal_namespace="clickpipes-aws-prd-apps-us-east-2.l2c4n",temporal_task_queue="clickpipes-svc-dc118d12-b397-4975-a33e-c2888ac12ac4-peer-flow-task-queue",temporal_workflow_type="QRepPartitionWorkflow"} 0.067 1765894320

실제로 적용된 구성에 Prometheus 수신기가 포함되어 있는지 확인하십시오:

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 "Prometheus:"
## 보통은: docker exec clickstack cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 "prometheus:"

collector agent의 로그에서 오류를 확인하세요:

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i Prometheus
# 연결 오류 또는 인증 실패 항목을 확인하세요
# docker exec clickstack cat /etc/otel/supervisor-data/agent.log | grep -i Prometheus

collector 로그에서 확인하세요:

docker exec <container> cat /var/log/otel-collector.log | grep -i error
# 설정 파싱 오류를 확인하세요 - 초기 supervisor.opamp-client 오류는 무시해도 됩니다 
# docker exec clickstack cat /var/log/otel-collector.log | grep -i error

인증 오류

로그에 인증 오류가 나타나면 API Key를 확인하세요.

네트워크 연결 문제

ClickStack에서 Temporal Cloud에 연결할 수 없는 경우 Docker Compose 파일 또는 docker run 명령에서 외부 네트워킹이 허용되어 있는지 확인하십시오.

다음 단계

중요한 메트릭(워크플로 실패율, 작업 백로그 증가, 스케줄 시작까지의 지연 시간)에 대한 알림을 설정합니다
특정 사용 사례(네임스페이스 수준 모니터링, 워크플로 유형별 성능)에 맞는 추가 대시보드를 만듭니다
서로 다른 엔드포인트와 서비스 이름을 사용하도록 수신기 구성을 복제해 여러 Temporal Cloud 계정을 모니터링합니다

프로덕션 환경으로 전환하기

이 가이드는 빠른 설정을 위해 ClickStack에 내장된 OpenTelemetry Collector를 확장해 사용합니다. 프로덕션 환경에 배포할 때는 자체 OTel collector를 실행하고 데이터를 ClickStack의 OTLP 엔드포인트로 보내는 것을 권장합니다. 프로덕션 구성은 OpenTelemetry 데이터 전송을 참조하십시오.

​기존 Temporal Cloud와의 통합

​사전 요구 사항

​Temporal Cloud 키 생성

​사용자 지정 OTel collector 구성 만들기

​사용자 지정 구성을 로드하도록 ClickStack 구성

옵션 1: Docker Compose

옵션 2: Docker run (all-in-one 이미지)

​HyperDX에서 메트릭 확인

​대시보드 및 시각화

​하여 대시보드 구성 파일 받기

​사전 구축된 대시보드 가져오기

​대시보드 보기

​문제 해결

​사용자 지정 구성이 로드되지 않는 경우

​HyperDX에 메트릭이 표시되지 않음

​인증 오류

​네트워크 연결 문제

​다음 단계

​프로덕션 환경으로 전환하기

기존 Temporal Cloud와의 통합

사전 요구 사항

Temporal Cloud 키 생성

사용자 지정 OTel collector 구성 만들기

사용자 지정 구성을 로드하도록 ClickStack 구성

HyperDX에서 메트릭 확인

대시보드 및 시각화

하여 대시보드 구성 파일 받기

사전 구축된 대시보드 가져오기

대시보드 보기

문제 해결

사용자 지정 구성이 로드되지 않는 경우

HyperDX에 메트릭이 표시되지 않음

인증 오류

네트워크 연결 문제

다음 단계

프로덕션 환경으로 전환하기