Ajan Gözlemlenebilirliği: Hook'lar, Alloy ve Grafana

Ajan sistemleri tuhaf şekillerde başarısız olur.

Bazen sorun modeldir. Bazen sorun araçtır. Bazen MCP sunucunuz gayet iyidir, ama ajan yanlış uzmanı seçmiştir, ya da oturumun yarısını beklemediğiniz kabuk (shell) işleriyle geçirmiştir, ya da dışarıdan üretken görünen bir döngüde sessizce maliyet yakmıştır.

Farkı göremiyorsanız, gerçekten bir ajan sistemi işletmiyorsunuzdur. Tahmin yürütüyorsunuzdur.

Bu yüzden kendi iş akışımız için bir gözlemlenebilirlik yığını kurduk: Claude Code, Codex, Claude hook olayları, Codex notify olayları, yerel OpenTelemetry, Grafana Alloy ve diğer uçta Grafana Cloud.

İlginç kısım “bir gösterge paneli yaptık” değil. İlginç kısım, tek bir akışın bize tüm resmi vermediği için telemetriyi iki farklı akışa bölmek zorunda kalmamız.

Sorun: Ajan Telemetrisi Parçalanmış Durumda

Modern kodlama ajanları zaten biraz telemetri yayınlıyor. Bu yardımcı oluyor, ama yeterli değil.

Yerel OTEL şu tür soruları yanıtlamakta iyidir:

• Kaç istek yaptık?
• Bir oturuma ne kadar maliyet oluştu?
• Span’ler ve trace’ler nerede?
• Gecikme sıçradı mı?

Şu tür soruları yanıtlamakta çok daha kötüdür:

• Ajan hangi MCP sunucusuna dayandı?
• Bu hata Bash’da mı, yerleşik bir dosya aracında mı, yoksa bir MCP çağrısında mı oldu?
• Hangi beceri (skill) gerçekten etkinleşti?
• Hangi alt ajan türü görevlendirildi?
• Oturum yararlı bir iş mi yapıyordu, yoksa sadece debelenip mi duruyordu?

Bu ikinci soru sınıfı, trace’lerden çok hook’lara yakın yaşar.

Ama tersi de doğrudur: en önemli performans sorularından bazıları hook’lardan çok trace’lere yakın yaşar.

Gecikmenin gerçekte nerede biriktiğini, hangi span’lerin yavaş olduğunu ya da oturumun zamanı model çağrılarında mı yoksa araç yürütmede mi harcadığını bilmek istiyorsanız, semantik olayların yanı sıra trace verisine de ihtiyacınız var.

Sonunda Vardığımız Mimari

İki telemetri yolunu yan yana çalıştırıyoruz.

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

Bu ayrım kasıtlıdır.

Ayrıca asimetriktir. Claude Code bize çok daha zengin bir yaşam döngüsü hook yüzeyi sağlar. Codex bize yerel OTEL artı bir notify yüzeyi sağlar; bu yüzden iki çalışma zamanının aynı kontrolleri sunduğunu varsaymak yerine, daha ince tur tamamlama olaylarını aynı günlük şemasına normalize ederiz.

Yerel OTEL bize temel akışı verir: çalışma zamanının kendisinden gelen günlükler ve trace’ler, artı çalışma zamanının gerçekten yaydığı metrikler.

Hook ve notify olayları bize semantik katmanı verir: PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated gibi şeyler ve ajan davranışını hata ayıklarken gerçekten önemsediğimiz sınıflandırılmış meta veriler. Claude Code burada daha zengin olay akışına katkıda bulunur. Codex daha ince ama yine de yararlı, normalize edilmiş bir akışa katkıda bulunur.

Hook’lar Neden Var Olsun Ki

Hook hattımız, olaylar Loki’ye ulaşmadan önce onları zenginleştirir.

Sadece “bir araç çalıştı” demek yerine, olayı şu tür alanlara sınıflandırırız:

• tool_type: builtin, mcp, skill, agent, bash
• mcp_server: hangi MCP arka ucunun çağrıyı işlediği
• bash_cli: kabuk komut ailesi
• subagent_type: ne tür bir uzmanın görevlendirildiği
• agent_tool: kaynağın Claude Code mu yoksa Codex mi olduğu

