SDK로 트레이스 조회하기

런(LangSmith 트레이스의 스팬 데이터)을 조회하는 권장 방법은 SDK의 list_runs 메서드 또는 API의 /runs/query 엔드포인트를 사용하는 것이에요. LangSmith는 런(스팬) 데이터 형식에 명시된 간단한 형식으로 트레이스를 저장해요.

이 페이지는 다음을 다룹니다:

필터 인자 사용: SDK 파라미터를 사용한 키워드 기반 필터링.
필터 쿼리 언어 사용: LangSmith의 필터 구문을 사용한 복잡한 쿼리.
하위 럔 프레디킷으로 트레이스 트리 조회: 서버 측 축소와 로컬 하위 럔 탐색 결합.
속도 제한: 테넌트별 제한 및 이를 지키기 위한 모범 사례.

참고: 대량의 트레이스를 내보내려면 대규모 데이터 볼륨을 더 잘 처리하고 자동 재시도와 파티션 병렬화를 지원하는 Bulk Data Export 기능을 사용할 것을 권장해요.

출처: 문서

본문

필터 인자 사용

간단한 쿼리의 경우 쿼리 구문에 의존할 필요가 없어요. 필터 인자 참조에 명시된 필터 인자를 사용할 수 있어요.

경고: 사전 요구사항 — 아래 코드 스니펫을 실행하기 전에 클라이언트를 초기화하세요.

```python Python from langsmith import Client

client = Client()


```typescript TypeScript
import { Client, Run } from "langsmith";

const client = new Client();

import com.langchain.smith.client.LangsmithClient;
import com.langchain.smith.client.okhttp.LangsmithOkHttpClient;

LangsmithClient client = LangsmithOkHttpClient.fromEnv();

다음은 키워드 인자를 사용해 럔을 나열하는 몇 가지 방법의 예시예요:

프로젝트의 모든 럔 나열

```python Python project_runs = client.list_runs(project_name="") ```

// Download runs in a project
const projectRuns: Run[] = [];
for await (const run of client.listRuns({
  projectName: "<your_project>",
})) {
  projectRuns.push(run);
};

import com.langchain.smith.models.runs.RunQueryParams;

RunQueryParams projectRuns = RunQueryParams.builder()
    .addSession("<your_project>")
    .build();

지난 24시간 내 LLM 및 채팅 럔 나열

```python Python todays_llm_runs = client.list_runs( project_name="", start_time=datetime.now() - timedelta(days=1), run_type="llm", ) ```

const todaysLlmRuns: Run[] = [];
for await (const run of client.listRuns({
  projectName: "<your_project>",
  startTime: new Date(Date.now() - 1000 * 60 * 60 * 24),
  runType: "llm",
})) {
  todaysLlmRuns.push(run);
};

OffsetDateTime now = OffsetDateTime.now();
OffsetDateTime twentyFourHoursAgo = now.minus(24, ChronoUnit.HOURS);

RunQueryParams todaysLlmRuns = RunQueryParams.builder()
    .runType(RunQueryParams.RunType.LLM)
    .startTime(twentyFourHoursAgo)
    .addSession("<your_project>")
    .limit(50L)
    .build();

프로젝트의 루트 럔 나열

루트 럔은 부모가 없는 럔이에요. 이들은 is_root에 대해 True 값을 갖습니다. 이를 사용해 루트 럔을 필터링할 수 있어요.

```python Python root_runs = client.list_runs( project_name="", is_root=True ) ```

const rootRuns: Run[] = [];
for await (const run of client.listRuns({
  projectName: "<your_project>",
  isRoot: 1,
})) {
  rootRuns.push(run);
};

import com.langchain.smith.models.runs.RunQueryParams;

RunQueryParams rootRuns = RunQueryParams.builder()
    .addSession("<your_project>")
    .isRoot(true)
    .build();

오류가 없는 럔 나열

```python Python correct_runs = client.list_runs(project_name="", error=False) ```

const correctRuns: Run[] = [];
for await (const run of client.listRuns({
  projectName: "<your_project>",
  error: false,
})) {
  correctRuns.push(run);
};

import com.langchain.smith.models.runs.RunQueryParams;

RunQueryParams noErrorRuns = RunQueryParams.builder()
    .addSession("<your_project>")
    .error(false)
    .build();

럔 ID로 럔 나열

