CODE_ASSISTANT/5_django_backend/docs-lib/phoenix.md

Phoenix(Arize) — 자체 호스팅 관측 서버 (2026-09-22 정리)

출처: arize.com/docs/phoenix (self-hosting/configuration, tracing/custom-spans), PyPI arize-phoenix 20.15.0.

• pip 패키지 arize-phoenix (Python >=3.10). 실행 python -m phoenix.server.main serve (= phoenix serve). 도커 불필요.
• 포트: 웹+OTLP/HTTP 6006(PHOENIX_PORT), OTLP/gRPC 4317(PHOENIX_GRPC_PORT). 헬스 GET /healthz.
• 트레이스 수신: POST {host}/v1/traces — OTLP/HTTP JSON, 인증 없음(기본). 응답 200.
• 저장: 기본 SQLite(PHOENIX_WORKING_DIR, 기본 ~/.phoenix). PostgreSQL 은 PHOENIX_SQL_DATABASE_URL=postgresql://u:p@host/db + PHOENIX_SQL_DATABASE_SCHEMA.
• 인증: PHOENIX_ENABLE_AUTH=true + PHOENIX_SECRET. 첫 관리자 admin@localhost / PHOENIX_DEFAULT_ADMIN_INITIAL_PASSWORD(기본 admin).
• 폐쇄망: PHOENIX_ALLOW_EXTERNAL_RESOURCES=false(구글 폰트 안 부름), PHOENIX_TELEMETRY_ENABLED=false.

OpenInference 속성 (Phoenix 가 읽는 것)

• 프로젝트: 리소스 속성 openinference.project.name (없으면 default)
• span 종류 openinference.span.kind = LLM | TOOL | CHAIN | AGENT | RETRIEVER …
• 입출력 input.value, input.mime_type(text/plain | application/json), output.value, output.mime_type
• 모델·토큰 llm.model_name, llm.token_count.prompt, llm.token_count.completion, llm.token_count.total
• 세션·사용자 session.id, user.id — 세션 화면은 같은 session.id 의 루트 span 들을 묶음
• 도구 tool.name, 메타 metadata(JSON 문자열), 태그 없음(metadata 로)
• 오류: span status code 2 + message

우리 모듈(apps/gateway/langfuse.py)은 langfuse.* 와 위 속성을 같은 span 에 둘 다 실어서 어느 서버로 보내도 읽힘.