감사 로그 스키마와 식별자

감사 로그는 정해진 스키마를 가진 구조화된 기록입니다. audit.3의 requestFields와 resultFields, 과거 audit.2의 request_params와 result_params에는 이벤트별 정보가 들어갑니다. 요청 당시 알려진 값과 실제 실행 중 얻은 결과를 구분해 읽어야 합니다.

audit.3의 범주와 보장

Audit.3 로그는 하나 이상의 표준 범주를 결합해 생성합니다. 각 범주는 적용 대상과 요청 및 결과 필드를 정의합니다. 이름이 지정된 리소스 같은 주요 정보는 상세 필드뿐 아니라 최상위 엔터티에도 나타납니다.

이벤트 이름만 나열하지 않고 dataExport, dataLoad 같은 범주를 사용하면 여러 제품의 같은 종류의 동작을 함께 조사할 수 있습니다. 다만 passThrough처럼 상세 파라미터가 실행 중 외부 시스템에 의해 정해지는 범주는 내부 내용의 구조를 별도로 다뤄야 합니다.

audit.3 필드

필드	자료형	의미
`categories`	`set<string>`	이벤트에 포함된 모든 감사 범주입니다.
`entities`	`list<any>`	요청 및 결과 필드에 등장하는 리소스 등의 모든 엔터티입니다.
`environment`	`optional<string>`	로그가 생성된 환경입니다.
`eventId`	`uuid`	하나의 감사 대상 이벤트 식별자입니다. 큰 바이너리 응답의 시작과 끝처럼 여러 로그 행이 같은 이벤트에 속할 수 있습니다.
`host`	`string`	로그를 만든 호스트입니다.
`logEntryId`	`uuid`	개별 로그 행의 고유 식별자입니다. 수집 중 중복된 같은 ID의 행은 같은 기록으로 취급합니다.
`name`	`string`	감사 이벤트 이름입니다. 일반적으로 제품과 엔드포인트 이름을 대문자 snake case로 결합합니다. 예: `DATA_PROXY_SERVICE_GENERATED_GET_DATASET_AS_CSV2`.
`orgId`	`optional<string>`	알 수 있는 경우 uid 사용자의 조직입니다.
`origin`	`optional<string>`	IP나 Kubernetes 노드 등 발신 머신의 최선 추정 식별자입니다. 위조될 수 있습니다.
`origins`	`list<string>`	요청 헤더에서 얻은 네트워크 요청 출처입니다. 위조될 수 있으며 아래의 요청 연결 분석에 사용합니다.
`product`	`string`	로그를 생성한 제품입니다. 제품별 분석 필터에 권장되는 불변 필드입니다.
`producerType`	`AuditProducer`	백엔드 `SERVER`, 프런트엔드 `CLIENT`처럼 로그 생성 주체의 종류입니다.
`productVersion`	`string`	로그를 생성한 제품 버전입니다.
`requestFields`	`map<string, any>`	메서드 호출 시점에 알려진 파라미터입니다. 포함 필드는 categories에 따라 정해집니다.
`result`	`AuditResult`	성공 여부와 실패 종류입니다. 예를 들어 `ERROR`, `UNAUTHORIZED` 같은 결과가 있습니다.
`resultFields`	`map<string, any>`	실행 중 얻은 정보이며 반환값의 일부 등이 포함됩니다.
`sequenceId`	`optional<integer>`	같은 eventId를 공유하는 이벤트의 최선 추정 순서입니다.
`service`	`optional<string>`	로그를 만든 서비스입니다. 같은 제품의 서로 다른 인스턴스를 구분하는 데 쓸 수 있습니다.
`sid`	`optional<SessionId>`	알 수 있는 경우 세션 ID입니다.
`sourceOrigin`	`optional<string>`	TCP 스택에서 결정한 네트워크 요청 출처입니다.
`stack`	`optional<string>`	로그가 생성된 스택입니다.
`time`	`datetime`	RFC3339Nano 형식의 UTC 시각 문자열입니다. 예: `2025-11-13T23:20:24.180Z`.
`tokenId`	`optional<TokenId>`	알 수 있는 경우 API 토큰 ID입니다.
`traceId`	`optional<TraceId>`	알 수 있는 경우 Zipkin trace ID입니다.
`uid`	`optional<UserId>`	호출 체계에서 가장 하류 호출자의 사용자 ID입니다.
`userAgent`	`optional<string>`	로그를 유발한 요청의 user agent입니다.
`users`	`set<ContextualizedUser>`	해당 로그에 등장하는 모든 사용자입니다.