Bu, operasyonel olarak önemli sorular sorabileceğimiz anlamına gelir:

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

Bunlar gösterişlik alanlar değildir. “Ajan yavaş hissettirdi” ile “ajan son on dakikayı yüksek araç başarısızlık oranına sahip, kabuk ağırlıklı git işlemlerinde geçirdi” arasındaki farktır.

Olduğundan daha garip görünen bir uygulama ayrıntısı: paylaşılan Loki akışı, olay Codex’ten gelse bile etiket olarak hâlâ service_name="claude-code-hooks"’yi kullanır. Çalışma zamanları arasındaki gerçek ayrım agent_tool üzerinde gerçekleşir.

Alloy Neden Ortada Duruyor

Grafana Alloy bu kurulumda sadece bir yönlendirici değildir. Politika sınırıdır.

Claude Code ve Codex’ten gelen yerel OTEL akışını localhost:4318 üzerindeki yerel bir Alloy proxy’sine yönlendiririz, ardından Alloy’un yükü Grafana Cloud’a iletmeden önce temizlemesine izin veririz.

Bu önemlidir çünkü ham ajan telemetrisi, analiz için yararlı ama indekslenmiş etiketler olarak berbat olan yüksek kardinaliteli alanlarla doludur:

• session_id
• prompt_id
• token sayıları
• süreler
• araç parametresi blob’ları

Her şeyi indekslerseniz, bir etiket patlaması ve kötü bir gün yaşarsınız.

Bu yüzden Alloy bizim için üç şey yapar:

1. Çok küçük bir düşük kardinaliteli etiket kümesini indekslenmiş tutar.
2. Gürültülü ama yararlı alanları yapılandırılmış meta veriye taşır.
3. Saf gürültüyü tamamen düşürür.

Önemli fikir basittir: daha fazla gözlemle, daha azını indeksle.

Hook Akışı Neden Alloy’u Atlıyor

Hook akışı zaten Loki için şekillendirilmiştir.

send_event.py bir olayı gönderdiğinde, hangi alanların etiket muamelesini hak ettiğine ve hangilerinin yapılandırılmış JSON gövdesine ait olduğuna zaten karar vermişizdir. Bu akış, Alloy’dan tekrar geçmek yerine doğrudan Grafana Cloud’un OTLP ağ geçidine gider.

Yani sistemin net bir iş bölümü vardır:

• Alloy ham yerel OTEL akışını evcilleştirir.
• Hook zenginleştirmesi semantik olayları sorgulanabilir kılar.

Bu, her şeyi tek bir yoldan geçirmeye zorlamaktan daha basit bir mimari sağlar.

Gösterge Paneli Gerçekte Neyi Gösteriyor

Aşağıdaki ekran görüntüsü, ajan iş akışımızın arkasındaki gözlemlenebilirlik gösterge panellerinden birine ait. Bu bir kıyaslama değildir ve sayılar sadece belirli bir andaki bir dilimdir. Önemli olan verinin biçimidir: etkinlik akışı, araç çağrıları, başarısızlıklar, istemler ve ajana, yerleşik araçlara, MCP kullanımına, kabuk komutlarına ve becerilere göre dökümler.

Yararlı olan kısım, bu gösterge panelinin ajan telemetrisinin geri kalanıyla aynı Grafana yığınında yaşamasıdır. Kaynak ajana ve araç ailesine göre filtreleyebilir ve her sistem için farklı bir gözlemlenebilirlik hikayesi icat etmeden çalışma zamanları arasında bakabiliriz.

Trace’ler Neden İlk Göründüğünden Daha Önemli

Günlükler bize ne kategoride bir iş olduğunu söyler. Trace’ler bize işin zaman içinde nasıl geliştiğini söyler.

Bu ayrım ajan sistemlerinde önemlidir çünkü “yavaş” yararlı olamayacak kadar kabadır.

Bir trace, sıkıntının şuradan gelip gelmediğini söyleyebilir:

• model gecikmesi
• araç yürütme süresi
• tekrarlanan yeniden denemeler
• özellikle maliyetli tek bir MCP etkileşimi
• tek başına zararsız görünen küçük işlemlerin uzun bir kuyruğu

Pratikte hook akışını ve Tempo trace’lerini birlikte kullanıyoruz.

