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

# Honeycomb

> OAuth로 Honeycomb을 CloudThinker에 연결해 트레이스 쿼리, BubbleUp 근본 원인 분석, 승인 기반 보드 및 트리거 변경을 수행합니다

Honeycomb 팀을 연결하면 [Alex](/ko/guide/agents/alex)(Cloud Engineer)가 트레이스를 쿼리하고, 실패 중인 엔드포인트의 순위를 매기고, BubbleUp으로 무엇이 바뀌었는지 찾고, 트레이스 워터폴을 따라 실패한 스팬까지 도달할 수 있습니다.

Honeycomb은 Honeycomb이 호스팅하는 MCP 서버를 통해 **OAuth**로 인증하므로, API 키를 만들거나 자격 증명을 CloudThinker에 붙여 넣을 필요가 없습니다.

## 사전 요구 사항

* CloudThinker가 읽을 팀에 접근할 수 있는 **Honeycomb 계정**.
* Honeycomb OAuth 흐름에서 CloudThinker를 승인할 권한.
* **텔레메트리를 수신하는 데이터셋이 있는 environment**가 최소 하나. 모든 쿼리 도구에는 데이터셋이 필요합니다. 데이터셋이 없는 environment는 정상적인 0이 아니라 텔레메트리가 전송되지 않는다는 뜻입니다.

<Info>
  CloudThinker는 Honeycomb의 US 엔드포인트 `https://mcp.honeycomb.io/mcp`에 연결합니다. EU 엔드포인트는 선택할 수 없으므로 EU 전용 팀은 아직 연결할 수 없습니다.
</Info>

## 설정

<Steps>
  <Step title="연결 열기">
    CloudThinker 워크스페이스에서 **Connections → Honeycomb**으로 이동합니다.
  </Step>

  <Step title="OAuth 흐름 시작">
    **Connect**를 클릭합니다. CloudThinker가 Honeycomb 승인 페이지를 엽니다.
  </Step>

  <Step title="CloudThinker 승인">
    사용하려는 팀에 접근할 수 있는 Honeycomb 계정으로 로그인한 뒤 접근을 승인합니다.
  </Step>

  <Step title="CloudThinker로 돌아오기">
    Honeycomb이 원래 화면으로 돌려보내고 CloudThinker가 토큰을 저장합니다. 연결에 **Connected** 상태가 표시됩니다.
  </Step>
</Steps>

## 연결 세부 정보

Honeycomb은 OAuth를 사용하므로 입력할 항목이 없습니다. CloudThinker는 흐름이 끝나면 액세스 토큰과 리프레시 토큰을 저장하고, 다시 묻지 않고 갱신합니다.

| 항목           | 설명                                                      |
| ------------ | ------------------------------------------------------- |
| **OAuth 토큰** | Honeycomb이 발급하며 자동 저장됩니다. 수동 입력이 필요 없습니다                |
| **엔드포인트**    | `https://mcp.honeycomb.io/mcp`, Honeycomb이 호스팅하는 MCP 서버 |

## 필요한 권한

CloudThinker는 승인한 계정이 접근할 수 있는 범위를 그대로 물려받습니다. 승인 시 두 가지 스코프가 부여됩니다.

| 스코프         | 범위                                            |
| ----------- | --------------------------------------------- |
| `mcp:read`  | environment, 데이터셋, 컬럼, 쿼리, 트레이스, 트리거, 보드, 수신자 |
| `mcp:write` | 보드, 트리거, SLO, 마커, 수신자 생성 및 수정                 |

<Tip>
  에이전트가 볼 팀으로 범위가 한정된 계정으로 승인하세요. CloudThinker는 그 계정이 이미 가진 권한보다 더 좁게 줄일 수 없습니다.
</Tip>

## 에이전트 기능

연결하면 Alex는 다음을 할 수 있습니다.

