Anthropic Python SDK 1.14.0으로 올릴 때는 환경변수만 보지 말고, 클라이언트를 만드는 공통 함수부터 확인하세요. open_telemetry에 빈 딕셔너리라도 명시하면 Anthropic 텔레메트리 환경변수를 읽지 않습니다. 환경에서 추적을 꺼 두었더라도, 코드가 새로 전달한 옵션의 기본값이 적용될 수 있습니다.
확인일은 2026년 10월 15일(KST)입니다. 대상은 PyPI의 anthropic 패키지 1.14.0 정식 릴리스이며, GitHub 공개 시각은 10월 14일 17:13:08 UTC입니다. 이 글은 고정 버전의 문서와 구현을 대조한 설정 검토 가이드입니다. SDK 실행, 실제 API 호출, 수집기 전송이나 개인정보 보호 효과를 실험으로 검증한 글은 아닙니다.
먼저 세 가지 결정을 나눕니다
혼자 개발하거나 작은 팀에서 공통 클라이언트 팩터리를 쓰면, 한 줄의 옵션 추가가 여러 작업에 함께 적용됩니다. 변경 전에 다음 세 질문의 답을 각각 남겨 두세요.
- span을 만들 것인가? 요청·스트림·도구 실행을 관찰하는 기록의 생성 정책입니다.
- 무엇을 기록할 것인가? 메타데이터만 남길지, 프롬프트·응답 내용까지 포함할지의 결정입니다.
- 추적 문맥을 HTTP 헤더로 전달할 것인가? 다른 서비스의 기록과 연결하는 전파 정책입니다.
그리고 별도로 어느 수집기로 내보내는가를 확인합니다. 이 SDK는 OpenTelemetry API에 의존하지만 OpenTelemetry SDK나 exporter를 자동으로 구성하지 않습니다. 앱에 tracer provider가 등록되어 있는지, 기록을 실제로 처리·내보내는 설정이 있는지를 함께 봐야 합니다. “업데이트했으니 무조건 외부 전송된다”와 “exporter를 이 코드에서 안 만들었으니 전송되지 않는다” 모두 설정 확인 없이 내릴 결론은 아닙니다.
설정 우선순위는 클라이언트 생성 지점에서 확인합니다
1.14.0의 문서와 옵션 해석 구현을 기준으로 나눈 경우입니다. 아래는 실행 결과표가 아니라 소스에서 확인한 설정 선택 규칙입니다.
- 옵션을 생략하거나 None을 전달한 새 클라이언트: 생성 시점의 Anthropic 텔레메트리 환경변수를 읽습니다. 나중에 환경변수만 바꿔도 이미 만든 클라이언트가 다시 읽지는 않습니다.
- 빈 딕셔너리 또는 tracer_provider만 전달한 새 클라이언트: Anthropic 텔레메트리 환경변수를 전부 건너뜁니다. 지정하지 않은 항목은 span 활성화,
metadata_only, 전파 활성화, 콘텐츠 예산 750,000바이트라는 기본값으로 채워집니다. - with_options 또는 copy로 만든 복사본: 옵션을 생략하거나 None을 전달하면 원본에서 이미 해석한 설정을 이어받으며 환경변수를 다시 읽지 않습니다. None이 아닌 새 옵션은 기존 옵션 전체를 교체하므로, 일부 항목만 덧붙인다는 가정은 피하세요.
예를 들어 배포 환경에서 ANTHROPIC_OPEN_TELEMETRY=false를 사용하던 서비스에 공통 팩터리가 빈 옵션을 추가했다면, 환경의 끄기 값이 선택되지 않는지 검토해야 합니다. provider만 바꾼 변경도 같은 점검 대상입니다. 이것은 해당 서비스에서 실제로 기록이 전송됐다는 뜻이 아니라, 환경 설정이 더 이상 제어하지 않는 생성 경로가 생겼다는 뜻입니다.
끄기 요청의 범위를 좁혀 말하세요
open_telemetry=False는 이 SDK의 span 생성을 끄는 설정입니다. 전파는 별도 옵션입니다. 두 정책을 모두 명시적으로 끄려면 traces와 propagation을 각각 false로 지정하는 구성을 검토하세요. 반대로 전파만 끄는 설정은 span 생성까지 끄는 설정이 아닙니다.
span을 끈 상태에서도 이 SDK가 반드시 헤더를 보낸다고 단정할 수는 없습니다. 실제 헤더 주입에는 span 존재 등 구현 조건이 관여합니다. 또한 앱에 별도로 붙인 HTTP 계측은 별개의 span이나 헤더를 만들 수 있습니다. 따라서 SDK 옵션 하나를 프로세스 전체의 추적 중지 스위치로 설명하면 안 됩니다.
metadata_only에서도 필드 검토는 필요합니다
기본 모드에서는 프롬프트와 응답 본문을 기록하지 않습니다. 그래도 요청 ID, 조직·워크스페이스·대화 및 다른 리소스 식별자 같은 메타데이터가 기록될 수 있습니다. 메타데이터라는 이름만으로 익명 데이터라고 판단하지 말고, 실제 앱이 쓰는 필드와 수집기 접근 범위를 확인하세요.
명시적으로 content 모드를 선택하면 시스템 지시, 메시지, 도구 인자·결과, reasoning 텍스트 등 검토할 내용이 넓어집니다. 바이너리·이미지·문서나 암호화 필드에 대한 제외 처리가 있더라도 일반적인 개인정보 마스킹을 보장하지는 않습니다. max_content_bytes 역시 콘텐츠를 자르는 예산이지, 전체 span의 엄격한 크기 상한이나 비밀정보 제거 기능이 아닙니다.
작은 팀의 적용 순서: 기록 정책을 먼저 고정합니다
- 생성 경로를 목록으로 만듭니다. 웹 요청용, 배치 작업용, 도구 실행용 클라이언트와 공통 팩터리·복사본을 찾습니다. 각 경로가 환경변수와 명시적 옵션 중 어느 쪽을 사용하는지 적습니다.
- 환경과 코드 중 정책의 기준을 정합니다. 환경변수로 제어하려면 무심코 빈 옵션을 넣지 않는지 확인합니다. 코드로 제어한다면 span·내용·전파를 각각 명시하고, 새 옵션이 기존 정책을 대체하는지 리뷰합니다.
- 기존 계측과 수집 경로를 함께 확인합니다. tracer provider, HTTP 자동 계측, exporter의 목적지와 접근·보관 정책을 담당자와 대조합니다. 이 글의 SDK 설정만으로 전체 수집 경로를 판정하지 않습니다.
- 비민감 합성 데이터로 검증할 항목을 정합니다. 새 클라이언트와 복사본 각각에 대해 span 유무, 본문 포함 여부, 식별자 필드, 요청 헤더를 확인하도록 체크리스트를 만듭니다. 이는 독자가 자기 환경에서 수행할 검증 항목이며, 이 글에서 통과시킨 테스트 결과는 아닙니다.
- 한 경로부터 적용하고 되돌릴 단위를 남깁니다. 의존성 업그레이드와 텔레메트리 정책 변경을 분리해 리뷰합니다. 문제가 생기면 이전에 검증한 잠금 파일과 팩터리 설정을 함께 복원하고 클라이언트를 새로 생성합니다. 이미 내보낸 기록은 코드 롤백으로 지워지지 않습니다.
호환성과 검증 범위
anthropic 1.14.0은 Python 3.10 이상을 요구하고 MIT 라이선스입니다. 고정 manifest에는 opentelemetry-api >=1.1,<2와 httpx2 >=2,<3가 들어 있습니다. 기존 0.x 조합에서 버전 숫자만 올리는 작업으로 보지 말고 잠금 파일의 의존성 변화도 검토하세요. 이 글은 Claude Agent SDK, Claude Code, 관리 API의 telemetry destination 설정을 다루지 않습니다.
남길 결론: “추적을 껐다”보다 “어떤 생성 경로에서 span·내용·전파를 어떤 값으로 해석했고, 어떤 수집 경로를 확인했는가”를 기록하세요. 그래야 공통 팩터리의 작은 변경이 환경의 정책을 바꿨는지 알아볼 수 있습니다.
댓글
댓글 쓰기