트레이스

Trackio trace는 사용자 요청, 어시스턴트 응답, 그리고 해당 응답을 생성한 작업을 캡처합니다. 대시보드의 Traces 페이지를 열면 요청을 검색하고 모델 및 도구 작업을 검사하며 지연 시간, 토큰, 비용, 상태 합계를 확인할 수 있습니다.

대화 기록

OpenAI 스타일의 메시지와 함께 Trace를 trackio.log()에 전달합니다:

import trackio

trackio.init(project="research-agent")
trackio.log(
    {
        "trace": trackio.Trace(
            messages=[
                {"role": "user", "content": "Find agent training datasets."},
                {"role": "assistant", "content": "Here are three datasets..."},
            ],
            metadata={"session_id": "session-123", "environment": "production"},
        )
    }
)
trackio.finish()

Messages에는 tool_calls와 tool 결과가 포함될 수 있습니다. trace에 명시적인 spans가 없는 경우, 대시보드는 이러한 호출과 결과를 tool operations으로 짝지어 더 쉽게 검사할 수 있도록 합니다.

실행 스팬 추가

타이밍, 계층 구조, 모델 사용량, 비용 또는 작업 상태가 필요할 때 spans를 사용합니다. 각 span은 딕셔너리입니다. 최소 필드는 id, name, kind입니다:

trackio.Trace(
    messages=messages,
    spans=[
        {
            "id": "research",
            "name": "answer-research-question",
            "kind": "span",
            "start_time": "2026-08-19T12:00:00Z",
            "end_time": "2026-08-19T12:00:03Z",
            "status": "success",
        },
        {
            "id": "generation-1",
            "parent_id": "research",
            "name": "provider-request",
            "kind": "generation",
            "start_time": "2026-08-19T12:00:00Z",
            "end_time": "2026-08-19T12:00:01.2Z",
            "model": "my-model",
            "input": {"messages": messages},
            "output": {"text": "I will search for datasets."},
            "usage": {"input_tokens": 8439, "output_tokens": 188},
            "cost_usd": 0.0042,
            "status": "success",
        },
        {
            "id": "tool-1",
            "parent_id": "research",
            "name": "hf search",
            "kind": "tool",
            "start_time": "2026-08-19T12:00:01.3Z",
            "end_time": "2026-08-19T12:00:02Z",
            "input": {"query": "agent training datasets"},
            "output": {"datasets": ["example/dataset"]},
            "status": "success",
        },
    ],
)

지원되는 span 필드:

Trace latency는 가장 이른 span 시작 시점부터 가장 늦은 span 종료 시점까지의 wall-clock time입니다. end_time을 가진 span이 없으면, 가장 긴 단일 duration_ms 값이 대신 사용됩니다. Token 및 비용 합계는 개별 span의 값을 합산하므로, usage와 cost_usd는 상위 집계가 아닌 해당 로컬 작업을 설명해야 합니다. 자식 span의 합계를 반복하여 보고하는 상위 span은 이중 계산을 유발합니다. Trackio는 모델 가격 카탈로그를 유지하지 않으므로, instrumentation이 실제 비용을 제공해야 합니다.

status가 error 또는 failed인 경우, 또는 error를 포함하는 경우 해당 span은 실패로 보고됩니다. 메시지에서 파생된 span의 경우, 메시지가 is_error, error, 또는 오류 status를 설정하면 도구 결과가 해당 작업을 실패로 표시합니다. OpenAI 스타일의 도구 결과에는 성공 신호가 없으므로, 이러한 작업은 성공했다고 가정하지 않고 상태 없이 남겨둡니다.

CLI에서 트레이스 검사

대시보드는 트레이스를 다시 읽는 유일한 방법이 아닙니다. CLI는 로컬 데이터 또는 --space를 사용한 Space에 대해 작동합니다:

trackio list traces --project research-agent
trackio list traces --project research-agent --search "rate limit"
trackio get trace --project research-agent --trace-id <id>
trackio get trace-summary --project research-agent

