Jejak

Trackio traces menangkap permintaan pengguna, respons asisten, dan operasi yang menghasilkannya. Buka halaman Traces di dasbor untuk mencari permintaan, memeriksa operasi model dan alat, serta melihat total latensi, token, biaya, dan status.

Catat percakapan

Lewatkan Trace ke trackio.log() dengan pesan bergaya OpenAI:

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

Pesan dapat mencakup tool_calls dan hasil tool. Ketika sebuah trace tidak memiliki span eksplisit, dashboard memasangkan panggilan dan hasil tersebut menjadi operasi tool untuk memudahkan inspeksi.

Tambahkan span eksekusi

Gunakan spans ketika Anda membutuhkan waktu, hierarki, penggunaan model, biaya, atau status operasi. Setiap span adalah kamus. Field minimal adalah id, name, dan 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",
        },
    ],
)

Bidang span yang didukung:

Latensi trace adalah waktu nyata (wall-clock) dari awal span terawal hingga akhir span terakhir; jika tidak ada span yang membawa end_time, maka duration_ms tunggal terpanjang digunakan sebagai gantinya. Total token dan biaya menjumlahkan nilai pada span individual, sehingga usage dan cost_usd harus menggambarkan operasi lokal, bukan agregat dari parent — parent yang mengulang total anak-anaknya akan menyebabkan penghitungan ganda. Trackio tidak memelihara katalog harga model; instrumetasi harus menyediakan biaya aktual.

Sebuah span dilaporkan sebagai gagal ketika status-nya adalah error atau failed, atau ketika span tersebut membawa error. Untuk span yang diturunkan dari pesan, hasil tool menandai operasinya sebagai gagal ketika pesan mengatur is_error, error, atau status error; hasil tool bergaya OpenAI tidak membawa sinyal keberhasilan, sehingga operasi tersebut dibiarkan tanpa status alih-alih diasumsikan berhasil.

Periksa jejak dari CLI

Dasbor bukan satu-satunya cara untuk membaca kembali trace. CLI bekerja terhadap data lokal, atau terhadap Space dengan --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 menampilkan pohon eksekusi dengan latensi per-span, model, token, biaya, dan error. trackio get trace-summary mengelompokkan setiap span berdasarkan nama operasi dan melaporkan jumlah panggilan, error, latensi rata-rata dan terburuk, penggunaan token, serta biaya — berguna untuk menemukan operasi mana yang mendominasi pengeluaran atau paling sering gagal. Keduanya menerima --json.

Untuk hal lainnya, spans adalah kolom JSON, sehingga json_each dapat digunakan dengan 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"

Melihat jejak pada Hugging Face Hub

Setiap trace yang dicatat juga ditulis sebagai file sesi agen .jsonl, dalam format yang dirender oleh penampil trace agen Hub. Ketika Trackio berjalan di Space, bucket dipasang di /data, sehingga file-file ini tersimpan di bucket di bawah traces/{project}/{run}/{trace_id}.jsonl — buka salah satunya dari peramban file bucket untuk menelusuri percakapan, pemanggilan tool-nya, dan hasilnya.

Trackio mengeluarkan format sesi Pi (versi 3), yang didukung secara native oleh Hub. Hub juga mendokumentasikan Session Trace Simple Format, tetapi file yang ditulis ke spesifikasi tersebut saat ini tidak dirender oleh viewer.

File sesi adalah artefak render, bukan sumber kebenaran. Tabel traces tetap menjadi otoritatif, dan semua hal lain di halaman ini — pencarian, pohon span, trace-summary, SQL langsung — membaca darinya. Yang dibawa oleh file sesi adalah percakapan linear, diperkaya dari span dengan detail yang dapat ditampilkan oleh viewer:

Penggunaan token dipasangkan dengan gilasan asisten yang memproduksinya, bukan diulang di setiap gilasan, sehingga penampil tidak menghitungnya dua kali. Hirarki span, duration_ms, metadata per-span, dan kind dari span non-tool tidak memiliki tempat dalam format dan tetap berada di SQLite.

File sesi berada di samping prefiks trackio/, bukan di dalamnya, sehingga perintah CLI trackio yang menyinkronkan bucket ke bawah tidak menarik salinan kedua dari setiap trace. Atur TRACKIO_TRACE_SESSIONS_DIR untuk menuliskannya ke lokasi lain.

Metadata tingkat trace

Spans adalah sumber yang lebih disukai untuk latensi, biaya, dan status. Ketika sebuah trace tidak memiliki spans, atau spans-nya tidak menyertakan nilai-nilai tersebut, dashboard akan kembali ke kunci metadata ini:

Cari

Pencarian trace mencocokkan konten pesan, metadata trace, serta id, name, kind, model, status, error, dan metadata dari setiap span. Payload input dan output span tidak diindeks: mereka secara rutin mengulang seluruh percakapan untuk setiap generasi, sehingga mengindeksnya akan melipatgandakan ukuran trace yang disimpan dengan nilai pencarian yang sedikit.

Nilai media Trackio bersarang dalam pesan, metadata, input span, atau output span disimpan bersama trace, dan gambar dirender secara inline di inspector.