OpenTelemetry
Copilot CLI에는 OpenTelemetry에 의한 트레이스 기능이 내장되어 있습니다. SDK 측에서 설정하기만 하면 CLI 프로세스의 트레이스 데이터를 수집할 수 있습니다.기본 사용법
CLI 프로세스의 트레이스 활성화
config/copilot.php에 telemetry 설정을 추가하거나 직접 옵션으로 지정합니다.
TelemetryConfig 옵션
| 옵션 | 설명 |
|---|---|
otlpEndpoint | OTLP HTTP 엔드포인트 URL |
filePath | JSON-lines 트레이스 출력 파일 경로 |
exporterType | "otlp-http" 또는 "file" |
sourceName | 인스트루먼테이션 스코프 이름 |
captureContent | 메시지 내용(프롬프트, 응답)을 캡처할지 |
W3C Trace Context 프로파게이션
대부분의 사용자에게는 이 기능이 필요 없습니다. 위의
TelemetryConfig만으로 CLI의 트레이스를 수집할 수 있습니다. 아래는 애플리케이션 측에서 독자적인 OpenTelemetry 스팬을 작성하고, CLI 스팬과 같은 분산 트레이스에 표시하고 싶은 경우의 고급 기능입니다.session.create, session.resume, session.send의 JSON-RPC 요청에 W3C Trace Context(traceparent/tracestate)를 자동으로 주입합니다.
자동 프로파게이션(권장)
open-telemetry/api 패키지를 설치하는 것만으로 트레이스 컨텍스트가 자동으로 전파됩니다.
커스텀 프로바이더
독자적인 트레이스 컨텍스트 취득 로직을 사용하려면:SDK → CLI(아웃바운드)
다음 RPC 호출에 자동으로traceparent/tracestate가 주입됩니다.
session.create— 세션 작성 시session.resume— 세션 재개 시session.send— 메시지 송신 시
CLI → SDK(인바운드)
CLI가 도구를 호출할 때 도구 핸들러의$invocation 배열에 트레이스 컨텍스트가 포함됩니다.
open-telemetry/api가 설치되어 있는 경우, 도구 핸들러 실행 중의 OpenTelemetry 컨텍스트는 CLI 스팬에 자동으로 링크됩니다. 명시적으로 traceparent를 사용할 필요는 없습니다.
의존 관계
| 패키지 | 용도 |
|---|---|
open-telemetry/api | 자동 Trace Context 전파(suggest, 옵션) |
open-telemetry/sdk | 트레이스 데이터의 익스포트 |
open-telemetry/api는 composer.json의 suggest에 포함되어 있습니다. 설치되어 있지 않아도 SDK 자체는 정상 동작합니다.
최신 정보는 GitHub 저장소를 참고하세요.