경고: 다른 인자 무시 — 위 방식대로 럔 ID 목록을 제공하면 project_name, run_type 등 다른 모든 필터링 인자를 무시하고 주어진 ID와 일치하는 럔을 직접 반환해요.

런 ID 목록이 있으면 직접 나열할 수 있어요:

```python Python run_ids = ['a36092d2-4ad5-4fb4-9c0d-0dba9a2ed836','9398e6be-964f-4aa4-8ae9-ad78cd4b7074'] selected_runs = client.list_runs(id=run_ids) ```

const runIds = [
  "a36092d2-4ad5-4fb4-9c0d-0dba9a2ed836",
  "9398e6be-964f-4aa4-8ae9-ad78cd4b7074",
];
const selectedRuns: Run[] = [];
for await (const run of client.listRuns({
  id: runIds,
})) {
  selectedRuns.push(run);
};

import com.langchain.smith.models.runs.RunQueryParams;

RunQueryParams runIdsRuns = RunQueryParams.builder()
    .addSession("<your_project>")
    .id(runIds)
    .build();

ID로 단일 럔 가져오기

ID로 단일 럔(트레이스)을 가져오려면 read_run 메서드를 사용해요. 특정 트레이스 ID를 가지고 있고(예: https://smith.langchain.com/public/<trace-id>/r 같은 LangSmith 공유 링크에서) 전체 데이터를 검색해야 할 때 유용해요.

```python Python run_id = "a36092d2-4ad5-4fb4-9c0d-0dba9a2ed836" run = client.read_run(run_id)

Access run data

print(run.inputs) print(run.outputs) print(run.name)


```typescript TypeScript
const runId = "a36092d2-4ad5-4fb4-9c0d-0dba9a2ed836";
const run = await client.readRun(runId);

// Access run data
console.log(run.inputs);
console.log(run.outputs);
console.log(run.name);

import com.langchain.smith.models.runs.RunQueryParams;

RunQueryParams runIdRun = RunQueryParams.builder()
    .addSession("<your_project>")
    .addId(runId)
    .build();

팁: LangGraph로 로컬에서 트레이스 재생 — 체크포인팅과 함께 LangGraph를 사용한다면 LangSmith에서 트레이스를 가져와 디버깅을 위해 로컬에서 재생할 수 있어요. 체크포인트에서 실행을 재개하는 방법은 LangGraph의 타임 트래블 및 재생 문서를 참조해요.

필터 쿼리 언어 사용

더 복잡한 쿼리의 경우 필터 쿼리 언어를 사용할 수 있어요. 다음 예시는 가장 일반적인 패턴을 다루며, 전체 연산자 및 필드 참조(모든 비교자, 필터 가능한 필드, 값 형식 규칙, 빠른 참조 예시 표 포함)는 Trace query syntax: filter query language를 참조해요.

대화 스레드의 모든 루트 럔 나열

이것이 대화 스레드에서 럔을 가져오는 방법이에요. 스레드 설정에 대한 자세한 내용은 스레드 설정 how-to 가이드를 참조해요. 스레드는 공유 스레드 ID를 설정함으로써 그룹화돼요. LangSmith UI에서 session_id 또는 thread_id 메타데이터 키 중 하나를 사용할 수 있어요. 세션 ID는 트레이싱 프로젝트 ID라고도 알려져 있어요. 다음 쿼리는 둘 중 하나와 일치해요.

```python Python group_key = "" filter_string = f'and(in(metadata_key, ["session_id","thread_id"]), eq(metadata_value, "{group_key}"))' thread_runs = client.list_runs( project_name="", filter=filter_string, is_root=True ) ```

const groupKey = "<your_thread_id>";
const filterString = `and(in(metadata_key, ["session_id","thread_id"]), eq(metadata_value, "${groupKey}"))`;
const threadRuns: Run[] = [];
for await (const run of client.listRuns({
  projectName: "<your_project>",
  filter: filterString,
  isRoot: true
})) {
  threadRuns.push(run);
};

import com.langchain.smith.models.runs.RunQueryParams;

String groupKey = "<your_thread_id>";

String filterString = String.format(
    "and(in(metadata_key, [\"session_id\",\"thread_id\"]), eq(metadata_value, \"%s\"))",
    groupKey
);

RunQueryParams threadRuns = RunQueryParams.builder()
    .addSession("<your_project>")
    .filter(filterString)
    .build();

트레이스의 루트에 피드백 "user_score" 점수 1이 할당된 "extractor"라는 모든 럔 나열

```python Python client.list_runs( project_name="", filter='eq(name, "extractor")', trace_filter='and(eq(feedback_key, "user_score"), eq(feedback_score, 1))' ) ```

client.listRuns({
  projectName: "<your_project>",
  filter: 'eq(name, "extractor")',
  traceFilter: 'and(eq(feedback_key, "user_score"), eq(feedback_score, 1))'
})

RunQueryParams extractorRuns = RunQueryParams.builder()
    .addSession("<your_project>")
    .filter("eq(name, \"extractor\")")
    .traceFilter("and(eq(feedback_key, \"user_score\"), eq(feedback_score, 1))")
    .build();

점수가 4보다 큰 "star_rating" 키가 있는 럔 나열

```python Python client.list_runs( project_name="", filter='and(eq(feedback_key, "star_rating"), gt(feedback_score, 4))' ) ```

client.listRuns({
  projectName: "<your_project>",
  filter: 'and(eq(feedback_key, "star_rating"), gt(feedback_score, 4))'
})

RunQueryParams runs = RunQueryParams.builder()
    .addSession("<your_project>")
    .filter("and(eq(feedback_key, \"star_rating\"), gt(feedback_score, 4))")
    .build();

완료하는 데 5초보다 오래 걸린 럔 나열

```python Python client.list_runs(project_name="", filter='gt(latency, "5s")') ```

client.listRuns({projectName: "<your_project>", filter: 'gt(latency, "5s")'})

RunQueryParams runs = RunQueryParams.builder()
    .addSession("<your_project>")
    .filter("gt(latency, \"5s\")")
    .build();

상태가 "error"가 아닌 모든 럔 나열

```python Python client.list_runs(project_name="", filter='neq(status, "error")') ```

client.listRuns({projectName: "<your_project>", filter: 'neq(status, "error")'})

RunQueryParams runs = RunQueryParams.builder()
    .addSession("<your_project>")
    .filter("neq(status, \"error\")")
    .build();

start_time이 특정 타임스탬프보다 큰 모든 럔 나열

```python Python client.list_runs(project_name="", filter='gt(start_time, "2023-07-15T12:34:56Z")') ```

client.listRuns({projectName: "<your_project>", filter: 'gt(start_time, "2023-07-15T12:34:56Z")'})

RunQueryParams runs = RunQueryParams.builder()
    .addSession("<your_project>")
    .filter("gt(start_time, \"2023-07-15T12:34:56Z\")")
    .build();

"substring" 문자열을 포함하는 모든 럔 나열

```python Python client.list_runs(project_name="", filter='search("substring")') ```

client.listRuns({projectName: "<your_project>", filter: 'search("substring")'})

RunQueryParams runs = RunQueryParams.builder()
    .addSession("<your_project>")
    .filter("search(\"substring\")")
    .build();

하위 럔 프레디킷으로 트레이스 트리 조회

트레이스 트리의 하위 럔에 대한 속성을 기반으로 럔을 조회하는 것도 가능해요. 파이프라인에서 특정 하위 럔이 존재하는지를 검색하고 싶을 때 유용해요. 예를 들어 특정 이름의 하위 럔이 있는 트레이스만 조회하거나, 특정 조건을 충족하는 하위 럔이 있는 트레이스의 루트 럔만 조회할 수 있어요. 이 접근 방식은 서버 측 필터링(트레이스/트리 기반)과 로컬 하위 럔 탐색을 결합해 필요한 정밀도를 제공해요.

예시: 특정 이름의 하위 럔을 포함하는 트레이스 조회

전체 트레이스 트리를 다운로드하지 않고 특정 하위 럔을 포함하는 트레이스를 찾으려면 filter(런 수준)와 trace_filter 또는 서버 측 하위 럔 프레디킷을 조합해 사용해요. 자세한 문법은 Trace query syntax 및 하위 럔 프레디킷을 참조해요.

속도 제한

LangSmith SDK와 API는 테넌트 및 엔드포인트별 소프트 및 하드 속도 제한을 적용해요. 런 조회를 대규모로 수행할 때는 다음을 권장해요:

페이지네이션을 사용해 요청당 반환되는 럔 수를 제한한다.
상한에 도달하지 않도록 백오프와 함께 지수 재시도 로직을 구현한다.
가능하면 Bulk Data Export를 사용해 자동 재시도와 파티션 병렬화를 활용한다.

구체적인 할당량과 헤더는 API 속도 제한 문서를 참조해요.

SDK로 트레이스 조회하기