# İ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`](./api#trace) iletin:

```python
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 yoksa, gösterge paneli bu çağrıları ve sonuçları, inceleme kolaylığı sağlamak amacıyla 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:

```python
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:

| Alan | Açıklama |
|---|---|
| `id` | İz içinde benzersiz tanımlayıcı |
| `parent_id` | İsteğe bağlı üst span kimliği; yürütme ağacını oluşturur |
| `name` | Denetleyicide görünen işlem adı |
| `kind` | `span`, `generation` veya `tool` |
| `start_time`, `end_time` | Gecikmeyi türetmek için kullanılan ISO-8601 zaman damgaları |
| `duration_ms` | Zaman damgaları kullanılamadığında isteğe bağlı süre |
| `status` | Genellikle `success` veya `error` |
| `error` | Yapılandırılmış veya metinsel hata ayrıntıları |
| `input`, `output` | Herhangi bir JSON-serileştirilebilir işlem yükü |
| `model` | Bir üretim için model tanımlayıcısı |
| `usage` | `input_tokens`, `output_tokens` ve isteğe bağlı `total_tokens` |
| `cost_usd` | Bu işlemin ABD doları cinsinden maliyeti |
| `metadata` | Ek operasyon meta verisi |

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 öğe, ç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ı başarı sinyali taşımaz, bu nedenle 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:

```bash
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 — harcamanın hangi işlem tarafından baskınlaştığını veya en sık hangi işlemin 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`](./cli_commands) ile çalışır:

```bash
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'un iz görüntüleyicisinin işlediği biçimde bir `.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'un yerel olarak desteklediği [Pi oturum biçimini](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/session-format.md) (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:

| Aralıktan | Oturumda şu şekilde görünür |
|---|---|
| `model` bir üretim | a `model_change` girdisi |
| `usage`, `cost_usd` | `usage` asistanın ürettiği turda |
| Bir araçta `status`, `error` | Araç sonucundaki `isError` |
| Bir araçta `input`, `output` | `messages` içermeyen izler için `toolCall` argümanları ve sonucu |

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 sayede bir kovayı aşağı senkronize eden `trackio` CLI komutları her izden ikinci bir kopya çekmez. Bunları başka bir yere yazmak için `TRACKIO_TRACE_SESSIONS_DIR` değişkenini 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üşer:

| Anahtar | Kullanım alanı |
|---|---|
| `status` | Bir span hata raporlamadığı sürece izleme durumu |
| `duration_ms`, `latency_ms` | Gecikmeyi izleme |
| `cost_usd` | Maliyet izleme, hiçbir span maliyet raporlamadığında |

## 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: bu alanlar her üretimde tüm sohbeti tekrarladığı için, indekslenmeleri depolanan iz boyutunu çok az 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.