OpenTelemetry Python¶

OpenTelemetry Python Agent는 런타임 monkey patch를 통해 지원되는 Python 라이브러리 및 프레임워크에 텔레메트리 기능을 주입합니다. opentelemetry-instrument로 애플리케이션을 시작하면 비즈니스 코드를 수정하지 않고도 웹 요청, HTTP 클라이언트, 데이터베이스, 메시지 큐 등의 호출을 수집할 수 있습니다.

이 문서에서는 DataKit의 OpenTelemetry 수집기를 사용하여 OTLP 데이터를 수신하고 Guance로 전달합니다.

Python 애플리케이션 + OpenTelemetry Python Agent -> OTLP -> DataKit -> Guance

전제 조건¶

• Python 3.10 이상
• pip 및 사용 가능한 Python 가상 환경
• DataKit이 설치되어 있고, DataKit이 대상 Guance 워크스페이스에 연결되어 있어야 함
• Python 애플리케이션에서 DataKit으로의 네트워크 연결 가능: OTLP/HTTP는 DataKit HTTP 포트 9529 사용, OTLP/gRPC는 기본적으로 4317 사용

1. OpenTelemetry 수집기 활성화¶

DataKit 설치 디렉터리의 conf.d/opentelemetry로 이동합니다. 수집기 구성이 아직 생성되지 않은 경우 샘플 파일을 복사합니다.

cd /usr/local/datakit/conf.d/opentelemetry
sudo cp opentelemetry.conf.sample opentelemetry.conf

opentelemetry.conf에 최소한 다음 수신 구성이 포함되어 있는지 확인합니다.

[[inputs.opentelemetry]]
  # Guance에서 태그로 유지할 사용자 정의 속성을 허용 목록에 추가합니다.
  customer_tags = ["team", "project"]

  [inputs.opentelemetry.http]
    http_status_ok = 200
    trace_api = "/otel/v1/traces"
    metric_api = "/otel/v1/metrics"
    logs_api = "/otel/v1/logs"

  [inputs.opentelemetry.grpc]
    addr = "127.0.0.1:4317"
    max_payload = 16777216

수신 주소는 다음과 같습니다.

Python 애플리케이션이 DataKit과 동일한 호스트에 없는 경우 실제 배포에 따라 DataKit 수신 주소, 방화벽 또는 기타 네트워크 액세스 제어를 조정해야 합니다. gRPC의 경우 addr을 애플리케이션이 액세스할 수 있는 수신 주소(예: 0.0.0.0:4317)로 변경할 수 있습니다. OTLP 수신 포트를 공용 네트워크에 직접 노출하지 마십시오.

DataKit을 재시작하고 서비스를 확인합니다.

sudo datakit service restart
curl http://127.0.0.1:9529/v1/ping

2. 애플리케이션에 OpenTelemetry 연결¶

가상 환경 생성¶

OpenTelemetry Agent, 애플리케이션 및 계측 패키지는 동일한 Python 환경에 설치되어야 합니다. 애플리케이션에 대해 별도의 가상 환경을 사용하는 것이 좋습니다.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

먼저 애플리케이션 자체 종속성을 설치합니다. 예를 들면 다음과 같습니다.

python -m pip install -r requirements.txt

Agent, Exporter 및 계측 패키지 설치¶

Python Package Index 공식 패키지 소스에서 OpenTelemetry Distro와 OTLP exporter를 설치합니다.

python -m pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install

opentelemetry-distro는 SDK, opentelemetry-bootstrap 및 opentelemetry-instrument를 제공합니다. opentelemetry-bootstrap -a install은 현재 환경에 설치된 애플리케이션 종속성을 확인하고 일치하는 계측 패키지를 설치합니다. 예를 들어 환경에 Flask가 있는 경우 opentelemetry-instrumentation-flask를 설치합니다.

애플리케이션 종속성을 먼저 설치한 후 bootstrap을 실행해야 합니다. 애플리케이션에 프레임워크, 데이터베이스 드라이버, HTTP 클라이언트 등의 종속성을 추가하거나 업그레이드한 후에는 다음 명령을 다시 실행하는 것이 좋습니다.

opentelemetry-bootstrap -a install

설치하지 않고 설치될 계측 패키지를 미리 확인하려면 다음 명령을 실행합니다.

opentelemetry-bootstrap

애플리케이션 구성 및 시작¶

다음은 OTLP/HTTP + Protobuf를 예로 들어 기본적으로 Trace에 연결하고 Metric과 Log는 일시적으로 비활성화합니다.

export OTEL_SERVICE_NAME="order-service"
export OTEL_RESOURCE_ATTRIBUTES="env=prod,version=1.0.0,team=backend"

export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="none"
export OTEL_LOGS_EXPORTER="none"

export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:9529/otel"
export OTEL_PROPAGATORS="tracecontext,baggage"
export OTEL_PYTHON_LOG_AUTO_INSTRUMENTATION="false"

opentelemetry-instrument python app.py