• Hook günlükleri şunu yanıtlar: ne tür bir şey oldu?
• Trace’ler şunu yanıtlar: zaman nereye gitti?

Bu kombinasyon, gözlemlenebilirliği bir gösterge panelinden bir açıklamaya dönüştüren şeydir.

Codex Nereye Oturuyor

Codex aynı yığının bir parçasıdır, ama Claude Code ile özdeş değildir.

Codex için iki parçayı bağlarız:

• Codex’ten Alloy’a yerel OTEL
• Tur tamamlamalarını hook olayları için kullandığımız aynı Loki şemasına eşleyen codex_notify.py’e bir notify webhook’u

Bu bize aynı günlük akışı içinde agent_tool="codex-cli" gibi birleşik bir filtre sağlar.

Dürüst çekince şu: Codex’in notify yükü şu anda Claude Code’un hook yükünden daha incedir, çünkü aynı türde bir entegrasyon yüzeyi değildir. Bugünkü kurulumumuzda, Codex tur tamamlamaları paylaşılan şemaya normalize edilebilir, ama araç araç zengin çıkarım hâlâ notify köprüsünden çok yerel OTEL akışında daha iyidir.

Bu, yazıyı yazmaktan kaçınmak için bir sebep değildir. Yazının asıl noktası tam da budur. Gerçek gözlemlenebilirlik sistemleri kusurlu sinyallerden bir araya getirilir.

MCP Üzerinden Grafana Oyunu Değiştiriyor

Daha büyük değişim, Grafana’nın sadece insanların bir tarayıcıda ziyaret ettiği bir yer olmamasıdır.

Bu depoda Grafana’yı MCP üzerinden de sunuyoruz. Bu, bir ajanın, bir insanın önce gösterge panellerini manuel olarak incelemesini beklemek yerine Loki’yi, Prometheus’u ve Tempo’yu doğrudan sorgulayabileceği anlamına gelir.

Bu, gözlemlenebilirliği iş akışına aktif bir girdiye dönüştürür.

Bir ajan şunu sorabilir:

• Son bir saatte hangi araç aileleri en çok başarısız oldu?
• Bir oturuma hangi MCP sunucusu hakim oldu?
• Son değişiklikler araç başarısızlıklarını azalttı mı, yoksa işi aynı hatalarla daha kabuk ağırlıklı yollara mı taşıdı?
• Hangi trace’ler en yüksek gecikmeyi veya tekrarlanan yeniden denemeleri gösteriyor?

Buna sahip olduğunuzda, kendi kendini geliştiren bir döngüye çok yaklaşmışsınızdır.

Gösterge Panelinden Geri Bildirim Döngüsüne

En ilginç bulduğumuz kısım bu.

Gözlemlenebilirlik yığını ajan katmanından sorgulanabilir hale geldiğinde, telemetri pasif bir raporlama yüzeyi olmaktan çıkıp bir kontrol sinyaline dönüşür.

Döngü şöyle görünür:

1. Ajan etkinliği trace’ler, metrikler ve zenginleştirilmiş hook günlükleri yayınlar.
2. Grafana, kanıtı Loki, Tempo ve metriklerin bulunduğu yerde Prometheus’ta saklar.
3. Ajanlar bu kanıtı Grafana MCP üzerinden sorgular.
4. Sistem, önlenebilir hatalar üretmeye devam eden kötü araç karışımını, kırılgan becerileri, zayıf yönlendirmeyi veya kabuk ağırlıklı iş akışlarını belirler.
5. Ajanlar veya operatörler istemleri, ajan yapılandırmalarını, beceri açıklamalarını, yönlendirme kurallarını veya araç erişimini ayarlar.
6. Bir sonraki oturum yeni bir telemetri biçimi üretir ve döngü tekrarlanır.

“İlginç gösterge paneli”nden “ölçülebilir iyileştirme sistemi”ne geçişin yolu budur.

Amaç bir araç kategorisini maksimize etmek değildir. Amaç, gerçekte yapılan iş için CLI, yerleşik araçlar, MCP çağrıları ve becerilerin doğru karışımına ulaşmaktır.

Bu Bize Neyi Yanıtlamamızı Sağlıyor

Her iki çalışma zamanı da aynı Grafana yığınına indiğinde, operasyonel sorulara çok daha hızlı yanıt verebiliyoruz:

