> ## 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.

# Prometheus

> 읽기 전용 PromQL 쿼리, 메트릭 검색, 타겟 상태, 알림 검사를 위해 Prometheus, Thanos, VictoriaMetrics, 또는 Grafana Cloud를 연결하세요

Prometheus 호환 모니터링 백엔드를 연결하여 CloudThinker 에이전트가 PromQL 쿼리를 실행하고, 메트릭과 레이블을 검색하며, 스크레이프 타겟 상태를 검사하고, 활성 알림을 상관 분석할 수 있도록 합니다 — 모두 읽기 전용입니다.

<Info>
  커넥터는 표준 Prometheus HTTP API를 지원하는 모든 백엔드와 작동합니다: 자체 호스팅 **Prometheus**, **Thanos**, **VictoriaMetrics**, **Grafana Cloud**. 인증은 **없음**, **Bearer Token**, **Basic Auth**를 지원합니다.
</Info>

***

## 지원 플랫폼

| 플랫폼                 | 지원                       | 일반적인 인증              |
| ------------------- | ------------------------ | -------------------- |
| **Prometheus**      | 자체 호스팅, 최근 모든 릴리스        | 없음 또는 Bearer         |
| **Thanos**          | 인증 프록시 뒤의 Querier        | 없음, Bearer, 또는 Basic |
| **VictoriaMetrics** | 단일 노드 및 클러스터             | 없음 또는 Basic          |
| **Grafana Cloud**   | Prometheus / Mimir 엔드포인트 | Basic                |

<Note>
  매니지드 Mimir 기반 엔드포인트(Grafana Cloud)에서는 `/api/v1/targets`, `/rules`, `/alerts` 경로가 노출되지 않아 404를 반환합니다. 이는 예상된 동작입니다 — 쿼리 API(즉시 쿼리, 범위 쿼리, 레이블, 메타데이터)는 정상적으로 작동합니다.
</Note>

***

## 사전 요구 사항

* CloudThinker에서 HTTPS로 접근 가능한 **Prometheus 호환 엔드포인트** — 자체 호스팅 Prometheus, Thanos, VictoriaMetrics, 또는 Grafana Cloud.
* 엔드포인트에 인증이 필요한 경우 자격 증명: bearer 토큰(Bearer Token 모드) 또는 사용자 이름과 비밀번호(Basic Auth 모드).
* **Grafana Cloud**의 경우, 숫자 인스턴스 ID와 **metrics:read** 범위가 있는 액세스 정책 토큰.

***

## 인증 모드 선택

엔드포인트 노출 방식에 맞는 모드를 선택하세요:

| 모드               | 사용 시기                                                               | 필드                  |
| ---------------- | ------------------------------------------------------------------- | ------------------- |
| **없음**           | 열려 있거나 네트워크 제한된 엔드포인트 (비공개 네트워크 내 자체 호스팅 Prometheus)                | URL만                |
| **Bearer Token** | `Authorization: Bearer <token>`을 기대하는 프록시 또는 게이트웨이 뒤의 엔드포인트         | URL + 토큰            |
| **Basic Auth**   | Grafana Cloud, 인증 프록시 뒤의 Thanos, 또는 사용자 이름/비밀번호가 있는 VictoriaMetrics | URL + 사용자 이름 + 비밀번호 |

<Tip>
  **Grafana Cloud**의 경우, 사용자 이름은 숫자 인스턴스 ID이고 비밀번호는 metrics read 범위가 있는 액세스 정책 토큰입니다.
</Tip>

***

## 설정

<Steps>
  <Step title="Prometheus URL 확인">
    Prometheus HTTP API의 기본 URL을 확인합니다(예: `https://prometheus.your-domain.com` 또는 Grafana Cloud Prometheus 쿼리 엔드포인트). CloudThinker가 표준 `/api/v1/...` 경로를 자동으로 추가합니다.
  </Step>

  <Step title="자격 증명 준비 (필요한 경우)">
    * **없음** — 준비할 것이 없습니다. 엔드포인트에 인증 없이 접근 가능합니다.
    * **Bearer Token** — 프록시 또는 게이트웨이가 기대하는 bearer 토큰을 준비합니다.
    * **Basic Auth** — 사용자 이름과 비밀번호를 준비합니다 (Grafana Cloud의 경우, 숫자 인스턴스 ID와 액세스 정책 토큰).
  </Step>

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

    * **PROMETHEUS\_URL**: 엔드포인트 (예: `https://prometheus.your-domain.com`)
    * **PROMETHEUS\_AUTH\_TYPE**: **없음**, **Bearer Token**, 또는 **Basic Auth** 선택

    선택에 따라 자격 증명 필드가 표시됩니다:

    * **Bearer Token** → **PROMETHEUS\_TOKEN**
    * **Basic Auth** → **PROMETHEUS\_USERNAME** 및 **PROMETHEUS\_PASSWORD**

    **Connect**를 클릭합니다. CloudThinker가 엔드포인트를 확인하고 **Connected** 상태를 표시합니다.
  </Step>
</Steps>

***

## 연결 세부 정보

| 필드                         | 설명                                                   | 예시                                   |
| -------------------------- | ---------------------------------------------------- | ------------------------------------ |
| **PROMETHEUS\_URL**        | Prometheus HTTP API의 기본 URL                          | `https://prometheus.your-domain.com` |
| **PROMETHEUS\_AUTH\_TYPE** | 인증 모드: `none`, `bearer`, 또는 `basic`                  | `basic`                              |
| **PROMETHEUS\_TOKEN**      | Bearer 토큰 (Bearer Token 모드 전용)                       | `eyJhbGci...`                        |
| **PROMETHEUS\_USERNAME**   | 사용자 이름, 또는 Grafana Cloud의 숫자 인스턴스 ID (Basic Auth 전용) | `1234567`                            |
| **PROMETHEUS\_PASSWORD**   | 비밀번호 또는 액세스 정책 토큰 (Basic Auth 전용)                    | `glc_xxxxx...`                       |