| 기능           | 설명                                                            |
| ------------ | ------------------------------------------------------------- |
| **환경 파악**    | 팀 이름을 확인하고 environment와 데이터셋을 나열하며 트리거, 보드, 수신자의 존재 여부를 보고합니다 |
| **서비스 상태**   | 실패 스팬 수와 오류율로 엔드포인트 순위를 매기고 p95 지연 시간을 함께 제시합니다               |
| **근본 원인 분석** | BubbleUp을 실행해 실패 스팬과 정상 스팬을 가르는 차원을 찾습니다                      |
| **트레이스 조사**  | 스팬을 나열하고 스팬 상세를 열어 트레이스 워터폴을 따라 실패 지점까지 이동합니다                 |
| **알림 검토**    | 트리거, SLO, 보드, 알림 수신자를 읽습니다                                    |
| **승인 기반 변경** | 입력값을 사용자가 승인한 뒤 보드, 트리거, SLO, 마커, 수신자를 생성하거나 수정합니다            |

### 연결 확인

```text theme={null}
@alex #report summarize my Honeycomb setup: team, environments, datasets, and whether triggers exist
```

### 프롬프트 예시

```text theme={null}
@alex which endpoint is in the worst shape right now
@alex why is POST /checkout failing and #report the dimension that changed
@alex show me the trace waterfall for the slowest checkout request
```

## 쓰기 작업은 되돌릴 수 없습니다

Honeycomb의 MCP 서버에는 삭제 도구가 없습니다. 에이전트가 만든 보드, 트리거, SLO, 마커, 수신자는 CloudThinker에서 제거할 수 없으며 Honeycomb에서 삭제해야 합니다.

그래서 모든 쓰기 작업은 두 번 차단됩니다. 에이전트가 영향과 정확한 입력값을 제시하고, 같은 턴에서 사용자가 [승인](/ko/guide/approval)한 뒤에만 변경이 실행됩니다.

<Warning>
  해당 객체를 계속 남겨 두어도 될 때만 생성을 승인하세요. CloudThinker를 통한 되돌리기 경로는 없습니다.
</Warning>

## 문제 해결

<Accordion title="OAuth 흐름이 완료되지 않습니다">
  브라우저가 다른 Honeycomb 계정으로 로그인되어 있을 수 있습니다. 의도한 계정으로 로그인한 뒤 Honeycomb 연결을 다시 시작하세요.
</Accordion>

<Accordion title="모든 호출이 인증 오류로 실패합니다">
  저장된 토큰이 더 이상 유효하지 않습니다. 보통 Honeycomb에서 승인이 취소된 경우입니다. 연결을 삭제하고 다시 연결하세요.
</Accordion>

<Accordion title="에이전트가 데이터셋이 없다고 보고합니다">
  쿼리에는 쿼리 가능한 environment 안의 데이터셋이 필요합니다. 해당 environment가 Honeycomb에서 텔레메트리를 수신하는지 확인하세요. 데이터셋이 없는 environment는 쿼리, BubbleUp, 트레이스 질문에 답할 수 없습니다.
</Accordion>

<Accordion title="에이전트가 특정 environment를 건너뜁니다">
  `$activity-log$`는 Honeycomb 자체 감사용 environment입니다. environment 목록에는 나타나지만 범위가 지정된 모든 호출을 거부하므로 CloudThinker가 의도적으로 건너뜁니다.
</Accordion>

<Accordion title="생성이 거부되었습니다">
  보드, 트리거, SLO, 마커, 수신자 생성에는 같은 턴에서의 승인이 필요합니다. 승인 프롬프트가 열려 있는 동안 응답하세요. 새로운 턴에서는 다시 묻습니다.
</Accordion>

## 보안

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

- **결과 링크를 채팅에 노출하지 않음** — Honeycomb은 쿼리 결과와 트레이스 결과 다운로드 URL에 서명합니다. CloudThinker는 사람이 보는 퍼머링크만 공유하므로, 복사된 메시지가 결과 접근 권한을 가진 토큰을 옮기지 않습니다.
- **팀 전환 시 재연결** — 다른 Honeycomb 계정을 승인하기 전에 기존 연결을 삭제하세요.

## 관련 문서

<CardGroup cols={2}>
  <Card title="Alex 에이전트" icon="cloud" href="/ko/guide/agents/alex">
    클라우드 및 관측성 조사 에이전트
  </Card>

  <Card title="승인" icon="shield-check" href="/ko/guide/approval">
    CloudThinker가 쓰기 작업을 확인 뒤에 두는 방식
  </Card>
</CardGroup>