설정

Sophonz Python SDK 설정 레퍼런스 — init()/init_sdk() 옵션, 계측 설정, PostgreSQL용 SQLCommenter, SOPHONZ_* / OTEL_* 환경 변수.

init() vs init_sdk()

from sophonz.opentelemetry import init, init_sdk

• init(**options) — 권장 진입점. Sophonz 기본값(console_capture=True, experimental_exception_capture=True)을 적용하고 그 위에 인자를 적용합니다.
• init_sdk(**options) — 저수준. 아래 옵션별 기본값(인자, 환경 변수, 내장 기본값 순)만 적용하며 추가 동작은 켜지 않습니다.

둘 다 트레이서, 미터, 로거 프로바이더를 시작해 OpenTelemetry 전역으로 설정하고, 설치된 모든 OpenTelemetry 계측을 로드합니다. SDK가 시작되면 True를, API 키가 없어 건너뛰었거나 이미 실행 중이면 False를 반환합니다.

옵션

핵심

캡처 토글

시그널 토글

수명 주기와 진단

고급과 확장

전송

엔드포인트 결정 순서(높은 것부터): 시그널별 인자, endpoint(시그널 경로 추가), 시그널별 환경 변수, OTEL_EXPORTER_OTLP_ENDPOINT(시그널 경로 추가), 기본값. 시그널 경로(/v1/traces, /v1/metrics, /v1/logs)는 http/protobuf에서만 붙고, gRPC 엔드포인트는 주어진 그대로 사용됩니다.

init()과 init_sdk()는 이 표의 모든 옵션을 키워드 인자로 받습니다. None을 전달하면 설정하지 않은 것으로 보고 환경 변수를 적용합니다.

불리언 환경 변수는 true/false, 1/0, yes/no, on/off를 받습니다.

예시

import os
 
from sophonz.opentelemetry import init_sdk
 
init_sdk(
    service="checkout-api",
    api_key=os.getenv("SOPHONZ_API_KEY"),
    service_version="2.4.1",
    deployment_environment="production",
    console_capture=True,
    experimental_exception_capture=True,
    advanced_network_capture=True,
    instrumentations={
        # 시끄러운 계측 끄기
        "urllib3": {"enabled": False},
        # 트레이스를 PostgreSQL까지 전달
        "psycopg": {"enable_commenter": True},
    },
)

계측

init()은 opentelemetry-instrument처럼 환경에 설치된 모든 OpenTelemetry 계측을 로드합니다. instrumentations 맵의 키는 계측의 엔트리 포인트 이름입니다 — flask, fastapi, django, psycopg, psycopg2, sqlalchemy, requests, httpx 등. 패키지 이름(opentelemetry-instrumentation-psycopg)도 받습니다. 각 값은 해당 계측기의 instrument()에 키워드 인자로 전달되며, "enabled": False는 그 계측을 건너뜁니다.

OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=requests,urllib3로도 계측을 건너뛸 수 있고, *는 전부 건너뜁니다. 계측별로 기록하는 내용은 계측에 정리되어 있습니다.

opentelemetry-instrument에서는 같은 맵을 SOPHONZ_PYTHON_INSTRUMENTATIONS에서 JSON으로 읽습니다.

export SOPHONZ_PYTHON_INSTRUMENTATIONS='{"psycopg": {"enable_commenter": true}, "urllib3": {"enabled": false}}'

데이터베이스 쿼리 트레이싱

psycopg, psycopg2, sqlalchemy extra를 설치하면 모든 쿼리가 클라이언트 스팬으로 트레이스됩니다. 트레이스를 PostgreSQL 안까지 이어가려면 SQLCommenter가 필요하며, 기본적으로 꺼져 있습니다.

init(
    service="checkout-api",
    api_key=os.getenv("SOPHONZ_API_KEY"),
    instrumentations={"psycopg": {"enable_commenter": True}},
)