trackio get trace는 스팬별 지연 시간, 모델, 토큰, 비용, 오류를 포함하여 실행 트리를 출력합니다. trackio get trace-summary는 모든 스팬을 작업 이름별로 그룹화하여 호출 횟수, 오류, 평균 및 최악의 지연 시간, 토큰 사용량, 비용을 보고합니다. 이는 비용이 가장 많이 드는 작업이나 가장 자주 실패하는 작업을 찾는 데 유용합니다. 두 명령 모두 --json을 지원합니다.

그 외의 경우, spans은 JSON 컬럼이므로 json_each가 trackio query project와 함께 작동합니다:

trackio query project --project research-agent --sql "
SELECT json_extract(s.value, '\$.name') AS operation,
       SUM(COALESCE(json_extract(s.value, '\$.usage.input_tokens'), 0)) AS input_tokens
FROM traces, json_each(traces.spans) AS s
GROUP BY operation ORDER BY input_tokens DESC"

Hugging Face Hub에서 트레이스 보기

기록된 모든 trace는 Hub의 agent trace viewer가 렌더링하는 형식으로 agent 세션 .jsonl 파일로도 기록됩니다. Trackio가 Space에서 실행되는 경우, 버킷은 /data에 마운트되므로 이러한 파일은 버킷의 traces/{project}/{run}/{trace_id}.jsonl 아래에 저장됩니다. 버킷의 파일 브라우저에서 파일을 열면 대화, 도구 호출 및 그 결과를 단계별로 살펴볼 수 있습니다.

Trackio는 Pi의 세션 형식(버전 3)을 출력하며, Hub는 이를 네이티브로 지원합니다. Hub에는 Session Trace Simple Format에 대한 문서도 있지만, 해당 스펙으로 작성된 파일은 현재 뷰어에서 렌더링되지 않습니다.

세션 파일은 렌더링 산출물일 뿐이며, 절대 신뢰할 수 있는 출처가 아닙니다. traces 테이블이 항상 권위 있는 출처로 유지되며, 이 페이지의 모든 다른 요소 — 검색, 스팬 트리, trace-summary, 직접 SQL — 는 이 테이블에서 데이터를 읽습니다. 세션 파일이 담고 있는 것은 스팬에서 뷰어가 표시할 수 있는 세부 정보로 풍부하게 보강된 선형 대화입니다:

Token 사용량은 해당 토큰을 생성한 어시스턴트 턴과 짝을 이루어 기록되며 모든 턴에 반복되지 않으므로 뷰어에서 이중 계산을 방지합니다. Span 계층 구조, duration_ms, span별 metadata, 그리고 non-tool span의 kind는 포맷에 포함되지 않으며 SQLite에 유지됩니다.

Session 파일은 trackio/ 접두사 안에 있는 것이 아니라 그 옆에 위치하므로, 버킷을 로컬로 동기화하는 trackio CLI 명령은 모든 trace의 두 번째 사본을 가져오지 않습니다. TRACKIO_TRACE_SESSIONS_DIR를 설정하여 다른 위치에 저장할 수 있습니다.

트레이스 수준 메타데이터

Spans은 지연 시간, 비용, 상태에 대한 권장 소스입니다. Trace에 spans이 없거나, 해당 spans에서 이러한 값이 누락된 경우 대시보드는 metadata 키로 대체합니다:

검색

Trace 검색은 메시지 콘텐츠, trace 메타데이터, 각 span의 id, name, kind, model, status, error, metadata를 대상으로 합니다. Span의 input 및 output 페이로드는 인덱싱되지 않습니다. 모든 generation마다 전체 대화 내용이 반복적으로 포함되므로, 이를 인덱싱하면 검색 가치에 비해 저장된 trace 크기가 크게 증가하기 때문입니다.

메시지, 메타데이터, span input 또는 span output에 포함된 중첩된 Trackio 미디어 값은 trace와 함께 저장되며, 이미지는 inspector에 인라인으로 렌더링됩니다.