langfuse-laravel-ailisted

# Langfuse × laravel/ai `laravel/ai` SDK(`Laravel\Ai\`)를 쓰는 Laravel 앱의 LLM/에이전트 호출을 Langfuse로 트레이싱한다. ## 핵심 전제 (먼저 알아야 할 것) - laravel/ai는 **OpenTelemetry를 지원하지 않고**, 공식 PHP Langfuse SDK도 없다. 직접 OTLP/인제스션 클라이언트를 짜기 전에 **`axyr/laravel-langfuse`를 먼저 채택한다** — laravel/ai를 **zero-code 자동계측**하고 Langfuse 인제스션 API로 큐 배칭 전송한다. - 패키지 비교(채택 전 근거): | 패키지 | laravel/ai 자동계측 | 전송 | 주의 | | --- | --- | --- | --- | | `axyr/laravel-langfuse` ✅ | O | Langfuse 네이티브 인제스션 | require가 `illuminate`만 → laravel/ai 버전 **비강제**(충돌 없음) | | `tracefast/laravel-ai-observability` | O | OTLP 경유 | `laravel/ai ^0.7`을 **강제** → 낮은 버전과 충돌 위험 | | `dropsolid/` · `dij-digital/` · `janzaba/` | X (수동 trace API만) | Langfuse | 결국 이벤트 후킹은 직접 해야 함 | ## 설치 & 설정 1. `composer require axyr/laravel-langfuse` - post-install 훅이 `package.json`을 무관하게 건드리면 `git checkout package.json`으로 원복. 2. `php artisan vendor:publish --tag=langfuse-config` 3. `.env` (env 키가 표준이라 기존 `LANGFUSE_*` 값을 그대로 재사용): ```env LANGFUSE_PUBLIC_KEY=pk-lf-... LANGFUSE_SECRET_KEY=sk-lf-... LANGFUSE_BASE_URL=https://cloud.langfuse.com # self-hosted면 그 URL LANGFUSE_LARAVEL_AI_ENABLED=true # ← 자동계측 ON (필수) LANGFUSE_QUEUE=default # 큐 worker로 비동기 전송 ``` 4. 등록 확인: `php artisan config:clear && php artisan event:list | grep LaravelAiSubscriber` → laravel/ai 6개 이벤트에 붙어야 정상. ## 자동계측이 잡는 것 `Axyr\Langfuse\LaravelAi\LaravelAiSubscriber`가 후킹한다: | laravel/ai 이벤트 | Langfuse 관측치 | | --- | --- | | `PromptingA