> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Grafana

> 대시보드 통합, 메트릭 분석, 통합 옵저버빌리티를 위해 Grafana를 CloudThinker에 연결하세요

Grafana 인스턴스를 연결하여 CloudThinker 에이전트가 대시보드에 접근하고, 메트릭을 쿼리하며, 분석 중에 시각화를 참조할 수 있도록 합니다.

Grafana는 Viewer 역할로 범위가 지정된 **서비스 계정 토큰**으로 인증합니다.

***

## 지원 플랫폼

| 플랫폼                    | 지원        |
| ---------------------- | --------- |
| **Grafana OSS**        | 9.x, 10.x |
| **Grafana Enterprise** | 모든 버전     |
| **Grafana Cloud**      | 모든 티어     |

***

## 사전 요구 사항

* CloudThinker에서 접근 가능한 **Grafana 인스턴스** (OSS, Enterprise, 또는 Cloud).
* **Administration → Users and access → Service Accounts**에서 서비스 계정을 생성할 관리자 접근 권한.
* Grafana 인스턴스 URL.

***

## 설정

<Steps>
  <Step title="Grafana 열기">
    Grafana 인스턴스로 이동하여 관리자 권한으로 로그인합니다.
  </Step>

  <Step title="서비스 계정 메뉴로 이동">
    **Administration → Users and access → Service Accounts**로 이동합니다.
  </Step>

  <Step title="서비스 계정 생성">
    **Add service account**를 클릭하고 다음을 입력합니다:

    * **Name**: `cloudthinker-readonly`
    * **Role**: **Viewer** 선택

    **Create**를 클릭하여 서비스 계정을 생성합니다.
  </Step>

  <Step title="토큰 생성">
    새 서비스 계정 페이지에서:

    1. **Add service account token**을 클릭합니다.
    2. 토큰 이름을 입력합니다 (예: `cloudthinker-token`).
    3. 선택적으로 만료 날짜를 설정합니다.
    4. **Generate token**을 클릭합니다.
    5. **즉시 토큰을 복사합니다** — 이후에는 다시 표시되지 않습니다.
  </Step>

  <Step title="CloudThinker에 연결 추가">
    **Connections → Grafana**로 이동하여 다음을 입력합니다:

    * **Grafana URL**: 인스턴스 URL (예: `https://grafana.your-domain.com`)
    * **Service Account Token**: 방금 복사한 토큰

    **Connect**를 클릭합니다. CloudThinker가 자격 증명을 확인하고 **Connected** 상태를 표시합니다.
  </Step>
</Steps>

<Warning>
  생성 직후 서비스 계정 토큰을 복사하세요. Grafana는 이후에 토큰을 다시 표시하지 않으며, 분실 시 새 토큰을 생성해야 합니다.
</Warning>

***

## 연결 세부 정보

| 필드                                   | 설명               | 예시                                  |
| ------------------------------------ | ---------------- | ----------------------------------- |
| **GRAFANA\_URL**                     | Grafana 인스턴스 URL | `https://your-instance.grafana.net` |
| **GRAFANA\_SERVICE\_ACCOUNT\_TOKEN** | 생성된 서비스 계정 토큰    | `glsa_xxxxx...`                     |

***

## 필요 권한

| 역할         | 부여하는 권한                                |
| ---------- | -------------------------------------- |
| **Viewer** | 대시보드 조회, 데이터 소스 쿼리, 어노테이션 조회, 폴더 내용 접근 |
| **Editor** | Viewer 권한에 더해 어노테이션 생성 및 대시보드 스냅샷 저장   |

<Tip>
  읽기 전용 조사에는 **Viewer** 역할을 지정하세요. 어노테이션 생성 또는 대시보드 스냅샷이 필요한 경우에만 Editor를 사용하세요.
</Tip>

***

## 에이전트 기능

연결 후 에이전트는 다음을 수행할 수 있습니다:

