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

# SigNoz

> 서비스 지연 시간 조사, 로그 검색, 알림 규칙 감사, 분산 트레이스 상세 분석을 위해 SigNoz를 CloudThinker에 연결합니다

SigNoz 인스턴스를 연결하면 CloudThinker 에이전트가 서비스 지연 시간을 조사하고, 로그를 검색 및 집계하고, 알림 규칙을 감사하고, 스택 전반의 분산 트레이스를 상세 분석할 수 있습니다.

SigNoz는 역할에 스코프가 지정된 **서비스 계정 API 키**로 인증합니다(읽기 전용 접근의 경우 `signoz-viewer`, 쓰기 접근의 경우 `signoz-admin`).

***

## 지원 플랫폼

| 플랫폼                 | 지원         |
| ------------------- | ---------- |
| **SigNoz Cloud**    | 모든 테넌트     |
| **SigNoz (셀프 호스팅)** | 자체 관리 인스턴스 |

SigNoz Cloud와 셀프 호스팅은 동일한 인터페이스를 공유하므로 아래 설정 단계는 두 플랫폼 모두 동일합니다.

***

## 사전 요구 사항

* **SigNoz Cloud 또는 셀프 호스팅 인스턴스**.
* API 키를 발급할 **서비스 계정** (읽기 전용 접근의 경우 `signoz-viewer`, CloudThinker가 변경을 수행해야 하는 경우 `signoz-admin`).
* **SigNoz 기본 URL**.

***

## 설정

<Steps>
  <Step title="서비스 계정 생성">
    SigNoz에서 **Settings → Workspace Settings → Service Accounts**를 열고 **New Service Account**를 클릭합니다. 이름(예: `cloudthinker-svc`)을 입력하고 **Create Service Account**를 클릭합니다.
  </Step>

  <Step title="역할 할당">
    **Overview** 탭에서 **Roles** 드롭다운을 사용하여 읽기 전용 접근의 경우 `signoz-viewer`를, CloudThinker가 변경을 수행해야 하는 경우 `signoz-admin`을 선택합니다. **Save Changes**를 클릭하여 역할이 적용되도록 합니다.
  </Step>

  <Step title="API 키 생성">
    **Keys** 탭으로 전환하고 **Add Key**를 클릭합니다. 키 이름(예: `cloudthinker-key`)을 입력하고 선택적으로 만료 날짜를 설정한 후 **Create Key**를 클릭하여 키를 복사합니다.
  </Step>

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

    * **SigNoz URL**: 인스턴스 기본 URL (예: `https://<hash>.signoz.cloud`) — 기본 URL만 입력하세요. 경로가 포함된 경우 404가 반환됩니다.
    * **API Key**: 복사한 키
    * **Log Level** (선택 사항): 디버깅이 아닌 경우 `info`로 유지

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

***

## 연결 세부 정보

| 필드                   | 설명                                                | 예시                            |
| -------------------- | ------------------------------------------------- | ----------------------------- |
| **SIGNOZ\_URL**      | 경로 접미사 없는 인스턴스 기본 URL                             | `https://<hash>.signoz.cloud` |
| **SIGNOZ\_API\_KEY** | 서비스 계정 키                                          | Keys 탭에서 복사                   |
| **LOG\_LEVEL**       | MCP 서버 로그 상세 수준: `debug`, `info`, `warn`, `error` | `info`                        |

***

## 필수 권한

* \*\*`signoz-viewer`\*\*는 읽기 전용 접근을 부여합니다: 서비스, 로그, 트레이스, 메트릭 쿼리, 알림, 대시보드, 뷰 검사.
* \*\*`signoz-admin`\*\*은 추가로 쓰기 접근을 부여합니다: 알림, 대시보드, 뷰, 채널 생성, 업데이트, 삭제.
* 쓰기 작업은 CloudThinker에서 실행 전 명시적인 [승인](/ko/guide/approval)도 필요합니다.

<Tip>
  읽기 전용 조사의 경우 `signoz-viewer`로 시작하세요. 에이전트가 알림이나 대시보드를 관리해야 할 때만 `signoz-admin`을 할당하세요.
</Tip>

***

## 에이전트 기능

연결 후 에이전트는 옵저버빌리티 데이터 전반에 읽기 작업을 수행하고, 승인이 필요한 쓰기 작업 세트를 사용할 수 있습니다.

| 기능            | 에이전트가 할 수 있는 작업                                        |
| ------------- | ------------------------------------------------------ |
| **서비스 (APM)** | 계측된 서비스 목록 조회, 지연 시간 상위 작업 검사                          |
| **로그**        | 시간 및 필터로 로그 검색, 패턴별 집계 및 그룹화                           |
| **트레이스**      | 트레이스 검색, 전체 트레이스 워터폴 가져오기, 의존성 상세 분석                   |
| **메트릭**       | 메트릭 목록 조회 및 시계열 쿼리 실행                                  |
| **대시보드**      | 대시보드 및 템플릿 목록 조회 및 검사                                  |
| **알림**        | 알림 규칙 목록 조회, 규칙 및 상태 전환 내역 검사; 생성, 업데이트, 삭제 (admin 전용) |
| **저장된 뷰**     | 저장된 쿼리 뷰 목록 조회, 검사, 생성, 업데이트, 삭제 (admin 전용)            |
| **알림 채널**     | 채널 목록 조회, 검사, 생성, 업데이트, 삭제 (admin 전용)                  |
| **문서**        | SigNoz 문서 검색 및 가져오기                                    |

<Warning>
  쓰기 작업은 라이브 알림과 대시보드를 변경합니다. CloudThinker는 쓰기를 실행하기 전에 리소스를 명시한 명시적인 [승인](/ko/guide/approval)을 요구합니다. 삭제는 되돌릴 수 없습니다.
</Warning>

### 연결 확인

```text theme={null}
@tony list SigNoz services and confirm that metrics and traces are reachable
```

### 예시 프롬프트

```text theme={null}
@tony find the slowest operations for the checkout service
@tony search error logs and group spikes by service
@tony audit SigNoz alert rules and flag misconfigured thresholds
```

***

## 문제 해결

<Accordion title="401 Unauthorized로 연결 실패">
  API 키가 올바른지, 취소되지 않았는지 확인하세요. 역할 할당 후 **Save Changes**를 클릭했는지 확인한 후 키를 다시 발급하세요.
</Accordion>

<Accordion title="모든 요청이 404 반환">
  `SIGNOZ_URL`에 추가 경로 접미사가 있습니다. `/api/v1` 없이 `https://<hash>.signoz.cloud`와 같이 기본 URL만 설정하세요.
</Accordion>

<Accordion title="403 Forbidden">
  서비스 계정의 역할이 해당 작업에 충분하지 않습니다. 쓰기 작업의 경우 `signoz-admin`을 할당한 후 **Save Changes**를 클릭하세요.
</Accordion>

<Accordion title="검색 결과 없음">
  로그, 트레이스, 메트릭 검색에는 시간 범위가 필요합니다. 에이전트에게 최근 범위(예: 최근 15분)를 사용하도록 요청하고 필요한 경우에만 범위를 넓히세요.
</Accordion>

***

## 보안

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

- **기본 URL만 사용** — `SIGNOZ_URL`을 경로 접미사 없는 루트 URL로 설정하세요. 후행 경로가 있으면 모든 요청이 404를 반환합니다.
- **쓰기에 승인 필요** — 알림 및 대시보드 변경이 의도적으로 이루어지도록 쓰기 작업을 승인 필요 상태로 유지하세요.

***

## 관련 항목

<CardGroup cols={2}>
  <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>

  <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>
</CardGroup>