Python 제로 코드 계측¶

Beacon Python의 제로 코드 흐름은 Python 3.10부터 3.14까지 지원합니다. 애플리케이션이 사용하는 것과 동일한 가상 환경에 설치하세요.

연동 전에 공통 설정에 따라 DataKit OpenTelemetry 수집기를 활성화하세요. 아래 명령은 Linux/macOS 셸을 기준으로 하며 애플리케이션과 DataKit이 같은 호스트에 있다고 가정합니다. 서로 다른 호스트나 컨테이너에서는 127.0.0.1을 바꾸고 수신 주소를 조정하세요.

설치¶

애플리케이션 프레임워크에 맞는 extra를 선택하세요.

# FastAPI. Flask 또는 requests를 사용하면 해당 extra로 바꾸세요.
pip install 'beacon-otel[fastapi]'

시작¶

export OTEL_SERVICE_NAME=my-python-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
beacon uvicorn myapp:app

uvicorn myapp:app을 애플리케이션의 기존 시작 명령으로 바꾸세요. beacon --version으로 현재 적용되는 버전을 확인할 수 있습니다.

디버깅 및 진단¶

Beacon Python의 제로 코드 진입점에는 통합 SDK 디버그 로그 스위치가 없습니다. OTEL_LOG_LEVEL=debug는 Python logging 수준을 자동으로 설정하지 않습니다. 상세 로그가 필요하면 애플리케이션의 기존 로그 설정에서 opentelemetry Logger를 DEBUG로 설정하고 출력 Handler를 구성하세요.

애플리케이션 소스 코드를 수정하지 않는 초기 진단으로, OTLP 내보내기를 유지하면서 콘솔 Span 출력을 추가할 수 있습니다.

beacon --version
OTEL_TRACES_EXPORTER=otlp,console \
  beacon uvicorn myapp:app > beacon-python-diagnostic.log 2>&1

위의 서비스 이름, OTLP 주소 및 프로토콜을 유지하고 지원되는 프레임워크의 API에 접근한 뒤 파일에서 Span을 확인하세요. 콘솔 사본은 Span 미생성과 수신 측 내보내기 실패를 구분하는 데 도움이 되지만, OTLP 전송 성공을 의미하지 않으며 SDK 디버그 로그도 아닙니다.

문제 해결 후 원래 시작 명령으로 복원하고 추가한 console 내보내기를 제거한 뒤 애플리케이션 로그 수준도 복원하세요.

Profile¶

먼저 DataKit Profile 수집기를 활성화한 뒤 아래 변수를 설정하고 위의 시작 방식을 유지하세요. Profile은 OTLP Trace 주소와 별개의 HTTP 업로드 주소를 사용합니다.

애플리케이션이 사용하는 가상 환경에 profiling extra를 설치하세요.

pip install 'beacon-otel[fastapi,profiling]'

fastapi를 애플리케이션에서 실제 사용하는 구성 요소로 바꾸세요.

HTTP로 pprof 업로드¶

export OTEL_SERVICE_NAME=my-python-service
export OTEL_PROFILING_ENABLED=true
export OTEL_PROFILING_EXPORTER=pprof_http
export OTEL_PROFILING_PPROF_UPLOAD_URL=http://127.0.0.1:9529/profiling/v1/input
beacon uvicorn myapp:app

인증이 필요하면 OTEL_PROFILING_PPROF_HEADERS로 쉼표로 구분한 name:value HTTP 헤더를 설정할 수 있습니다.

로컬 pprof 파일에 기록¶

export OTEL_PROFILING_ENABLED=true
export OTEL_PROFILING_EXPORTER=pprof
export OTEL_PROFILING_PPROF_PATH="$PWD/profiles"
beacon uvicorn myapp:app

대상 디렉터리를 먼저 생성하고 배포 환경의 파일 보존 정책에 포함하세요.

추가 수집기¶

Profile을 활성화하면 기본적으로 스택 샘플링이 수행됩니다. 필요에 따라 다른 수집기를 추가하세요.

