Bir kullanıcı, aracının dün öğleden sonra "garip bir şey yaptığını" bildiriyor. Logları açtığınızda şunları buluyorsunuz:
INFO agent run started
INFO calling tool: updateOrder
INFO tool returned 200
INFO agent run completed
Aracı, updateOrder'ı çağırdı. Hangi argümanlarla, hangi siparişe karşı, neden bu aracı seçtiğini veya ne döndüğünü bilmiyorsunuz. Kaydettiğiniz her ölçüye göre çalıştırma başarılı oldu ve aldığı tek bir kararı bile yeniden yapılandıramıyorsunuz.
Aracı sistemleri, ancak sonradan anlamlı gelen şekillerde başarısız olur; bu da logun nihai ürün olduğu anlamına gelir. Bu kılavuz, her araç çağrısında neleri kaydetmeniz gerektiğini, bir model kararını ürettiği HTTP isteğiyle nasıl ilişkilendireceğinizi, neleri düzenleyeceğinizi ve izleri testlere nasıl dönüştüreceğinizi kapsar. API gözlemlenebilirliği hakkındaki yazımız hizmet tarafını; bu yazı ise onun üzerinde yer alan aracı katmanını kapsar.
Bir izleme verisine sahip olduğunuzda Apidog faydalıdır, çünkü kötü bir çağrıyı anlamanın en hızlı yolu, aynı uç noktaya karşı tekrar oynatmak ve ne olduğunu izlemektir.
Üç katman, tek bir iz
Bir aracı üç seviyede olay üretir ve çoğu ekip yalnızca orta seviyeyi loglar.
Mantık katmanı, modelin karar verdiği yerdir. Bağlamda ne vardı, hangi araçlar sunuldu, hangisini seçti ve hangi argümanlarla.
Araç katmanı sizin yürütücünüzdür. Argümanları doğrular, politikayı uygular, çağrıyı bir HTTP isteğiyle eşleştirir ve sonucu işler.
HTTP katmanı kablo tarafıdır. Metot, URL, başlıklar, gövde, durum, gecikme.
Hata ayıklama neredeyse her zaman katmanları aşar. "Aracı yanlış müşteri kimliği gönderdi" sadece HTTP katmanında görünen bir mantık problemidir. "API, boş bir gövdeyle 200 döndürdü" ise üç adım sonra garip bir mantık olarak ortaya çıkan bir HTTP problemidir. Eğer üç katman ortak bir tanımlayıcıyla birbirine bağlı değilse, zaman damgasına göre ilişkilendirme yapmaya mahkum olursunuz, ki bu da iki çalıştırmanın çakıştığı anda işe yaramaz hale gelir.
Bu nedenle ilk kural: her aracı çalıştırması için bir izleme kimliği (trace ID), her araç çağrısı için bir kapsam kimliği (span ID) ve her ikisinin de her katmandaki her kayda damgalanması. OpenTelemetry izleri tam olarak bu şekli zaten modeller ve verilerinizin taşınabilir olması için nitelikleri adlandırmak için büyüyen bir GenAI semantik konvansiyonları seti bulunmaktadır.
Her araç çağrısında neler kaydedilmeli
Gerçek soruları yanıtlayan bir kayıt kabaca şu şekle sahiptir:
{
"trace_id": "run_01J8ZK3M2Q",
"span_id": "call_004",
"parent_span_id": "call_003",
"timestamp": "2026-08-26T14:03:11.482Z",
"agent": "billing",
"step": 4,
"tool_name": "refundOrder",
"tool_args": { "orderId": "ord_92", "amount": 1200, "reason": "duplicate" },
"tools_available": ["getOrder", "listOrders", "refundOrder", "voidInvoice"],
"http": {
"method": "POST",
"url": "/v1/orders/ord_92/refund",
"request_body_hash": "sha256:1f4c...",
"status": 200,
"duration_ms": 412,
"retry_count": 1,
"idempotency_key": "9f2b7c14-6d3a-4b18"
},
"outcome": "success",
"tokens": { "prompt": 8420, "completion": 96 },
"policy": { "approval_required": true, "approved_by": "user_31", "dry_run": false }
}
Beş alan orantısız derecede iş yapar.
tool_args en sık eksik olanıdır ve her zaman istediğinizdir. Modelin ürettiği argümanları, yürütücünüz onları normalleştirmeden önce kaydedin. Bir aracı yanlış kimlik gönderdiğinde, bu burada görünür olur.
tools_available seçimi açıklar. Model garip bir araç seçtiyse, ilk soru başka nelerin seçeneği olduğudur. Bu alan birkaç bayt maliyetindedir ve anında yanıt verir.
retry_count, "API yavaştı" ile "API iki kez başarısız oldu ve sonra çalıştı" durumlarını ayırır. Olmadan, üç deneme tek bir çağrı gibi görünür.
outcome açık bir enum olmalıdır, bir durum kodundan çıkarılan bir şey değil. success (başarılı), failed (başarısız), timed_out (zaman aşımına uğradı), blocked_by_policy (politika tarafından engellendi), rejected_by_human (insan tarafından reddedildi). Son ikisi önemlidir çünkü engellenen bir çağrı bir hata değil, çalışan bir koruyucudur ve bunları karıştırmak başarısızlık oranınızı bozar.
policy sizin denetim kaydınızdır. Biri yıkıcı bir eylemin onaylanıp onaylanmadığını sorduğunda, bu cevaptır. Bu, yapay zeka aracı koruyucuları hakkındaki yazımızda açıklanan uygulama ile eşleşir.
Sadece eylemi değil, kararı da kaydedin
En zor aracı hataları seçimlerdir, bu yüzden onları yeniden yapılandırmaya yetecek kadar kayıt tutun.
Çalıştırma için kullanılan araç tanımlarını veya bunların bir özetini (hash) saklayın. Seçim doğruluğu değiştiğinde, ilk şüpheli birinin düzenlediği bir açıklamadır ve bir özet, iyi bir çalıştırma ile kötü bir çalıştırma arasında araç setinin değişip değişmediğini size anında söyler. Aracılar için API araç şemaları tasarlama hakkındaki yazımız, bu metnin davranışı neden bu kadar etkilediğini kapsar.
Modeli ve ayarlarını kaydedin. Model kimliği, sıcaklık ve istem sürümü çalıştırma kaydında yer almalıdır. Model sürümleri arasında davranış değişir ve bu alan olmadan kendi kodunuzu incelemekle bir gün geçirirsiniz.
Modelin ne gördüğünü veya en azından boyutunu kaydedin. Tam bir istem dökümü depolamak maliyetlidir ve genellikle hassas bilgiler içerir. Bir jeton sayısı artı bir özet, çoğu teşhis değerini verir: istemi normal boyutunun iki katı olan bir çalıştırma, olmaması gereken bir şeyin eklendiği bir çalıştırmadır.
Kırpmadan önce ham araç sonucunu kaydedin. Yürütücünüz yanıtları modele teslim etmeden önce küçültüyorsa, araç yanıtlarını bağlam penceresinden uzak tutma hakkındaki yazımızda olduğu gibi, tam yükü izleme verisinde saklayın. Aksi takdirde, verilerin eksik mi olduğunu yoksa sizin mi düşürdüğünüzü anlayamazsınız.
Depolamadan önce redakte edin
Aracı izlemeleri, hem isteği hem de etrafındaki mantığı içerdikleri için alışılmadık derecede tehlikelidir ve istemler kişisel veri toplama eğilimindedir.
Dört kural bunu yönetilebilir kılar.
Asla kimlik bilgilerini saklamayın. Authorization, API anahtarları, çerezler ve imzalı URL'leri çıkarın. Kimlik bilgisinin değerini değil, bir anahtar kimliği gibi tanımlayıcısını kaydedin. Aracılar için en az ayrıcalıklı API anahtarları hakkındaki yazımız, neden bu tanımlayıcıyı istediğinizi kapsar: hangi aracının eylem yaptığını söyler.
Redakteyi sorguda değil, sınırda yapın. Okuma sırasında filtreleme, sırrın diske yazıldığı, çoğaltıldığı ve yedeklendiği anlamına gelir. Kayıt işlemden ayrılmadan önce loglama ara katman yazılımında redakte edin.
Saklayamadığınız gövdeleri özetleyin (hash). Bir istek gövdesi özeti, iki çağrının aynı olduğunu kanıtlamanıza yine de olanak tanır ki bu, yükü saklamadan çift kayıt araştırmaları için ihtiyacınız olanın çoğudur.
Saklama süresini hassasiyete göre ayarlayın. Bir hafta boyunca tam izlemeler, bir yıl boyunca redakte edilmiş özetler. Çoğu hata ayıklama birkaç gün içinde gerçekleşir; çoğu denetim sorusu ise birkaç ay içinde gelir.
İzlemeleri testlere dönüştürün
İyi izlemenin getirisi sadece daha hızlı hata ayıklama değildir. Aynı zamanda gerçekçi test senaryoları kaynağıdır.
Her başarısız çalıştırma bir senaryodur. Kötü bir izden araç çağrılarını alın, bunları API'nize karşı yeniden oynatın ve bir yeniden üretiminizi (reprodüksiyon) elde edin. Düzeltme yapıldığında, yeniden oynatmayı bir regresyon testi olarak saklayın. Apidog'da başarısız isteği kaydedilmiş bir durum olarak yeniden oluşturabilir, düzeltilmiş davranışı doğrulayabilir ve bunu CI'da çalıştırabilirsiniz, bu da tek seferlik bir olayın kalıcı bir kapsama dönüşmesini sağlar.
İzlemeler ayrıca neyi taklit edeceğinizi de söyler. Aracınızın en çok çağırdığı uç noktalar ve gerçekten karşılaştığı hata durumları, tahminden ziyade doğrudan verilerden gelir. Üretim yerine taklit API'lere karşı aracılar çalıştırma hakkındaki yazımızı takip ederek taklitleri bunların etrafında oluşturun.
Ve başka türlü gözden kaçıracağınız yavaş kaymayı yüzeye çıkarırlar. Haftalık olarak birkaç sayıyı takip edin: araç seçim dağılımı, uç nokta başına yeniden deneme oranı, tamamlanan görev başına çağrı sayısı ve politika tarafından engellenen çalıştırmaların yüzdesi. Bunlardan herhangi birindeki bir değişim, bir olay haline gelmeden önce bir sinyaldir. API sözleşme testi kılavuzumuzdaki gibi sözleşme düzeyindeki kontroller, genellikle buna neden olan yukarı yönlü değişikliği yakalar.
İzlemenin hayatta kalması gereken üç araştırma
"Aracı yanlış müşteriyi ücretlendirdi." Modelin ürettiği argümanlara, çözülen URL'ye ve ondan önceki adıma ihtiyacınız var. On vakadan dokuzunda kimlik, birden fazla eşleşme döndüren ve modelin ilkini seçtiği daha önceki bir araç sonucundan gelmiştir. İzleme, önceki sonucu, belirsizliği ve seçimi gösterir. tool_args olmadan, bir 200 ve çok mutsuz bir müşteriniz olur.
"Salı günü çalışmayı durdurdu." İyi bir çalıştırma ile kötü bir çalıştırmayı alan bazında karşılaştırın. Model Kimliği, araç seti özeti (hash), istem sürümü, ortalama yanıt boyutu. Bir şeyler değişmiştir ve genellikle bu dördünden biri bunu adlandırır. Bu yüzden çalıştırma kaydı sadece olayları değil, yapılandırmayı da taşır: bir fark (diff) ancak her iki taraf da aynı alanları kaydettiğinde mümkündür.
"Bunu kim onayladı?" Politika bloğu tüm cevaptır ve sonradan yeniden yapılandırılmak yerine kararın verildiği anda yazılmalıdır. approval_required (onay gerekli), approved_by (onaylayan) ve bir zaman damgası gergin bir konuşmayı bir aramaya dönüştürür.
Bunların ortak noktalarına dikkat edin. Hiçbiri "araç 200 döndürdü" ile yanıtlanmaz. Üçü de yazılması neredeyse hiçbir şeye mal olmayan ve sonradan kurtarılması imkansız olan alanlarla yanıtlanır.
Örnekleme ve asla örneklenmemesi gerekenler
Her çalıştırmada tam doğrulukta izleme, hacimli olduğunda pahalı hale gelir, bu yüzden ekipler örnekleme yapar. Dikkatli örnekleme yapın, çünkü aracı trafiği tekdüze değildir.
Her zaman başarısız olan her çalıştırmayı, bir politika bloğuna takılan her çalıştırmayı ve bir yazma işlemi içeren her çalıştırmayı saklayın. Bunlar, herkesin hakkında soru soracağı çalıştırmalardır. Başarılı, salt okunur çalıştırmaları örnekleyin, çünkü bunlar hacmin çoğunu oluşturur ve bireysel olarak en az ilgi çekicidirler, ancak yine de temel çizgilerinizi hesaplamak için yeterince sahip olmak istersiniz.
Google'ın SRE kitabının izleme bölümü, neden hacim yerine sinyal için örnekleme yapmanız gerektiğinin hala en açık ifadesidir ve bu mantık doğrudan uygulanabilir.
Yükleri attığınızda bile çalıştırma kaydını saklayın. Araç adları, sonuçlar ve süreler içeren iskelet bir izleme küçüktür ve yine de yukarıdaki dört metrikle desteklenir. Pahalı kısımlar gövdeler ve istemlerdir ve ilk atabileceğiniz kısımlar bunlardır.
Kuyruk örneklemesi hakkında bir uyarı: bir çalıştırma tamamlandıktan sonra neyi saklayacağınıza karar verirseniz, kararın sonucun bilinmesinden sonra verildiğinden emin olun. Üçüncü adımda iyi görünen ve dokuzuncu adımda başarısız olan bir çalıştırma tamamen saklanmalıdır, bu da ilerlerken atmak yerine arabelleğe almak anlamına gelir.
İzlemenin nerede yaşaması gerektiği
Yukarıdakilerin hepsi, depolama alanına sahip olduğunuzu varsayar. Aracı kendi API'lerinizi çağıran kendi hizmetiniz olduğunda bu doğru bir varsayımdır. Aracılar geliştirici makinelerinde kod çalıştırma ortamları olduğunda ise kötü bir yaklaşımdır, çünkü izleme o zaman onu çalıştıran terminalde yaşar.
Sharkly diğer bir yaklaşımı benimser: çalıştırma izi, aracının atandığı Göreve eklenir. Çalıştırma geçmişi, çalıştırma günlüğü ve sonuç, hedefin, durumun ve bir insanın çalışmayı incelediği yorum dizisinin yanında yer alır. Pratik farkı, geri almadır. "Aracı neden bunu yaptı" sorusu, makineyi, oturumu ve geri kaydırma geçmişini bulmak yerine görevi açarak yanıtladığınız bir soru haline gelir.
Burada açıklanan izlemeyi ve çalışma zamanını da değiştirmez; Claude Code ve Codex hala işi yapar. Değiştirdiği şey, aracı dağıttığınız bir hizmet değilken kaydın nereye gittiğidir.
Dört sayıyı izleyin
İzlemeler yalnızca birileri bakarsa işe yarar. Bu dört sayı kontrol panelinde yerini kazanır.
Tamamlanan görev başına çağrı sayısı. En net verimlilik ölçüsü. Eğer artarsa, aracı daha fazla keşfediyor demektir, genellikle bir açıklama kötüleştiği veya bir uç nokta başarısız olmaya başladığı için.
Uç noktaya göre yeniden deneme oranı. En az güvenilir bağımlılıklarınızı sıralar ve birinin ne zaman kötüleştiğini gösterir. Aracı hata kurtarma hakkındaki yazımız, bu listenin başındaki maddelerle ne yapmanız gerektiğini kapsar.
Politika tarafından engellenen oran. Düşük ve istikrarlı olmalıdır. Bir artış, ya aracının yapmaması gereken şeyler denediği ya da bir politikanın çok sıkı olduğu ve artık bir darboğaz haline geldiği anlamına gelir.
İlk araç çağrısına kadar geçen süre. Yavaş bir başlangıç genellikle şişmiş bir istem anlamına gelir ve istem boyutu, kimse büyütmeye karar vermeden büyüyen şeydir.
Kontrol listesi
- Her çalıştırma için bir izleme kimliği, her araç çağrısı için bir kapsam kimliği, her üç katmanda da damgalanmış.
- Model argümanları normalleştirmeden önce kaydedilmiş.
- Mevcut araç listesi her çağrıda kaydedilmiş.
- Sonuç, politika blokları dahil olmak üzere açık bir enum olarak kaydedilmiş.
- Yeniden deneme sayısı, çağrı sayısından ayrı.
- Model, sıcaklık, istem sürümü ve araç seti özeti (hash) çalıştırma kaydında.
- Ham araç sonuçları, modele verilen kırpılmış sürüm yerine depolanmış.
- Kimlik bilgileri ara katman yazılımında çıkarılmış, depolanamayan gövdeler özetlenmiş.
- Saklama süresi hassasiyete göre katmanlara ayrılmış.
- Başarısız izlemeler, tekrar oynatılabilir test durumlarına dönüştürülebilir.
Hedef basitçe ifade edilebilir: biri aracının neden böyle yaptığını sorduğunda, tahminden ziyade kayıtlardan yanıt verebilirsiniz. Bir izdeki çağrıları yeniden oynatmak ve çoğaltmaları test olarak saklamak için Apidog'u indirin.
Sıkça sorulan sorular
OpenTelemetry mi yoksa amaca özel bir aracı gözlemlenebilirlik aracı mı kullanmalıyım? İlişkilendirmeyi zaten hallettiği ve altyapınız muhtemelen bunu konuştuğu için taşıma ve izleme modeli için OpenTelemetry kullanın. Aracıya özel araçlar üzerine faydalı görünümler ekler; ancak alttaki veriler yine de taşınabilir olmalıdır.
Tam izlemenin depolama maliyeti ne kadardır? Katmanlara ayırırsanız, insanların beklediğinden daha az. Birkaç gün boyunca tam yükler ve daha uzun süreler için gövdesiz yapılandırılmış kayıtlar çoğu hacmi düşük tutar. İstem dökümleri pahalı kısımdır, bu nedenle varsayılan olarak bunları depolamak yerine özetleyin ve boyutlandırın.
Modelin muhakeme metnini kaydetmem gerekiyor mu? Genellikle hayır. Seçtiği araç, ürettiği argümanlar ve sahip olduğu seçenekler çoğu kararı açıklar. Bir sağlayıcı muhakeme içeriğini ifşa ediyorsa, bunu yalnızca başarısız çalıştırmalar için saklayın ve hassas olarak değerlendirin.
Birden çok aracı arasında nasıl izleme yaparım? Tüm görev için bir izleme kimliği tutun ve her aracıya kendi kapsamını verin, el değiştirme bir olay olarak kaydedilsin. Çoklu aracı el değiştirmesi hakkındaki yazımız, bu el değiştirme kaydında nelerin yer alması gerektiğini kapsar.
Aracı bir müşterinin makinesinde çalışıyorsa ne olur? Yerel olarak günlüğe kaydedin, agresif bir şekilde redakte edin ve kullanıcı onay verene kadar yalnızca toplu metrikler gönderin. Araç adları, sonuçlar ve süreler genellikle cihazdan herhangi bir yük çıkışı olmadan filo düzeyinde izleme için yeterlidir.
İstek gövdesi özeti gerçekten faydalı mı? Evet, en yaygın sorular için. İki çağrının aynı olduğunu kanıtlar, bu da çoğu çift yazma araştırmasını yükün kendisini saklamadan çözer. Bunu, çifti önlemesi gereken idempotency anahtarları ile eşleştirin.