Python

Sophonz Python SDK는 Python 서버 애플리케이션의 트레이스, 메트릭, 로그를 Sophonz로 보내는 OpenTelemetry 배포판으로, 프레임워크 미들웨어와 예외 캡처를 제공합니다.

제공 기능

• 트레이스, 메트릭, 로그 — OTLP로 전송합니다. 시그널마다 익스포터가 있고 리소스는 공유합니다. 호스팅 엔드포인트 https://in.sophonz.ai는 트레이스와 로그를 받으며, 메트릭은 배포를 참고하세요.
• 브라우저에서 데이터베이스까지 분산 트레이싱 — 들어온 W3C traceparent를 이어받고, baggage 항목(브라우저의 session.id 포함)을 모든 스팬에 복사하며, SQLCommenter로 트레이스를 PostgreSQL까지 전달할 수 있습니다.
• 두 가지 시작 방법 — 코드에서 init()을 호출하거나, 코드 변경 없이 환경 변수와 opentelemetry-instrument로 실행합니다.
• 프레임워크 미들웨어 — Flask, FastAPI, Django 요청의 모든 스팬에 baggage, 클라이언트 IP, user agent, 사용자 속성을 더하고, 에러 핸들러를 제공합니다.
• 예외 캡처 — 라우트에서 빠져나간 예외를 요청 스팬에 기록하고, 처리되지 않은 예외는 프로세스가 끝나기 전에 기록하며, 실패한 스팬마다 에러 로그를 남깁니다.
• 표준 라이브러리 로깅 — logging 레코드를 활성 트레이스와 연결해 내보냅니다.
• 정상 종료 — SIGTERM / SIGINT를 받거나 프로세스가 끝날 때 텔레메트리를 flush합니다.
• 서비스 식별 — API 키를 authorization 헤더와 service.key 리소스 속성으로 전송합니다.

동작 방식

1. 코드에서 — 웹 프레임워크를 import하기 전에 init()을 호출합니다. 설치된 계측은 자동으로 로드됩니다.
2. opentelemetry-instrument로 — 실행 명령 앞에 붙이고 SOPHONZ_* / OTEL_* 환경 변수로 SDK를 설정합니다.

Node.js SDK와 마찬가지로 init()에 명시한 인자가 환경 변수보다 우선합니다.

읽는 순서

먼저 읽을 문서:

1. 설치 — 패키지를 설치하고 텔레메트리 전송을 시작합니다.
2. 설정 — 모든 옵션과 환경 변수.
3. 프레임워크 가이드 — Flask, FastAPI, Django에서 init()을 둘 곳과, gunicorn·uvicorn이 미치는 영향.
4. 미들웨어 — 요청 보강과 에러 핸들러 옵션.

필요할 때 읽을 문서:

• 계측 — 자동 캡처 대상, 로그, 예외, 네트워크 캡처와 마스킹, 사용자 정의 스팬.
• 데이터베이스 트레이싱 — psycopg, psycopg2, SQLAlchemy, Django ORM과 PostgreSQL용 SQLCommenter.
• 브라우저-백엔드 트레이싱 — 브라우저의 트레이스와 세션을 서버에서 이어받기.
• 배포 — 컨테이너, Kubernetes, 시크릿, 정상 종료.

레퍼런스:

• API 레퍼런스 — 모든 공개 함수, 클래스, 헬퍼.
• 예제 — Flask, FastAPI, Django 서버 전체 예제.