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

# Langfuse

> LLM 트레이스 조사, 대화 디버깅, 평가 검토, 프롬프트 감사를 위해 Langfuse를 CloudThinker에 연결합니다

Langfuse 프로젝트를 연결하면 CloudThinker 에이전트가 옵저버빌리티 스택 전반에서 LLM 트레이스를 조사하고, 대화를 디버깅하고, 평가 점수 및 데이터셋을 검토하고, 프롬프트 버전을 감사할 수 있습니다. Langfuse는 Langfuse 호스트에 대해 **프로젝트 스코프 API 키 쌍**(공개 키와 비밀 키)으로 인증합니다. 동일한 설정이 Langfuse Cloud 및 셀프 호스팅 인스턴스 모두에서 작동합니다.

## 사전 요구 사항

* 조사할 **Langfuse Cloud 또는 셀프 호스팅 프로젝트**.
* 해당 프로젝트의 **프로젝트 스코프 API 키 쌍** (공개 키와 비밀 키).
* **Langfuse 호스트 URL** (EU의 경우 `https://cloud.langfuse.com`, US의 경우 `https://us.cloud.langfuse.com`, 또는 셀프 호스팅 도메인).

<Info>
  Langfuse API 키는 단일 프로젝트에 스코프가 지정됩니다. CloudThinker가 접근할 프로젝트에서 키 쌍을 생성하고, 접근을 쉽게 감사하고 취소할 수 있도록 CloudThinker 전용 키 쌍을 사용하세요.
</Info>

## 설정

<Steps>
  <Step title="Langfuse 열기">
    Langfuse에 로그인하고 CloudThinker가 조사할 프로젝트를 선택합니다.
  </Step>

  <Step title="API 키 쌍 생성">
    **Project → Settings → API Keys**로 이동하여 **Create new API keys**를 클릭합니다. Langfuse가 생성하는 키:

    * **Public Key** (`pk-lf-` 접두사)
    * **Secret Key** (`sk-lf-` 접두사)

    비밀 키를 즉시 복사하세요 — 한 번만 표시되며 이후에는 조회할 수 없습니다.
  </Step>

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

    * **Host**: Langfuse 기본 URL (예: `https://cloud.langfuse.com`) — 기본 URL만 입력하세요. 경로 없이
    * **Public Key**: 생성한 `pk-lf-` 키
    * **Secret Key**: 생성한 `sk-lf-` 키

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

<Warning>
  생성 후 비밀 키를 즉시 복사하세요. Langfuse는 한 번만 표시하므로 분실 시 새 키 쌍을 생성해야 합니다.
</Warning>

## 연결 세부 정보

| 필드                        | 설명                                                 | 예시                           |
| ------------------------- | -------------------------------------------------- | ---------------------------- |
| **LANGFUSE\_HOST**        | Langfuse 인스턴스의 기본 URL — EU 클라우드, US 클라우드 또는 셀프 호스팅 | `https://cloud.langfuse.com` |
| **LANGFUSE\_PUBLIC\_KEY** | 프로젝트 스코프 공개 키                                      | `pk-lf-...`                  |
| **LANGFUSE\_SECRET\_KEY** | 프로젝트 스코프 비밀 키                                      | `sk-lf-...`                  |

## 필수 권한

Langfuse API 키는 속한 프로젝트의 접근 권한을 상속합니다. CloudThinker는 트레이스, 관찰, 메트릭, 점수, 데이터셋, 주석 큐, 댓글, 프롬프트 전반의 읽기 및 조사 워크플로에 키 쌍을 사용합니다.

<Tip>
  최소 권한 원칙을 따르세요. 키 쌍의 스코프를 CloudThinker가 조사해야 하는 단일 프로젝트로 제한하고, SDK 또는 다른 통합에서 사용하는 키와 분리하여 독립적으로 교체하거나 취소할 수 있도록 하세요.
</Tip>

## 에이전트 기능

연결 후 에이전트는 Langfuse 프로젝트 전반의 LLM 옵저버빌리티 데이터를 조사할 수 있습니다.

