> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

export const TrackedLink = ({href, eventName, children, ...rest}) => {
  const handleClick = () => {
    try {
      if (typeof window !== "undefined" && window.galaxy && eventName) {
        window.galaxy.track(eventName, {
          interaction: "click"
        });
      }
    } catch (e) {}
  };
  return <a href={href} onClick={handleClick} {...rest}>
      {children}
    </a>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

<Info>
  **경고**

  Temporal 플랫폼의 OpenMetrics 지원은 현재 [Public Preview](https://docs.temporal.io/evaluate/development-production-features/release-stages#public-preview) 상태로 제공됩니다. 자세한 내용은 [Temporal 문서](https://docs.temporal.io/cloud/metrics/openmetrics)를 참조하십시오.
</Info>

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

<Info>
  **TL;DR**

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

<div id="existing-temporal">
  ## 기존 Temporal Cloud와의 통합
</div>

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

<div id="prerequisites">
  ## 사전 요구 사항
</div>

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

<Steps>
  <Step>
    #### Temporal Cloud 키 생성

    Temporal Cloud API Key가 있는지 확인하십시오. 이 키는 Temporal 문서의 [Authentication guide](https://docs.temporal.io/production-deployment/cloud/metrics/openmetrics/api-reference#authentication)를 따르면 생성할 수 있습니다.

    <Warning>
      **키 파일**

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

  <Step>
    #### 사용자 지정 OTel collector 구성 만들기

    ClickStack에서는 사용자 지정 설정 파일을 마운트하고 환경 변수를 설정해 기본 OpenTelemetry collector 구성을 확장할 수 있습니다. 사용자 지정 구성은 OpAMP를 통해 HyperDX가 관리하는 기본 구성에 머지됩니다.

    다음 구성으로 `temporal-metrics.yaml` 파일을 만드세요:

    ```yaml title="temporal-metrics.yaml" theme={null}
    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초마다 메트릭을 수집합니다
    * [주요 성능 메트릭](https://docs.temporal.io/production-deployment/cloud/metrics/openmetrics/metrics-reference)을 수집합니다
    * [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/resource/#service)에 따라 **필수 `service.name` 리소스 속성을 설정합니다**
    * 전용 파이프라인을 통해 메트릭을 ClickHouse exporter로 전달합니다

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

  <Step>
    #### 사용자 지정 구성을 로드하도록 ClickStack 구성

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

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

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

    ##### 옵션 1: Docker Compose

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

    ```yaml theme={null}
    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 이미지를 사용하는 경우:

    ```bash theme={null}
    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
    ```
  </Step>

  <Step>
    #### HyperDX에서 메트릭 확인

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

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

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/huP88Vza7bEG09HU/images/clickstack/temporal/temporal-metrics.png?fit=max&auto=format&n=huP88Vza7bEG09HU&q=85&s=47ef1e489ad0c142346dfc72d2133022" alt="Temporal 메트릭" size="md" width="1133" height="628" data-path="images/clickstack/temporal/temporal-metrics.png" />
  </Step>
</Steps>

<div id="dashboards">
  ## 대시보드 및 시각화
</div>

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

<Steps>
  <Step>
    #### <TrackedLink href={'/ko/examples/temporal-metrics-dashboard.json'} download="temporal-metrics-dashboard.json" eventName="docs.temporal_metrics_monitoring.dashboard_download">다운로드</TrackedLink>하여 대시보드 구성 파일 받기
  </Step>

  <Step>
    #### 사전 구축된 대시보드 가져오기

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

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/zXCQbzXFHfeD9FBK/images/clickstack/import-dashboard.png?fit=max&auto=format&n=zXCQbzXFHfeD9FBK&q=85&s=eace17d7f86efbec4d3151bbf428941a" alt="대시보드 가져오기 버튼" width="3024" height="556" data-path="images/clickstack/import-dashboard.png" />

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

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/huP88Vza7bEG09HU/images/clickstack/temporal/import-temporal-metrics-dashboard.png?fit=max&auto=format&n=huP88Vza7bEG09HU&q=85&s=88789a20ad998956f25aa91900bb5af3" alt="가져오기 완료 대화상자" width="3600" height="2028" data-path="images/clickstack/temporal/import-temporal-metrics-dashboard.png" />
  </Step>

  <Step>
    #### 대시보드 보기

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

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/huP88Vza7bEG09HU/images/clickstack/temporal/temporal-metrics-dashboard.png?fit=max&auto=format&n=huP88Vza7bEG09HU&q=85&s=cdbd7ffdcd87a1f57178bbb0b7dffa9e" alt="Temporal 메트릭 대시보드" width="3840" height="1933" data-path="images/clickstack/temporal/temporal-metrics-dashboard.png" />
  </Step>
</Steps>

<div id="troubleshooting">
  ## 문제 해결
</div>

<div id="troubleshooting-not-loading">
  ### 사용자 지정 구성이 로드되지 않는 경우
</div>

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

```bash theme={null}
docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE
```

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

```bash theme={null}
docker exec <container-name> ls -lh /etc/otelcol-contrib/custom.config.yaml
# 보통, docker exec clickstack ls -lh /etc/otelcol-contrib/custom.config.yaml
```

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

```bash theme={null}
docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml
# 보통, docker exec clickstack cat /etc/otelcol-contrib/custom.config.yaml
```

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

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

<div id="no-metrics">
  ### HyperDX에 메트릭이 표시되지 않음
</div>

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

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

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

```text theme={null}
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 수신기가 포함되어 있는지 확인하십시오:

```bash theme={null}
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의 로그에서 오류를 확인하세요:

```bash theme={null}
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 로그에서 확인하세요:

```bash theme={null}
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
```

<div id="auth-errors">
  ### 인증 오류
</div>

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

<div id="network-issues">
  ### 네트워크 연결 문제
</div>

ClickStack에서 Temporal Cloud에 연결할 수 없는 경우 Docker Compose 파일 또는 `docker run` 명령에서 [외부 네트워킹](https://docs.docker.com/engine/network/#drivers)이 허용되어 있는지 확인하십시오.

<div id="next-steps">
  ## 다음 단계
</div>

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

<div id="going-to-production">
  ## 프로덕션 환경으로 전환하기
</div>

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