허니콤 MCP
Honeycomb 관측 데이터와 상호작용하기 위한 모델 컨텍스트 프로토콜 서버입니다. 이 서버를 통해 Claude와 같은 LLM은 여러 환경에서 Honeycomb 데이터 세트를 직접 분석하고 쿼리할 수 있습니다.
요구 사항
- 노드.js 18+
- 전체 권한이 있는 Honeycomb API 키:
- 분석을 위한 쿼리 액세스
- SLO 및 트리거에 대한 읽기 액세스
- 데이터 세트 작업을 위한 환경 수준 액세스
Honeycomb MCP는 사실상 Honeycomb에 대한 완벽한 대체 인터페이스이므로 API에 대한 광범위한 권한이 필요합니다.
허니컴 엔터프라이즈 전용
현재 이 기능은 Honeycomb Enterprise 고객에게만 제공됩니다.
작동 원리
현재 이는 사용자 컴퓨터에서 실행해야 하는 단일 서버 프로세스입니다. 인증되지 않습니다. 모든 정보는 클라이언트와 서버 간에 STDIO를 사용합니다.
설치
지엑스피1
빌드 아티팩트는 /build 폴더로 이동합니다.
구성
이 MCP 서버를 사용하려면 MCP 구성의 환경 변수를 통해 Honeycomb API 키를 제공해야 합니다.
{
"mcpServers": {
"honeycomb": {
"command": "node",
"args": [
"/fully/qualified/path/to/honeycomb-mcp/build/index.mjs"
],
"env": {
"HONEYCOMB_API_KEY": "your_api_key"
}
}
}
}
여러 환경의 경우:
{
"mcpServers": {
"honeycomb": {
"command": "node",
"args": [
"/fully/qualified/path/to/honeycomb-mcp/build/index.mjs"
],
"env": {
"HONEYCOMB_ENV_PROD_API_KEY": "your_prod_api_key",
"HONEYCOMB_ENV_STAGING_API_KEY": "your_staging_api_key"
}
}
}
}
중요: 이러한 환경 변수는 MCP 구성의 env 블록에서 설정 해야 합니다 .
EU 구성
MCP가 기본적으로 비EU 인스턴스를 사용하므로 EU 고객도 HONEYCOMB_API_ENDPOINT 구성을 설정해야 합니다.
# Optional custom API endpoint (defaults to https://api.honeycomb.io)
HONEYCOMB_API_ENDPOINT=https://api.eu1.honeycomb.io/
캐싱 구성
MCP 서버는 성능을 향상시키고 API 사용량을 줄이기 위해 모든 비쿼리 Honeycomb API 호출에 대한 캐싱을 구현합니다. 캐싱은 다음 환경 변수를 사용하여 구성할 수 있습니다.
# Enable/disable caching (default: true)
HONEYCOMB_CACHE_ENABLED=true
# Default TTL in seconds (default: 300)
HONEYCOMB_CACHE_DEFAULT_TTL=300
# Resource-specific TTL values in seconds (defaults shown)
HONEYCOMB_CACHE_DATASET_TTL=900 # 15 minutes
HONEYCOMB_CACHE_COLUMN_TTL=900 # 15 minutes
HONEYCOMB_CACHE_BOARD_TTL=900 # 15 minutes
HONEYCOMB_CACHE_SLO_TTL=900 # 15 minutes
HONEYCOMB_CACHE_TRIGGER_TTL=900 # 15 minutes
HONEYCOMB_CACHE_MARKER_TTL=900 # 15 minutes
HONEYCOMB_CACHE_RECIPIENT_TTL=900 # 15 minutes
HONEYCOMB_CACHE_AUTH_TTL=3600 # 1 hour
# Maximum cache size (items per resource type)
HONEYCOMB_CACHE_MAX_SIZE=1000
클라이언트 호환성
Honeycomb MCP는 다음 클라이언트에서 테스트되었습니다.
다른 클라이언트에서도 효과가 있을 가능성이 높습니다.
특징
- 여러 환경에서 Honeycomb 데이터 세트 쿼리
- 다음을 지원하여 분석 쿼리를 실행합니다.
- 다양한 계산 유형(COUNT, AVG, P95 등)
- 분석 및 필터
- 시간 기반 분석
- SLO 및 상태 모니터링(Enterprise 전용)
- 열과 데이터 패턴 분석
- 트리거 보기 및 분석
- 데이터 세트 메타데이터 및 스키마 정보에 액세스합니다.
- 모든 비쿼리 API 호출에 대해 TTL 기반 캐싱을 사용하여 성능을 최적화했습니다.
자원
다음 형식의 URI를 사용하여 Honeycomb 데이터 세트에 액세스합니다: honeycomb://{environment}/{dataset}
예를 들어:
honeycomb://production/api-requestshoneycomb://staging/backend-services
리소스 응답에는 다음이 포함됩니다.
- 데이터 세트 이름
- 열 정보(이름, 유형, 설명)
- 스키마 세부 정보
도구
list_datasets : 환경의 모든 데이터 세트를 나열합니다.{ "environment": "production" }
get_columns : 데이터 세트의 열 정보를 가져옵니다.{
"environment": "production",
"dataset": "api-requests"
}
run_query : 다양한 옵션을 사용하여 분석 쿼리 실행{
"environment": "production",
"dataset": "api-requests",
"calculations": [
{ "op": "COUNT" },
{ "op": "P95", "column": "duration_ms" }
],
"breakdowns": ["service.name"],
"time_range": 3600
}
analyze_columns : 통계 쿼리를 실행하고 계산된 메트릭을 반환하여 데이터 세트의 특정 열을 분석합니다.list_slos : 데이터세트의 모든 SLO를 나열합니다.{
"environment": "production",
"dataset": "api-requests"
}
get_slo : 자세한 SLO 정보 가져오기{
"environment": "production",
"dataset": "api-requests",
"sloId": "abc123"
}
list_triggers : 데이터 세트의 모든 트리거를 나열합니다.{
"environment": "production",
"dataset": "api-requests"
}
get_trigger : 자세한 트리거 정보를 가져옵니다.{
"environment": "production",
"dataset": "api-requests",
"triggerId": "xyz789"
}
get_trace_link : Honeycomb UI에서 특정 추적에 대한 딥 링크를 생성합니다.get_instrumentation_help : OpenTelemetry 계측 지침을 제공합니다.{
"language": "python",
"filepath": "app/services/payment_processor.py"
}
Claude를 사용한 예제 쿼리
클로드에게 다음과 같은 질문을 해보세요.
- "프로덕션 환경에서는 어떤 데이터 세트를 사용할 수 있나요?"
- "지난 1시간 동안 API 서비스에 대한 P95 지연 시간을 보여주세요"
- "서비스 이름별로 오류율은 어떻게 되나요?"
- "예산을 초과할 위기에 처한 SLO가 있나요?"
- "스테이징 환경에서 모든 활성 트리거 표시"
- "프로덕션 API 데이터 세트에서 어떤 열을 사용할 수 있나요?"
최적화된 도구 응답
모든 도구 응답은 필수 정보를 유지하면서 컨텍스트 창 사용을 줄이도록 최적화되었습니다.
- 데이터세트 목록 : 이름, 슬러그, 설명만 반환합니다.
- 열 가져오기 : 이름, 유형 및 설명에 초점을 맞춘 간소화된 열 정보를 반환합니다.
- 쿼리 실행 :
- 실제 결과와 필요한 메타데이터가 포함되어 있습니다.
- 자동으로 계산된 요약 통계를 추가합니다.
- 히트맵 쿼리에 대한 시리즈 데이터만 포함합니다.
- 자세한 메타데이터, 링크 및 실행 세부 정보를 생략합니다.
- 열 분석 :
- 상위 값, 개수 및 주요 통계를 반환합니다.
- 적절한 경우 숫자형 메트릭을 자동으로 계산합니다.
- SLO 정보 : 주요 상태 지표 및 성과 측정 항목으로 간소화됨
- 트리거 정보 : 트리거 상태, 조건, 알림 대상에 초점을 맞춥니다.
이러한 최적화를 통해 응답은 간결하면서도 완전해지며, LLM은 맥락 제한 내에서 더 많은 데이터를 처리할 수 있습니다.
run_query 에 대한 쿼리 사양
run_query 도구는 포괄적인 쿼리 사양을 지원합니다.
- 계산 : 수행할 연산의 배열
- 지원되는 작업: COUNT, CONCURRENCY, COUNT_DISTINCT, HEATMAP, SUM, AVG, MAX, MIN, P001, P01, P05, P10, P25, P50, P75, P90, P95, P99, P999, RATE_AVG, RATE_SUM, RATE_MAX
- COUNT 및 CONCURRENCY와 같은 일부 작업에는 열이 필요하지 않습니다.
- 예:
{"op": "HEATMAP", "column": "duration_ms"}
- 필터 : 필터 조건 배열
- 지원되는 연산자: =, !=, >, >=, <, <=, starts-with, does-not-start-with, exists, does-not-exist, contains, does-not-contain, in, not-in
- 예:
{"column": "error", "op": "=", "value": true}
- filter_combination : "AND" 또는 "OR"(기본값은 "AND")
- breakdowns : 결과를 그룹화하기 위한 열 배열
- 예:
["service.name", "http.status_code"]
- orders : 결과를 정렬하는 방법을 지정하는 배열
- 분류 또는 계산의 열을 참조해야 합니다.
- HEATMAP 작업은 주문에 사용할 수 없습니다.
- 예:
{"op": "COUNT", "order": "descending"}
- time_range : 상대적인 시간 범위(초)(예: 마지막 시간의 경우 3600)
- start_time 또는 end_time과 결합할 수 있지만 둘 다 결합할 수는 없습니다.
- 시작 시간 및 종료 시간 : 절대 시간 범위에 대한 UNIX 타임스탬프
- 가지고 있음 : 계산 값을 기준으로 결과 필터링
- 예:
{"calculate_op": "COUNT", "op": ">", "value": 100}
예제 쿼리
다음은 실제 쿼리의 몇 가지 예입니다.
느린 API 호출 찾기
{
"environment": "production",
"dataset": "api-requests",
"calculations": [
{"column": "duration_ms", "op": "HEATMAP"},
{"column": "duration_ms", "op": "MAX"}
],
"filters": [
{"column": "trace.parent_id", "op": "does-not-exist"}
],
"breakdowns": ["http.target", "name"],
"orders": [
{"column": "duration_ms", "op": "MAX", "order": "descending"}
]
}
DB 호출 분포(지난주)
{
"environment": "production",
"dataset": "api-requests",
"calculations": [
{"column": "duration_ms", "op": "HEATMAP"}
],
"filters": [
{"column": "db.statement", "op": "exists"}
],
"breakdowns": ["db.statement"],
"time_range": 604800
}
예외 및 호출자별 예외 수
{
"environment": "production",
"dataset": "api-requests",
"calculations": [
{"op": "COUNT"}
],
"filters": [
{"column": "exception.message", "op": "exists"},
{"column": "parent_name", "op": "exists"}
],
"breakdowns": ["exception.message", "parent_name"],
"orders": [
{"op": "COUNT", "order": "descending"}
]
}
개발
pnpm install
pnpm run build
특허
MIT