***

## 필요 권한

Prometheus 커넥터는 **읽기 전용**입니다 — 에이전트가 쿼리하고 검사하지만 모니터링 백엔드에 쓰지 않습니다.

* **Grafana Cloud**의 경우, **metrics:read** 범위만 있는 액세스 정책 토큰을 생성합니다.
* 보호된 엔드포인트의 경우, 자격 증명이 쿼리, 레이블, 타겟, 규칙, 알림 API 경로에 접근할 수 있는지 확인합니다.

<Tip>
  Grafana Cloud에서는 액세스 정책 토큰을 `metrics:read` 범위로만 지정하세요 — CloudThinker에 다른 범위는 필요하지 않습니다.
</Tip>

***

## 에이전트 기능

Prometheus 커넥터는 읽기 전용입니다 — 에이전트가 쿼리하고 검사하지만 모니터링 백엔드를 수정하지 않습니다.

| 기능         | 에이전트가 할 수 있는 것                        |
| ---------- | ------------------------------------- |
| **즉시 쿼리**  | 특정 시점에 대한 PromQL 표현식 실행               |
| **범위 쿼리**  | 단계 간격으로 시간 창에 걸친 PromQL 표현식 실행        |
| **메트릭 검색** | 접두사로 필터링하여 사용 가능한 메트릭 이름 목록 조회        |
| **레이블 열거** | 레이블 이름 목록 조회 및 메트릭이 분할된 차원 검사         |
| **타겟 상태**  | 스크레이프 타겟 검사 및 다운되거나 비정상적인 타겟 식별       |
| **알림 검사**  | 활성 알림 목록 조회 및 구성된 알림 규칙 검토            |
| **상태 프로브** | 보편적인 `up` 쿼리를 실행하여 백엔드 및 타겟 접근 가능성 확인 |

### 연결 확인

```text theme={null}
@alex run the Prometheus health probe and confirm all scrape targets are reachable
```

### 예시 프롬프트

```text theme={null}
@alex query node_cpu utilization across the cluster for the last hour and #report anything sustained above 85%
@kai list scrape targets that are currently down and #report which jobs they belong to
@alex show all active alerts and #recommend which to investigate first
```

<Note>
  Prometheus는 레이블 **값** 조회 도구를 제공하지 않습니다 — 레이블 열거는 레이블 **이름**만 반환합니다. 에이전트가 정확한 PromQL 셀렉터를 구성할 수 있도록 관심 있는 메트릭과 레이블을 명시하세요.
</Note>

***

## 문제 해결

<Accordion title="401 Unauthorized로 연결 또는 쿼리 실패">
  * **PROMETHEUS\_AUTH\_TYPE**이 엔드포인트가 기대하는 것과 일치하는지 확인합니다.
  * **Bearer**의 경우, 토큰이 최신이고 취소되지 않았는지 확인합니다.
  * **Basic**의 경우, 사용자 이름/비밀번호를 확인합니다 — Grafana Cloud에서는 사용자 이름이 숫자 인스턴스 ID이고 비밀번호가 액세스 정책 토큰입니다.
</Accordion>

<Accordion title="타겟, 규칙, 또는 알림이 404 반환">
  * 매니지드 Mimir 기반 엔드포인트(Grafana Cloud)에서 예상되는 동작 — 이러한 경로는 노출되지 않습니다.
  * 쿼리 API(즉시, 범위, 레이블, 메타데이터)는 여전히 작동합니다. 타겟/규칙 검사 대신 쿼리를 사용하세요.
</Accordion>

<Accordion title="엔드포인트에 도달하지 못하는 연결 실패">
  * **PROMETHEUS\_URL**이 HTTPS를 통해 CloudThinker에서 접근 가능한지 확인합니다.
  * 자체 호스팅 또는 네트워크 제한 엔드포인트의 경우, CloudThinker에서 네트워크 경로가 있는지 확인합니다.
  * URL에서 후행 `/api/v1`을 제거하세요 — 기본 URL만 입력합니다.
</Accordion>

<Accordion title="쿼리가 빈 결과를 반환함">
  * 레이블로 분할하기 전에 검색 쿼리로 메트릭이 존재하는지 확인합니다.
  * 시간 창을 넓히세요 — 요청한 범위에 시리즈의 샘플이 없을 수 있습니다.
</Accordion>

***

## 보안

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

- **설계상 읽기 전용** — 커넥터는 모니터링 백엔드에 쓰지 않습니다. 쓰기 권한이 필요하지 않습니다.
- **최소 권한 자격 증명** — Grafana Cloud에서는 액세스 정책 토큰을 metrics read 범위로만 지정합니다.

***

## 관련 항목

<CardGroup cols={2}>
  <Card title="Grafana 연결" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/grafana.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=c1329049025cd3c3a0909b400baef7be" href="/ko/guide/connections/grafana" width="24" height="24" data-path="images/icons/grafana.svg">
    대시보드 및 통합 옵저버빌리티
  </Card>

  <Card title="Datadog 연결" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/datadog.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=e8382167f2a1eb1e00971b5f4d703d48" href="/ko/guide/connections/datadog" width="24" height="24" data-path="images/icons/datadog.svg">
    로그 검색, 메트릭, 인프라 모니터링
  </Card>
</CardGroup>