OTEL_EXPORTER_OTLP_ENDPOINT는 기본 주소입니다. OTLP/HTTP exporter는 데이터 유형에 따라 자동으로 /v1/traces, /v1/metrics 또는 /v1/logs를 추가하며, 최종적으로 DataKit의 /otel/v1/* 라우트에 매핑됩니다.

실제 애플리케이션 프로세스를 시작하려면 opentelemetry-instrument를 사용해야 합니다. 환경 변수만 설정하고 python app.py를 직접 실행하면 제로 코드 자동 계측이 활성화되지 않습니다.

일반적인 시작 방법¶

Flask 개발 서버:

opentelemetry-instrument flask --app app run --host 0.0.0.0 --port 8080

Gunicorn:

opentelemetry-instrument gunicorn --workers 1 --bind 0.0.0.0:8080 app:app

Gunicorn과 같은 사전 포크(pre-fork) 서버가 여러 worker를 사용하는 경우 자동 계측 및 Metric 내보내기가 프로세스 fork 동작의 영향을 받을 수 있습니다. 먼저 단일 worker로 테스트하는 것이 좋습니다. 프로덕션 환경에서 다중 프로세스가 필요한 경우 사용 중인 프레임워크와 신호 유형에 따라 공식 사전 포크 배포 방안을 평가해야 합니다.

Django 개발 서버:

opentelemetry-instrument python manage.py runserver 0.0.0.0:8080

프로덕션 환경에서 Supervisor, systemd 또는 다른 프로세스 관리자를 사용하는 경우 환경 변수와 opentelemetry-instrument를 실제 시작 명령에 포함시킨 후 애플리케이션을 재시작합니다.

OTLP/gRPC 사용¶

설치된 opentelemetry-exporter-otlp에는 OTLP exporter가 이미 포함되어 있습니다. gRPC를 사용하려면 프로토콜과 endpoint를 변경합니다.

export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4317"

gRPC endpoint에는 /v1/traces와 같은 HTTP 경로를 추가할 수 없습니다.

3. 데이터 보고 파라미터¶

Python Agent는 명령줄 인수와 환경 변수를 지원합니다. 명령줄 인수 이름을 환경 변수로 변환할 때는 대문자로 바꾸고 OTEL_ 접두사를 추가해야 합니다. 예를 들어 --service_name은 OTEL_SERVICE_NAME에 해당합니다. 동일한 파라미터가 명령줄과 환경 변수를 통해 동시에 설정된 경우 명령줄 인수가 우선합니다.

기본 파라미터¶

service.name은 Guance에서 서비스 소속을 식별하는 데 사용됩니다. env와 version을 함께 설정하여 환경 및 버전별로 필터링하는 것이 좋습니다. 다른 사용자 정의 리소스 속성은 DataKit customer_tags 허용 목록에 추가되어야 태그로 유지됩니다. 속성 이름의 .은 _로 변환됩니다.

Python 자동 계측 파라미터¶

OTLP 파라미터¶

DataKit의 OTLP/HTTP 수집은 Protobuf만 지원하므로 http/protobuf를 사용하고 http/json은 사용하지 마십시오. 통합 endpoint와 특정 데이터 유형의 endpoint가 동시에 존재하는 경우 특정 데이터 유형의 구성이 우선합니다.

샘플링 및 배치 보고 파라미터¶

프로덕션 환경에서는 트래픽과 데이터 예산에 따라 샘플링 비율을 설정해야 합니다. 애플리케이션 측 헤더 샘플링과 DataKit 측 샘플링이 동시에 활성화되면 최종 유지율이 중첩되어 감소하므로 샘플링 위치를 통합적으로 계획해야 합니다.

연결 확인¶

설치된 계측 라이브러리를 사용하는 애플리케이션 라우트를 요청한 후 DataKit 호스트에서 수신 로그를 확인합니다.

curl http://127.0.0.1:8080/
sudo tail -f /usr/local/datakit/log/gin.log | grep '/otel/v1/'

/otel/v1/traces에 대한 POST 요청이 나타나고 응답 코드가 200이면 DataKit이 Trace를 수신한 것입니다. 그런 다음 Guance의 "APM(애플리케이션 성능 모니터링) > 분산 추적"으로 이동하여 service:order-service로 조회합니다.

데이터가 없으면 다음 사항을 순서대로 확인하십시오. 애플리케이션과 OpenTelemetry가 동일한 가상 환경에 설치되었는지, 애플리케이션 종속성 설치 후 opentelemetry-bootstrap -a install을 실행했는지, opentelemetry-instrument를 통해 시작했는지, 실제 코드 경로가 지원되는 계측 라이브러리를 사용하는지, 그리고 OTLP endpoint에 연결할 수 있는지 확인합니다.

참고¶

• OpenTelemetry 수집기 구성
• OpenTelemetry Python 제로 코드 계측
• OpenTelemetry Python Agent 구성
• OpenTelemetry Python 자동 계측 예시
• OpenTelemetry Python Distro
• OpenTelemetry OTLP Exporter 구성