İzler

Trackio izleri, bir kullanıcı isteğini, asistan yanıtını ve bu yanıtı üreten işlemleri yakalar. İstekleri aramak, model ve araç işlemlerini incelemek ile gecikme, token, maliyet ve durum toplamlarını görmek için panoda Traces sayfasını açın.

Bir sohbeti kaydet

OpenAI tarzı mesajlarla trackio.log() fonksiyonuna Trace iletin:

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()

Mesajlar tool_calls ve tool sonuçlarını içerebilir. Bir izde açık aralıklar (spans) yoksa, gösterge paneli bu çağrıları ve sonuçları daha kolay inceleme için araç işlemleri olarak eşleştirir.

Çalışma aralıkları ekleyin

Zamanlamalar, hiyerarşi, model kullanımı, maliyet veya işlem durumu gerektiğinde spans kullanın. Her span bir sözlüktür. Minimal alanlar id, name ve kind'dir:

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",
        },
    ],
)

Desteklenen alanlar:

Trace gecikmesi, en erken span başlangıcından en geç span sonuna kadar geçen duvar saati süresidir; hiçbir span end_time taşımıyorsa bunun yerine en uzun tekil duration_ms kullanılır. Token ve maliyet toplamları, bireysel spanlardaki değerleri toplar; bu nedenle usage ve cost_usd, üst bir toplam yerine yerel işlemi açıklamalıdır — çocuklarının toplamlarını tekrar eden bir üst, çift saymaya yol açar. Trackio bir model fiyatlandırma kataloğu sürdürmez; enstrümantasyon gerçek maliyeti sağlamalıdır.

Bir span, status değeri error veya failed olduğunda ya da bir error taşıdığında başarısız olarak raporlanır. Mesajlardan türetilen spanlar için, bir araç sonucu, mesaj is_error, error veya bir hata status ayarladığında ilgili işlemi başarısız olarak işaretler; OpenAI tarzı araç sonuçlarında başarı sinyali bulunmadığından, bu işlemler başarılı varsayılmak yerine durum bilgisi olmadan bırakılır.

CLI'den izleri incele

Panel, izleri geri okumanın tek yolu değildir. CLI, yerel verilerle veya --space ile bir Space üzerinde çalışır:

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, span başına gecikme, model, token, maliyet ve hataları içeren yürütme ağacını yazdırır. trackio get trace-summary, tüm span'leri işlem adına göre gruplandırır ve çağrıları, hataları, ortalama ve en kötü durum gecikmesini, token kullanımını ve maliyeti raporlar — hangi işlemin harcamayı domine ettiğini veya en sık başarısız olduğunu bulmak için kullanışlıdır. İkisi de --json parametresini kabul eder.

Diğer her şey için, spans bir JSON sütunudur, bu nedenle json_each, trackio query project ile çalışır:

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 üzerinde izleri görüntüleme

Kaydedilen her iz, Hub’ın iz görüntüleyicisinin işlediği biçimde bir ajan oturumu .jsonl dosyası olarak da yazılır. Trackio bir Space üzerinde çalıştığında, varlık kovası /data konumuna bağlanır; bu nedenle bu dosyalar kovada traces/{project}/{run}/{trace_id}.jsonl altında yer alır — sohbeti, araç çağrılarını ve sonuçlarını adım adım incelemek için kovadaki dosya gezgini üzerinden birini açın.

Trackio, Hub tarafından yerel olarak desteklenen Pi oturum biçimini (sürüm 3) yazar. Hub ayrıca Session Trace Simple Format’ı da belgelemektedir ancak bu spesifikasyona göre yazılan dosyalar şu anda görüntüleyici tarafından işlenmemektedir.

Oturum dosyaları bir görüntüleme çıktısıdır, asla tek doğruluk kaynağı değildir. traces tablosu yetkilidir ve bu sayfadaki her şey — arama, span ağacı, trace-summary, doğrudan SQL — bu tablodan okur. Oturum dosyasının taşıdığı şey, görüntüleyicinin gösterebileceği ayrıntılarla spanlardan zenginleştirilmiş doğrusal konuşmadır:

Token kullanımı, onu üreten asistan turuyla eşleştirilir ve her turda tekrarlanmaz; böylece görüntüleyici çift sayım yapmaz. Span hiyerarşisi, duration_ms, span başına metadata ve araç dışı spanların kind değeri biçimde yeri yoktur ve SQLite'ta kalır.

Oturum dosyaları trackio/ önekinin içinde değil, yanında yer alır; bu nedenle bir kovayı aşağı senkronize eden trackio CLI komutları, her izlemenin ikinci bir kopyasını çekmez. Bunları başka bir yere yazmak için TRACKIO_TRACE_SESSIONS_DIR değerini ayarlayın.

İz düzeyi meta verileri

Spans, gecikme, maliyet ve durum için tercih edilen kaynaktır. Bir izde span yoksa veya span'ları bu değerleri içermiyorsa, panel bu metadata anahtarlarına geri döner:

Ara

Arama, mesaj içeriğini, iz meta verilerini ve her span’ın id, name, kind, model, status, error ve metadata alanlarını eşleştirir. Span input ve output yükleri indekslenmez: her üretim için tüm sohbeti tekrarladıkları için, indekslenmeleri depolanan iz boyutunu az bir arama değeri karşılığında katlayarak artırır.

Mesajlarda, metadata'da, span girdisinde veya span çıktısında yer alan iç içe geçmiş Trackio medya değerleri izleme (trace) ile birlikte saklanır ve görüntüler denetleyicide (inspector) satır içi olarak gösterilir.