export OTEL_PROFILING_MEMORY_ENABLED=true
export OTEL_PROFILING_LOCK_ENABLED=true
# Python 3.12 이상에서만 사용
export OTEL_PROFILING_EXCEPTION_ENABLED=true

기본 내보내기 주기는 60초입니다. 주기적으로 업로드하려면 프로세스가 해당 주기보다 오래 실행되어야 합니다.

파라미터 참조¶

환경 변수 이름은 대소문자를 구분합니다. 런타임 표의 간격 값은 초 단위입니다.

런타임 및 수집기¶

환경 변수	유형 / 허용 값	기본값	설명
`OTEL_PROFILING_ENABLED`	불리언	`false`	자동 계측 초기화 단계에서 Profiler를 시작합니다.
`OTEL_PROFILING_EXPORTER`	`none`、`pprof`、`pprof_http`、`otlp`	자동 선택	내보내기를 선택합니다. 설정하지 않은 경우 pprof 업로드 URL이 있으면 `pprof_http`, 그렇지 않으면 `otlp`가 선택됩니다.
`OTEL_PROFILING_SAMPLE_INTERVAL`	양수	`0.01`	호출 스택 샘플링 간격.
`OTEL_PROFILING_EXPORT_INTERVAL`	양수	`60`	Profile 플러시 및 내보내기 간격.
`OTEL_PROFILING_MAX_FRAMES`	양의 정수	`64`	샘플당 캡처할 최대 스택 프레임 수.
`OTEL_PROFILING_INCLUDE_TRACE_CONTEXT`	불리언	`true`	사용 가능한 경우 현재 Trace 및 Span 컨텍스트를 추가합니다.
`OTEL_PROFILING_EXCEPTION_ENABLED`	불리언	`false`	예외 Profile을 활성화합니다.
`OTEL_PROFILING_EXCEPTION_SAMPLING_INTERVAL`	양의 정수	`100`	예외 샘플링 간격.
`OTEL_PROFILING_EXCEPTION_COLLECT_MESSAGE`	불리언	`false`	예외 메시지를 수집합니다. 활성화하기 전에 민감한 데이터에 미치는 영향을 검토하세요.
`OTEL_PROFILING_LOCK_ENABLED`	불리언	`false`	threading 및 asyncio 잠금 수집기를 활성화합니다.
`OTEL_PROFILING_MEMORY_ENABLED`	불리언	`false`	메모리 Profile을 활성화합니다.
`OTEL_PROFILING_MEMORY_INTERVAL`	양수	내보내기 간격	메모리 수집 간격.
`OTEL_PROFILING_MEMORY_TOP_STATS`	양의 정수	`200`	메모리 수집마다 유지할 최대 통계 항목 수.
`OTEL_PROFILING_MEMORY_IGNORE_PROFILER`	불리언	`true`	Profiler 자체에서 발생한 메모리 할당을 제외합니다.

pprof 내보내기¶

환경 변수	유형 / 허용 값	기본값	설명
`OTEL_PROFILING_PPROF_PATH`	파일 경로 접두사	`otel-profiles`	생성되는 `.pprof` 파일의 경로 접두사. 두 pprof 내보내기 모두 로컬 사본을 유지합니다.
`OTEL_PROFILING_PPROF_UPLOAD_URL`	HTTP(S) URL	`http://localhost:8126/profiling/v1/input`	`pprof_http`의 업로드 주소. 내보내기가 설정되지 않은 경우 이 변수를 지정해도 `pprof_http`가 선택됩니다.
`OTEL_PROFILING_PPROF_HEADERS`	쉼표로 구분한 `name:value`	비어 있음	추가 HTTP 요청 헤더.

Security¶

동일한 beacon-otel wheel에 선택적으로 활성화할 수 있는 Security가 포함되어 있으며 표준 GIL CPython 3.11부터 3.14까지 지원합니다. Python Security 가이드를 참조하세요.

연동 확인¶

지원되는 프레임워크나 라이브러리를 거치는 요청을 애플리케이션 API에 보낸 뒤 Guance의 APM > 트레이스에서 위에 설정한 서비스 이름으로 필터링하세요. 전체 확인 절차는 공통 설정을, 데이터가 없으면 문제 해결을 참조하세요.