> For the complete documentation index, see [llms.txt](https://genos-docs.gitbook.io/default/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://genos-docs.gitbook.io/default/v1.9.4/common-features/usage-log-custom-filter.md).

# 이용 로그 사용자 지정 검색

이용 로그의 「사용자 지정」 검색은 **로그에 적재된 JSON 값을 임의의 키 경로로 지정해 찾는 기능**입니다. 기존에는 요청 ID·POD ID·IP·세션 ID처럼 미리 정해진 항목으로만 검색할 수 있었지만, 이제 `input`·`output`·`metadata` 컬럼 안의 원하는 필드를 직접 지목해 "그 값이 무엇인 로그"를 걸러낼 수 있습니다.

검색 필드 드롭다운에서 「사용자 지정」을 고르면 입력창이 `[키] [연산자] [값]` 형태로 바뀝니다. 키를 직접 입력할 수도 있고, 옆의 **\[필터 간편 선택]** 버튼으로 최근 로그의 JSON 구조를 펼쳐 보며 클릭으로 고를 수도 있습니다.

<figure><img src="https://1274363562-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJuB29xjw7zmR91VXmqf%2Fuploads%2FVDtHxcnIufAyQZwkNcpa%2F01_search_field_custom_option.png?alt=media&amp;token=be95a3ec-1738-47fc-8de1-7099c3564343" alt=""><figcaption></figcaption></figure>

### 적용 대상 화면

이용 로그 탭 5곳에서 동일하게 제공됩니다.

| 화면                 | 위치                |
| ------------------ | ----------------- |
| 모델 서빙 상세 > 이용 로그   | 서빙 > 모델 서빙 > 상세   |
| 코드 서빙 상세 > 이용 로그   | 서빙 > 코드 서빙 > 상세   |
| 워크플로우 상세 > 이용 로그   | 에이전트 > 워크플로우 > 상세 |
| MCP 서버 상세 > 이용 로그  | 도구 > MCP 서버 > 상세  |
| 서비스 라우터 상세 > 이용 로그 | 서비스 라우터 > 상세      |

### 사용 방법

1. 이용 로그 탭에서 검색 필드 드롭다운을 열고 「사용자 지정」을 선택합니다. (기존 항목: 요청 ID · POD ID · IP · 세션 ID)
2. 입력창이 `[키] [연산자] [값]` 세 칸으로 바뀝니다. 키 칸 플레이스홀더는 `예: metadata.attributes.user.id`, 값 칸은 `예: 511` 입니다.
3. 가운데 드롭다운에서 `==`(기본) 또는 `!=`를 고릅니다.
4. 값을 입력하고 검색하면 해당 조건에 맞는 로그만 조회됩니다.

* **키와 값이 모두 채워져야 검색이 실행됩니다.** 둘 중 하나만 채우면 필터가 적용되지 않고 전체 목록이 그대로 표시됩니다.
* 조건은 한 번에 한 건만 지정할 수 있습니다.
* 기간(날짜 범위) 선택은 기존과 동일하게 함께 적용됩니다.

<figure><img src="https://1274363562-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJuB29xjw7zmR91VXmqf%2Fuploads%2FmS8yz50HW0S4IvEkNwqR%2F02_custom_filter_inputs.png?alt=media&amp;token=2ace1900-6057-45fe-9d7f-e885180e536c" alt=""><figcaption></figcaption></figure>

### 검색 키 작성 규칙

키는 `<컬럼>.<경로>` 형식이며, 첫 점(`.`) 앞이 컬럼, 뒤가 JSON 경로입니다. 컬럼은 `input` · `output` · `metadata` 3종만 지원합니다.

| 형태       | 예시                            | 의미                    |
| -------- | ----------------------------- | --------------------- |
| 멤버 접근    | `output.model`                | `output` 안의 `model` 값 |
| 중첩 접근    | `metadata.attributes.user.id` | 중첩된 하위 필드             |
| 점이 포함된 키 | `metadata."service.name"`     | 키 자체에 점이 있으면 큰따옴표로 감쌈 |
| 배열 인덱스   | `output.items[0].id`          | 배열의 특정 번째 요소          |
| 배열 전체    | `output.items[*].id`          | 배열의 모든 요소 중 하나라도 일치   |

지원하지 않는 문법 — 임의 깊이 탐색(`..a`), 객체 와일드카드(`.*`), 키 일부 와일드카드(`a_*`). 지원하지 않는 문법을 입력하면 조회가 오류로 거부됩니다.

metadata 컬럼은 문자열 맵이라 경로의 첫 세그먼트가 반드시 맵 키(멤버 접근)여야 합니다. 맵 값이 JSON 문자열이면 그 안쪽 경로까지 이어서 지정할 수 있습니다.

### 필터 간편 선택

키를 외워 쓰기 어려우므로, 「사용자 지정」을 선택하면 검색창 옆에 **\[필터 간편 선택]** 버튼이 나타납니다.

* 모달을 열면 **현재 화면에 걸린 검색·필터와 무관하게** 최신순 로그를 한 건씩 불러와 `input` · `output` · `metadata`를 JSON 트리로 보여 줍니다.
* **화면에서 고른 기간도 미리보기에는 적용되지 않습니다.** 모달을 열어 둔 채 기간을 바꿔도 미리보기 내용은 바뀌지 않습니다.
* `<` `>` 버튼이나 번호 직접 입력으로 로그를 넘겨 봅니다.
* 트리에서 **필드를 클릭하면 그 경로와 값이 키·값 칸에 자동으로 채워지고 즉시 검색이 실행됩니다.** 연산자는 그때 선택돼 있던 값이 유지됩니다.
* 값이 JSON 문자열이거나 스트리밍 응답이면 자동으로 해석해 하위 트리로 펼쳐 보여 줍니다.

<figure><img src="https://1274363562-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJuB29xjw7zmR91VXmqf%2Fuploads%2Fj4BBaq8rkxdSSy7I60oK%2F03_field_preview_modal.png?alt=media&amp;token=bfd8117d-17dd-4421-bd58-9ddf982e061d" alt=""><figcaption></figcaption></figure>

### 알아 둘 점

* 잘못된 입력은 조용히 무시하지 않고 **오류로 거부**합니다. 이용 로그는 감사 목적 화면이라, 필터가 걸리지 않은 전체 목록을 "조건에 맞는 기록이 없다"로 오해하면 그대로 사고가 되기 때문입니다.
* **CSV 다운로드에는 「사용자 지정」 필터가 반영되지 않습니다.** 다운로드는 기간 기준으로만 내려받으므로, 화면에서 필터를 걸어 둔 상태로 받아도 전체 데이터가 내려옵니다.

<figure><img src="https://1274363562-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJuB29xjw7zmR91VXmqf%2Fuploads%2Fxa4Wpqsn3u0vbnNSrBhu%2F04_filtered_result.png?alt=media&amp;token=f9ddbbd4-4ce0-42bf-aa71-bf4e71385f80" alt=""><figcaption></figcaption></figure>

### 자주 마주치는 안내 문구

| 상황            | 문구                                          |
| ------------- | ------------------------------------------- |
| 키에 컬럼 구분이 없음  | 이용 로그 사용자 지정 필터 key 는 '<컬럼>.<경로>' 형식이어야 합니다 |
| 키 또는 값이 비어 있음 | 이용 로그 사용자 지정 필터는 key·value 가 모두 필요합니다       |
| 지원하지 않는 컬럼    | 지원하지 않는 컬럼입니다 (input/output/metadata 만 지원)  |
| 지원하지 않는 연산자   | 지원하지 않는 연산자입니다 (eq/ne 만 지원)                 |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://genos-docs.gitbook.io/default/v1.9.4/common-features/usage-log-custom-filter.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.