| 기능           | 설명                     |
| ------------ | ---------------------- |
| **대시보드 접근**  | 분석 시 기존 대시보드 참조        |
| **메트릭 쿼리**   | Grafana를 통해 데이터 소스 쿼리  |
| **어노테이션 읽기** | 컨텍스트를 위한 대시보드 어노테이션 접근 |
| **알림 상태**    | Grafana 알림 규칙 상태 확인    |

### 연결 확인

```text theme={null}
@alex check Grafana for active alert rules and summarize any that are firing
```

### 예시 프롬프트

```text theme={null}
@alex check the AWS cost dashboard for anomalies
@kai reference the Kubernetes cluster dashboard for pod health
@tony query database metrics from the Grafana data source
```

### 지원되는 데이터 소스

CloudThinker는 Grafana에 구성된 데이터 소스를 통해 쿼리할 수 있습니다:

| 데이터 소스        | 쿼리 지원           |
| ------------- | --------------- |
| Prometheus    | PromQL 쿼리       |
| InfluxDB      | InfluxQL / Flux |
| Elasticsearch | Lucene / KQL    |
| CloudWatch    | CloudWatch 메트릭  |
| Loki          | LogQL 쿼리        |

***

## 문제 해결

<Accordion title="연결 실패">
  * Grafana URL이 CloudThinker에서 접근 가능한지 확인합니다.
  * SSL 인증서가 유효한지 확인합니다.
  * 프록시가 연결을 차단하지 않는지 확인합니다.
  * Grafana가 실행 중이고 접근 가능한지 확인합니다.
</Accordion>

<Accordion title="인증 실패">
  * 서비스 계정 토큰이 올바른지 확인합니다.
  * 토큰이 만료되지 않았는지 확인합니다.
  * 서비스 계정이 활성 상태인지 확인합니다.
  * 계정에 IP 제한이 설정되어 있지 않은지 확인합니다.
</Accordion>

<Accordion title="토큰 만료">
  * **Administration → Service Accounts**로 이동합니다.
  * CloudThinker 서비스 계정을 선택합니다.
  * 새 토큰을 생성합니다.
  * CloudThinker 연결 설정에서 토큰을 업데이트합니다.
</Accordion>

<Accordion title="대시보드에 접근할 수 없음">
  * 서비스 계정에 Viewer 역할이 있는지 확인합니다.
  * 폴더 권한에 서비스 계정이 포함되어 있는지 확인합니다.
  * 대시보드가 제한된 폴더에 있지 않은지 확인합니다.
</Accordion>

***

## 보안

* **최소 권한** — 에이전트가 사용 사례에 필요한 권한만 부여하세요. 읽기 전용으로 시작한 후 필요에 따라 확장하세요.
* **기본 읽기 전용** — 에이전트가 이 연결을 통해 변경 작업을 수행하게 할 것이 아니라면 읽기 전용 자격증명을 사용하세요.
* **자격증명 교체** — 정기 일정에 따라 키와 토큰을 교체하세요. 연결을 업데이트하면 CloudThinker가 새 값을 자동으로 반영합니다.
* **오프보딩 시 취소** — 연결을 삭제하거나 팀원이 퇴사할 때 프로바이더에서 자격증명을 제거하세요.

- **Viewer 역할만 사용** — CloudThinker 서비스 계정에 Editor 또는 Admin 역할을 절대 부여하지 마세요.
- **토큰 만료** — 만료 날짜를 설정하고 90일마다 서비스 계정 토큰을 교체합니다.

***

## 관련 항목

<CardGroup cols={2}>
  <Card title="Elasticsearch 연결" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/elasticsearch.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=c7389cfcd0bc8d303aeeb68bd19199ca" href="/ko/guide/connections/elasticsearch" width="24" height="24" data-path="images/icons/elasticsearch.svg">
    로그 데이터 소스 연결
  </Card>

  <Card title="AWS 연결" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/aws.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=45d526a3e9345214c0345f277da2e829" href="/ko/guide/connections/aws" width="24" height="24" data-path="images/icons/aws.svg">
    CloudWatch 메트릭 연결
  </Card>
</CardGroup>