| 기능       | 설명                                       |
| -------- | ---------------------------------------- |
| **트레이스** | 트레이스 검색 및 검사, 오류·지연 시간·모델 사용량 연관         |
| **관찰**   | 트레이스 내 스팬, 생성, 이벤트 상세 분석                 |
| **메트릭**  | 시간 범위에 걸쳐 사용량, 지연 시간, 비용 메트릭 쿼리          |
| **점수**   | 평가 점수 및 품질 신호 검토                         |
| **데이터셋** | 평가 및 테스트에 사용되는 데이터셋 검사                   |
| **주석 큐** | 주석 큐 및 항목 검토                             |
| **댓글**   | 트레이스 및 관찰에 남겨진 댓글 읽기                     |
| **프롬프트** | 프롬프트 감사를 위한 프롬프트 버전, 레이블, 최근 변경 사항 목록 조회 |

<Note>
  CloudThinker 채팅 URL에는 Langfuse `sessionId`에 매핑되는 `conversationId`가 포함됩니다. 에이전트에게 채팅 URL을 분석하도록 요청하면 URL을 웹 페이지로 가져오는 대신 Langfuse를 통해 세션을 확인합니다.
</Note>

### 연결 확인

```text theme={null}
@alex investigate recent Langfuse traces and summarize errors, latency, and model usage
```

### 예시 프롬프트

```text theme={null}
@alex investigate recent failed Langfuse traces for production conversations, correlate errors and latency, and #recommend likely fixes
@alex inspect this CloudThinker chat URL by mapping its conversationId to a Langfuse session and summarize tool calls, model usage, and failures
@alex list active Langfuse prompts, versions, and labels, and #report prompts tied to degraded scores
```

트레이스 및 메트릭 쿼리는 시간 범위가 제한되므로, 결과를 집중적으로 유지하려면 범위(예: "지난 한 시간")를 지정하세요.

## 문제 해결

<Accordion title="401 Unauthorized로 연결 실패">
  공개 키와 비밀 키가 올바른지, 교체되거나 삭제되지 않았는지 확인하세요. 두 키 모두 **동일한** Langfuse 프로젝트에 속하는지, 여분의 공백 없이 복사되었는지 확인하세요.
</Accordion>

<Accordion title="잘못된 호스트 또는 리전">
  데이터는 리전별로 분리되어 있으므로 키 쌍은 생성된 호스트에서만 작동합니다. **LANGFUSE\_HOST**가 로그인하는 URL과 일치하는지 확인하세요 (EU의 경우 `https://cloud.langfuse.com`, US의 경우 `https://us.cloud.langfuse.com`).
</Accordion>

<Accordion title="모든 요청이 404 반환">
  **LANGFUSE\_HOST**에 추가 경로 접미사가 있습니다. 후행 경로 없이 기본 URL만 설정하세요.
</Accordion>

<Accordion title="검색 결과 없음">
  트레이스 및 메트릭 검색에는 시간 범위가 필요합니다. 에이전트에게 최근 범위(예: 지난 한 시간)를 사용하도록 요청하고 필요한 경우에만 범위를 넓히세요. 애플리케이션에서 프로젝트가 활발하게 트레이스를 수신하고 있는지 확인하세요.
</Accordion>

<Accordion title="채팅 URL이 세션으로 분석되지 않음">
  에이전트에게 URL을 직접 가져오는 대신 `conversationId`를 추출하고 Langfuse `sessionId`에 매핑하도록 요청하세요.
</Accordion>

## 보안

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

- **프로젝트 스코프 키 쌍** — CloudThinker가 조사하는 단일 프로젝트에 스코프가 지정된 키 쌍을 사용하세요. CloudThinker 전용 키 쌍을 생성하여 독립적으로 쉽게 감사하고 취소할 수 있도록 하세요.
- **올바른 호스트** — 교차 리전 오류를 방지하기 위해 프로젝트가 있는 리전에 맞게 호스트를 일치시키세요.

## 관련 항목

<CardGroup cols={2}>
  <Card title="SigNoz 연결" icon="https://mintcdn.com/cloudthinker/CGWam0VVP8R5KVLk/images/icons/signoz.svg?fit=max&auto=format&n=CGWam0VVP8R5KVLk&q=85&s=d08abadb07adcc41c8812b59483344e3" href="/ko/guide/connections/signoz" width="24" height="24" data-path="images/icons/signoz.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>