type 최상위 필드는 audit.2 또는 audit.3처럼 로그 형식을 구분하는 데 사용할 수 있습니다. Foundry 내보내기 데이터셋의 date 파티션 열은 이벤트 본문의 time과 구분합니다.

사용자 정보

ContextualizedUser의 구조에는 다음 필드가 있습니다.

필드	자료형
`uid`	`UserId`
`userName`	`optional<string>`
`firstName`	`optional<string>`
`lastName`	`optional<string>`
`groups`	`list<string>`
`realm`	`optional<string>`

현재 audit.3 전달 과정에서는 uid만 채우며 userName, firstName, lastName과 realm은 설정하지 않고 groups는 항상 빈 목록입니다. 낮은 지연의 전달 과정에서 신원 제공자를 실시간 조회하지 않기 때문입니다. 사용자 프로필이 필요하면 하류 파이프라인에서 사용자 디렉터리 데이터와 연결해 보강합니다. 빈 groups를 사용자가 실제로 어떤 그룹에도 속하지 않았다는 증거로 해석하면 안 됩니다.

사용자 요청과 API gateway 추적

origins가 비어 있지 않은 로그는 사용자 시작 요청을 찾는 기준입니다. 비어 있는 로그는 그 요청을 수행하는 과정에서 Palantir 백엔드가 시작한 서비스 요청에 해당합니다.

origins가 있고 categories에 apiGatewayRequest가 있으면 API gateway가 사용자 요청을 처리한 것입니다. 실제 하류 작업을 찾으려면 같은 traceId를 가진 로그 중 userAgent가 그 gateway 로그의 service 이름으로 시작하는 항목을 확인합니다.

origin과 origins는 위조될 수 있으므로 단독 신원 증거로 사용하지 않습니다. eventId는 여러 행을 한 사건으로 묶고, logEntryId는 같은 행의 중복을 제거하는 데 사용합니다. 서로 대체하지 않습니다.

과거 audit.2 필드

Audit.2에는 제품 간 요청 및 결과 구조의 공통 보장이 없습니다. 범주가 있다면 request_params 안의 _category 또는 _categories에 들어가지만, 범주 자체가 없을 수도 있습니다.

필드	자료형	의미
`filename`	`.log.gz` 파일명	아카이브의 압축 로그 파일 이름입니다.
`ip`	`string`	발신 IP의 최선 추정값입니다.
`name`	`string`	`PUT_FILE` 같은 이벤트 이름입니다.
`request_params`	`map<string, any>`	호출 시점에 알려진 파라미터입니다.
`result`	`AuditResult`	성공 또는 실패 등의 결과입니다.
`result_params`	`map<string, any>`	실행 중 얻은 정보와 반환값 일부입니다.
`sid`	`optional<SessionId>`	세션 ID입니다.
`time`	`datetime`	RFC3339Nano UTC 시각 문자열입니다.
`token_id`	`optional<TokenId>`	API 토큰 ID입니다.
`trace_id`	`optional<TraceId>`	Zipkin trace ID입니다.
`type`	`string`	`audit.2`입니다.
`uid`	`optional<UserId>`	가장 하류 호출자의 사용자 ID입니다.

두 스키마의 필드 이름을 바꾸는 것만으로 같은 의미의 데이터가 되는 것은 아닙니다. 전환 절차에서 상세 필드의 이동, 과거 이력과 중복 기간을 고려합니다.