트레이스와 접근 제어
트레이스와 접근 제어
게이트웨이 트레이스가 어디에 기록되는지, 누가 무엇을 보고 구성할 수 있는지 이해하는 방법을 알려드릴게요.
참고: LLM Gateway는 베타 상태입니다.
LLM Gateway를 통한 모든 호출은 LangSmith에 트레이싱되며, 정책 위반은 LangSmith Engine에서 분류를 위해 표시됩니다.
참고: 게이트웨이 트레이스는 모든 호출에 대해 메타데이터(토큰 수, 정책 결과, 호출자 신원)를 기록합니다. 입력·출력 콘텐츠는 기본적으로 기록되지 않으며, 콘텐츠가 없는 트레이스는 LangSmith 트레이스 할당량에 청구되지 않습니다. 콘텐츠 로깅과 관련 청구는 데이터 정책으로 명시적으로 활성화할 때만 적용됩니다.
출처: 문서
본문
게이트웨이 트레이스가 나타나는 위치
기본적으로 콘텐츠 트레이싱은 모든 조직에서 꺼져 있습니다. 콘텐츠 트레이싱이 켜져 있으면 게이트웨이 프록시 호출은 호출자의 API 키와 연결된 워크스페이스의 gateway라는 프로젝트와, UI에서 트래픽을 분리하는 호출자별 프로젝트에 트레이싱됩니다. 워크스페이스 API 키로 인증하는 호출자는 gateway/short-api-key/<short_key>/api-key-id/<api_key_id>를 얻고, 워크스페이스 API 키 없이 bearer 토큰으로 인증하는 호출자는 gateway/user/<obfuscated_email>/ls_user_id/<ls_user_id>를 얻습니다.
RBAC와 ABAC로 이 트레이싱 프로젝트에 대한 접근을 제어하세요.
트레이스 메타데이터
게이트웨이 프록시 호출은 기록되는 프로젝트와 span에 첨부된 메타데이터로 직접 LLM 호출과 구분할 수 있습니다:
- 게이트웨이 프로젝트: 모든 게이트웨이 트래픽은 각 워크스페이스의
gateway라는 프로젝트에 기록되며, UI 격리용 호출자별 사본도 있습니다. 프로젝트(또는langsmith.metadata.gateway.*span 속성의 존재)로 필터링해 게이트웨이 프록시 호출을 찾으세요. - 정책 평가 결과: 모든 게이트웨이 span은
langsmith.metadata.gateway.policy.matched_ids/_names,passed_ids/_names,violated_ids/_names를 통해 어떤 정책이 평가되었고 결과가 무엇인지 기록하므로 통과와 차단 모두 캡처됩니다. - 가드 규칙 매칭: redaction 정책이 적용될 때 가드 파이프라인은 span에
policy.matched_rules,passed_rules,violated_rules로 찍힌rule_id → count맵을 생성합니다. 이것은 규칙 ID이며 PII나 시크릿 카테고리 레이블이 아닙니다. - 비용 데이터: 토큰 수와 비용은 인라인으로 계산되며, spend 캡 정책이 시행하는 것과 동일한 지출 누적기에 공급됩니다.
트레이스 콘텐츠
트레이스 콘텐츠(요청·응답 본문)는 기본적으로 꺼져 있습니다. 콘텐츠가 없는 트레이스는 LangSmith 트레이스 할당량에 청구되지 않습니다. 정책 범위와 일치하는 게이트웨이를 통해 내보내지는 모든 트레이스에 적용되는 데이터 정책으로 콘텐츠 로깅을 켜세요. 콘텐츠 로깅 데이터 정책과 일치하는 트레이스는 요금제의 트레이스 볼륨에 계산됩니다.
LangSmith Engine 통합
거버넌스 정책이 발화하면(예: 지출 한도 도달, PII 감지·삭제, 시크릿 적발) 해당 이벤트가 트레이스의 메타데이터로 기록됩니다. 이러한 정책 위반은 LangSmith Engine에서 이슈로 표면화됩니다.
Engine 이슈에서 다음을 할 수 있습니다:
- 위반 확인: 어떤 정책이 발화했고, 무엇이 차단·삭제되었는지.
- 트레이스로 클릭스루: 정책이 트리거되었을 때 에이전트가 정확히 무엇을 하고 있었는지 확인.
- 근본 원인 진단: 예산을 태우는 재시도 루프였는지, 사용자가 프롬프트에 자격 증명을 붙여넣었는지, 아니면 한도를 초과한 정당한 워크로드였는지 등.
- 조치: 에이전트 구성 업데이트, 정책 조정, 또는 에스컬레이션.
감사 로깅
게이트웨이는 두 가지 카테고리의 이벤트를 기록합니다:
| Category | What's logged |
|---|---|
| 행정 변경(Administrative changes) | 정책 생성, 수정, 삭제. 게이트웨이 접근과 관련된 역할·권한 변경. |
| 게이트웨이 호출(Gateway invocations) | 각 프록시 호출. 호출자 신원과 일치한 정책 ID 포함. |
감사 로그는 Enterprise 요금제의 조직 관리자에게 제공됩니다.
권한
필수 권한
| Action | Permission needed | 기본 보유자 |
|---|---|---|
| 게이트웨이를 통한 호출 | gateway:invoke + workspaces:read |
WORKSPACE_ADMIN만 |
| 정책 생성, 편집, 삭제 | organization:manage |
Org admins |
| 게이트웨이 트레이스 보기 | projects:read + runs:read |
WORKSPACE_ADMIN, WORKSPACE_USER, WORKSPACE_VIEWER |
| 감사 로그 보기 | organization:manage |
Org admins |
빌트인 WORKSPACE_USER와 WORKSPACE_VIEWER 역할은 gateway:invoke를 포함하지 않으며 편집할 수 없습니다. 워크스페이스 전체 관리자 권한 없이 게이트웨이 접근을 부여하려면 gateway:invoke와 workspaces:read로 커스텀 워크스페이스 역할을 만드세요(RBAC 활성 요금제 필요). 지침은 Admin 설정을 참고하세요.
API 키 범위 지정
게이트웨이에는 항상 워크스페이스 범위의 API 키를 사용하세요. 조직 범위 키는 게이트웨이 호출에 지원되지 않습니다.
프로바이더 자격 증명 중앙화
게이트웨이는 프로바이더 API 키를 LangSmith 워크스페이스 시크릿에 중앙화합니다. 개별 개발자와 에이전트는 LangSmith API 키로 인증하며 프로바이더 키에 직접 접근할 필요가 없습니다.
즉:
- 자격 증명 제어: 프로바이더 키는 한 곳, 관리자가 관리하는 곳에 있습니다. 접근을 취소한다는 것은 분산된 프로바이더 키 사본을 찾는 것이 아니라 LangSmith API 키를 취소한다는 뜻입니다.
- 정책 시행: 모든 호출이 게이트웨이를 통과하므로 정책이 일관되게 시행됩니다. 개발자가 프로바이더 키에 별도로 접근할 수 없는 한, 프로바이더를 직접 호출해 비용 한도를 우회할 방법이 없습니다.
Claude Code Plus 및 Max 사용자의 경우 Anthropic OAuth 패스스루가 모든 조직에 제공됩니다. 호출자는 게이트웨이 인증을 위해 워크스페이스 범위 LangSmith API 키를, 프로바이더 인증을 위해 Anthropic OAuth bearer를 보냅니다. 게이트웨이 권한, 정책, 트레이싱은 계속 적용되며, OAuth bearer는 Anthropic에만 전달되고 게이트웨이는 워크스페이스의 ANTHROPIC_API_KEY를 로드하지 않습니다. Anthropic은 이 호출을 사용자의 Claude 구독에 청구합니다. 구성 지침은 코딩 에이전트 설정을 참고하세요.
트레이스 가시성 제한
게이트웨이 트레이스는 워크스페이스 프로젝트의 실행으로 기록되며 LangSmith의 표준 워크스페이스 구성원 모델을 따릅니다. 워크스페이스에서 runs:read(및 프로젝트 자체를 보기 위한 projects:read)가 있는 사람은 누구나 해당 워크스페이스의 게이트웨이 프로젝트에서 트레이스를 볼 수 있습니다. 빌트인 역할 WORKSPACE_ADMIN, WORKSPACE_USER, WORKSPACE_VIEWER는 모두 기본적으로 두 권한을 포함합니다.
게이트웨이 트레이스를 볼 수 있는 사람을 제한해야 한다면 두 가지 옵션이 있습니다:
- 별도 워크스페이스 (모든 요금제에서 동작): 구성원이 제한된 워크스페이스 하나와, 구성원이 더 넓은 개발자 코딩 에이전트용 워크스페이스 하나를 만듭니다. 각 워크스페이스에는 자체 프로바이더 시크릿과 트레이스 프로젝트가 있습니다.
- 프로젝트 수준 접근 정책 (Enterprise 요금제 필요): 게이트웨이 프로젝트의
projects:read와runs:read를 특정 사용자나 역할로 제한하는 ABAC 정책을 작성합니다.