• Başarısızlıklar tek bir araç ailesinde mi yoğunlaşıyor?
• Kabuk ağırlıklı iş akışları, daha üst seviyeli bir aracın var olması gereken yerlerde önlenebilir hatalar mı yaratıyor?
• İş yükünü hangi MCP sunucuları taşıyor?
• Anlamlı ilerleme üretmeyen ajan etkinliği için ödeme mi yapıyoruz?
• Bir oturum model, araçlar veya orkestrasyon katmanı yüzünden mi sağlıksız?

Bu, “ajan meşguldü”nün size neredeyse hiçbir şey söylemediği çok ajanlı iş akışlarında özellikle yararlıdır.

Bir uzman sürekli görevlendiriliyor ve yüksek başarısızlık oranları üretiyorsa, bu bir yönlendirme veya istem şekillendirme sorunudur.

Bir MCP sunucusu tüm çağrılara hakimse, bu iyi bir mimari olabilir ya da geri kalan her şeyin ölü ağırlık olduğunun bir işareti olabilir.

Maliyet yüksek kalırken araç başarısızlıkları sıçrıyorsa, bir kalite sorununuz değil, operasyonel bir sorununuz var demektir.

Kabuk işi, daha üst seviyeli bir aracın var olması gereken yerlerde tahmin edilebilir, önlenebilir şekillerde başarısız olmaya devam ediyorsa, bu bir ürün sinyalidir.

Bir beceri sürekli etkinleşiyor ama sonuçları iyileştirmiyorsa, bu bir istem veya yönlendirme sinyalidir.

Gerçek Ders

Buradaki daha derin ders, ajan gözlemlenebilirliğinin hem çalışma zamanı telemetrisine hem de iş akışı telemetrisine ihtiyaç duymasıdır.

Çalışma zamanı telemetrisi size sistemin ne yaptığını söyler.

İş akışı telemetrisi size ajanın ne yaptığını düşündüğünü söyler.

İkisine de ihtiyacımız var.

Sadece trace’leri ve sayaçları tutarsanız, semantik katmanı kaçırırsınız. Sadece hook olaylarını tutarsanız, gecikmeyi, span’leri ve daha geniş çalışma zamanı resmini kaçırırsınız.

Ve ikisini de tutar ama asla ajan katmanına geri beslemezseniz, izleme yaparsınız, adaptasyon değil.

Kombinasyon, sistemi işletmek için yeterince açıklanabilir ve iyileştirmek için yeterince ayarlanabilir kılan şeydir.

Hâlâ Kusurlu Olan Neler

Hâlâ pürüzler var.

• Her hook olayı istediğimiz süre ve token verisini içermiyor.
• En iyi zamanlama görünümlerinin bazıları hâlâ hook günlüklerinden değil, Tempo trace’lerinden geliyor.
• Codex bugün, zenginleştirilmiş olay akışında Claude Code’dan daha az semantik zenginliğe sahip.
• Gösterge paneli ekran görüntüsü, cilalanmış bir pazarlama eseri değil, canlı bir operasyon yüzeyidir.

Bu son nokta kasıtlıdır. Ajan sistemlerinin sihirli bir şekilde kendi kendini açıkladığını iddia etmek yerine, gerçek gösterge panelini göstermeyi tercih ederiz.

Bunun Maguyva İçin Neden Önemli Olduğu

Maguyva, ajanlara daha iyi kod zekâsı vermekle ilgilidir. Ama ajanlar gerçekten yararlı bir iş yapmaya başladığında, hemen yeni bir gereksinim ortaya çıkar: nasıl davrandıklarını görmeniz gerekir.

Arama kalitesi, yönlendirme kalitesi, araç seçimi ve bağlam verimliliğinin hepsi gözlemlenebilir sorunlar haline gelir.

Bu yüzden bunun yazmaya değer olduğunu düşünüyoruz. Geleceğin ajan yığını sadece istemler ve araçlar değildir. İstemler, araçlar ve tüm sistemin çalışıp çalışmadığını size söyleyen enstrümantasyon katmanıdır.

Ciddi ajan iş akışları inşa ediyorsanız, gözlemlenebilirlik isteğe bağlı bir altyapı değildir. Ürünün bir parçasıdır.