SOPHONZ_PYTHON_SQLCOMMENTER=true는 opentelemetry-instrument에서도 psycopg와 psycopg2에 이를 켜며, 명시한 instrumentations 항목이 이보다 우선합니다. 드라이버별 옵션, 주석을 traceparent만으로 줄이는 방법, SQLAlchemy와 Django ORM, 준비된 문은 데이터베이스 트레이싱에서 다룹니다.

서비스 식별 정보

모든 시그널은 하나의 리소스를 공유합니다. SDK는 값이 있을 때 다음 속성을 추가합니다.

OTEL_RESOURCE_ATTRIBUTES도 계속 동작하며, SDK가 설정하지 않는 속성을 채웁니다.

export OTEL_RESOURCE_ATTRIBUTES="service.namespace=sophonz,team=payments"

OTEL_EXPORTER_OTLP_HEADERS와 시그널별 헤더 변수의 헤더는 전송 헤더에 병합됩니다. API 키가 설정되어 있으면 그 변수들의 authorization 헤더를 대체합니다.

service, OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES의 service.name이 모두 없으면 SDK는 시작하되 경고를 남기고, 텔레메트리는 unknown_service:python으로 보고됩니다.

detect_resources(기본값 켜짐)가 켜져 있으면 프로세스, OS, 호스트 속성이 아래에 더해지며, 위 표의 속성이 감지된 값보다 우선합니다.

컨텍스트 전파와 샘플링

전파기는 OpenTelemetry 기본값인 tracecontext,baggage(OTEL_PROPAGATORS)입니다. 들어온 traceparent는 서버 스팬이 이어받고, 기본 샘플러 parentbased_always_on은 브라우저가 샘플링한 트레이스를 모두 유지합니다.

모든 baggage 항목은 모든 스팬에 baggage.<key>로 복사됩니다. Sophonz 브라우저 SDK가 보내는 session.id는 session.id로도 복사되어, 브라우저와 서버 스팬을 하나의 속성으로 조회할 수 있습니다. 승격할 키는 promote_baggage_keys로 바꿀 수 있습니다. 브라우저 쪽 설정, CORS, 확인 방법은 브라우저-백엔드 트레이싱에서 다룹니다.

로그

console_capture가 켜져 있으면 SDK는 루트 로거에 OTLP 핸들러를 붙입니다. 레코드는 로깅 설정이 루트 로거에서 허용하는 레벨로 내보내지며(Python 기본값은 WARNING), 스팬 안에서 남긴 레코드는 해당 트레이스 ID와 스팬 ID를 가지고, extra={...} 필드는 속성이 됩니다. print()는 캡처하지 않습니다. logging.basicConfig, dictConfig, fileConfig는 init() 전후 모두 그대로 동작합니다.

error_log_capture가 켜져 있으면 ERROR 상태로 끝난 스팬은 그 스팬과 연결된 에러 로그 레코드 하나도 만듭니다. 둘 다 계측을 참고하세요.

고급 네트워크 캡처

advanced_network_capture=True(또는 SOPHONZ_PYTHON_ADVANCED_NETWORK_CAPTURE=true)는 서버·클라이언트 스팬의 요청·응답 헤더를 캡처하되 authorization, proxy-authorization, cookie, set-cookie, x-api-key는 [REDACTED]로 기록하고, requests, urllib(요청 본문만), FastAPI/Starlette의 본문을 캡처합니다. 본문은 16KiB로 잘리고, 민감한 키워드가 들어 있으면 [Filtered]로 대체됩니다. 어떤 스팬에 무엇이 붙는지, 설정되는 변수, 전체 키워드 목록은 계측에 있습니다.

제외 URL

SDK는 자신의 전송 URL을 OTEL_PYTHON_REQUESTS_EXCLUDED_URLS, OTEL_PYTHON_URLLIB_EXCLUDED_URLS, OTEL_PYTHON_URLLIB3_EXCLUDED_URLS, OTEL_PYTHON_HTTPX_EXCLUDED_URLS에 추가하며, 이미 설정한 값(OTEL_PYTHON_EXCLUDED_URLS 포함)은 유지합니다. 전송 요청이 나가는 HTTP 스팬으로 기록되지 않게 하기 위함입니다.

환경 변수

Sophonz 전용

OpenTelemetry