LLM Gözlemlenebilirlikte Sessions, Traces ve Spans: Bunlardan Biri Yapısal Seviye Değil

LLM Gözlemlenebilirlikte Sessions, Traces ve Spans: Bunlardan Biri Yapısal Seviye Değil

Datadog'un terimler sayfası, LLM observability sessions traces spans sorgusunda Google'da 1 numaralı sonuç, bu üç kelimeden yalnızca ikisini tanımlıyor. Üçünü değil. Eksik olan gen_ai.conversation.id ile eşleşiyor; eksik olmasının nedeni ise OpenTelemetry şartnamesinin onu hiçbir zaman yapısal bir seviye olarak tanımlamaması. Gözlemlenebilirliğin kendisine neden ihtiyaç duyduğunuza dair gerekçeye ihtiyacınız varsa buradan başlayın. Bu yazı, o yazının bittiği yerden devam ediyor: veri modeli.

Öne Çıkanlar

• Span'ler trace'lerin içine yuvalanır; trace'ler session'larda gruplanır. Yuvalanma en içten dışa doğrudur: önce span, sonra trace, sonra session.
• Span, süresi ölçülen tek bir işlemdir. Trace, uçtan uca tek bir istektir. Session, çok turlu tek bir konuşmadır.
• OpenTelemetry'nin GenAI sözleşmeleri span'leri ve gen_ai.conversation.id özniteliğini tanımlar. Bir session seviyesi tanımlamazlar.
• Trace ve span ID'leri context üzerinden otomatik yayılır. Session ID'si yayılmaz. Onu her turda siz ayarlarsınız.

Sessions, Traces ve Spans Bir Bakışta

LLM gözlemlenebilirlikte span, süresi ölçülen tek bir işlemdir (bir model çağrısı, bir retrieval adımı); trace, tek bir isteğin ürettiği span ağacıdır; session ise aynı konuşmadan gelen birçok trace'i gruplar. Yuvalanma içe doğrudur: span'ler trace'lerin içinde, trace'ler session'ların içinde. Üçüncü gruplama, göründüğü gibi olmayan gruplamadır.

Bu adet ve ömür rakamları, bir RAG sohbet botunda veya bir ajan döngüsünde bekleyeceğiniz tipik aralıklardır; kontrollü bir testten alınmış ölçümler değildir. Sizin rakamlarınız farklı olacaktır. Farklı olmayacak olan şu: Session satırı, şartnamede yapısal bir seviye olmayan satırdır ve "Sessions: Aracınızın Büyük Olasılıkla İcat Ettiği Seviye" bölümü bunu kanıtlar.

Span Nedir ve Span Kind Nedir?

Span; bir adı, bir başlangıç zaman damgası, bir bitiş zaman damgası, bir durum kodu ve bir anahtar-değer öznitelik kümesi bulunan, süresi ölçülen tek bir işlemdir. LLM tracing'de faydalı veri özniteliklerde yaşar: gen_ai.usage.input_tokens, gen_ai.usage.output_tokens ve gen_ai.request.model size işlemin maliyetini ve hangi modelin çalıştığını söyler.

Span tek bir işlemdir, tek bir fonksiyon çağrısı değil

Her span, ağacı kuran bir üst span ID'si işaretçisi taşır (kök span'de boştur). Öznitelik kümesi açıktır: ihtiyacınız olan bağlamı eklersiniz. OpenTelemetry GenAI span sözleşmeleri (durum: Development) her GenAI span'inde gen_ai.operation.name ve gen_ai.provider.name gerektirir ve yukarıdaki token kullanım özniteliklerini önerir.

Datadog'un terimler sayfasından pratik bir kural: LLM, Workflow ve Agent span'leri kök span görevi görebilir; Tool, Task, Embedding ve Retrieval span'leri göremez. Bu Datadog'un kuralıdır, evrensel bir kural değil; ancak bunu açıkça belirten tek sağlayıcıdır ve sizi üstü olmayan bir araç çağrısında başlayan bir trace kurmaktan kurtarır.

Span kind'ları: aynı fikir, beş farklı sözcük dağarcığı

Her aracın "bu span bir model çağrısıdır" ile "bu span bir retrieval'dır" demenin bir yoluna ihtiyacı vardır. Sadece kelime üzerinde anlaşamazlar:

OpenInference şartnamesi on tür listeler. Datadog yedi listeler. OTel üçüncü bir yol izler: GenAI öznitelik kayıt defteri, gen_ai.operation.name için 15 bilinen değer yayımlar (chat, create_agent, create_memory, create_memory_store, delete_memory, delete_memory_store, embeddings, execute_tool, generate_content, invoke_agent, invoke_workflow, plan, retrieval, search_memory, text_completion) ve bunlardan biri uygulanıyorsa o değerin MUTLAKA kullanılacağını belirtir; özel bir değer YALNIZCA hiçbiri uymadığında kullanılabilir. Yani bu yarı açık bir enum'dır, yokluğu değil. Üç liste, üç farklı uzunluk ve aralarında hiçbir hizalama yok. Bir araç seçiyorsanız, bu sözcük dağarcığı farkı özellik listesinden daha önemlidir; çünkü panolarınızın ve uyarı filtrelerinizin anahtarlanacağı şey budur.

Trace Nedir ve Ağaç Şekli Neden Önemlidir?

Trace, tek bir isteğin ürettiği span ağacıdır. Tepede bir kök span durur; diğer her span, üst-span-ID kenarları aracılığıyla onun altına asılır. Ağaç şekli işin tümüdür: düz bir log size bir şeyin yavaş olduğunu söyler, ama ağaç hangi adımın yavaş olduğunu ve hangi adımın hatalı çıktıyı ürettiğini söyler.

chat_request (root)                         2,340ms
├── retrieval                                 410ms
│   └── rerank                                 85ms
├── chat gpt-4o                             1,720ms
└── tool_call: search_calendar                190ms

Bu ağacı okuyun ve teşhis anında bellidir: Gecikmenin %74'ü model çağrısındaydı, retrieval'da değil. Beş zaman damgasından oluşan düz bir log size aynı toplamı verir ama hiçbir atıf vermez.

Bir ajan döngüsü bu ağacı, düz bir RAG isteğinden daha derin ve daha geniş yapar. Her araç çağrısı kendi alt ağacını doğurur; beş adımlı bir ajan turu, tek bir kök altında rahatlıkla 30'dan fazla span üretebilir. Bu normaldir ve aşağıdaki span granülaritesi sorusunun var olma nedeni budur.

Tracing ile logging arasındaki ayrım da burada önemlidir: logging olayları kaydeder, tracing nedenselliği kaydeder. Neyi loglayacağınıza karşın neyi trace edeceğinize hâlâ karar veriyorsanız, LLM loglama en iyi uygulamaları yazımız o çizgiyi çizer.

Sessions: Aracınızın Büyük Olasılıkla İcat Ettiği Seviye

Hayır. Session, OpenTelemetry GenAI sözleşmelerinde yapısal bir seviye değildir. Şartname, span'leri ve gen_ai.conversation.id özniteliğini tanımlar (koşullu gerekli, "kullanılabilir olduğunda", durum: Development); bu öznitelik, mesajları ilişkilendirmek için kullanılan bir konuşma veya thread'in benzersiz tanımlayıcısı olarak tanımlanır. Sağlayıcılar sonra bu özniteliğin üzerine kendi session nesnelerini inşa eder. Bu SERP'te başka hiç kimse şartname durumunu bu kadar açık belirtmez; işte burada.

Sonuç, bu yazının var olma nedeni olan cümledir:

Session bir gruplama anahtarıdır, bir üst span değildir. Bir trace ID'sinin yayıldığı şekilde yayılmaz; onu her turda kendiniz ayarlarsınız.

Bir turu kaçırırsanız o tur session'ın dışında kalır. Bunun için otomatik context yayılımı yoktur.

Bir session ne zaman başlar ve biter?

Sağlayıcı tanımlıdır. Bazı araçlar, yeni bir konuşma ID'si taşıyan ilk trace'te bir session açar ve hareketsizlik zaman aşımında kapatır (Langfuse varsayılan olarak yapılandırılabilir bir pencere kullanır). Diğerleri açık bir kapatma çağrısı gerektirir. Şartname yaşam döngüsü hakkında hiçbir şey söylemez; çünkü şartname bir session'ı bir nesne olarak modellemez.

Turlar arasında ne taşınır, ne taşınmaz?

Modelin context penceresi session değildir. Session, bağımsız trace'ler üzerinde bir gruplama anahtarıdır. Her tur kendi trace'ini, kendi kök span'ini, kendi token sayımlarını alır. Taşınan şey, her kök span'e bastığınız konuşma ID'si özniteliğidir. Taşınmayan şey: gecikme, token kullanımı, span yapısı. Bunlar trace'e özeldir.

Session seviyesindeki bir metrik neyi ölçer?

Tek bir trace'in ölçemeyeceği şeyleri: çözüm oranı (konuşma kullanıcının sorununu çözdü mü?), yanıta ulaşma turu (kullanıcı ihtiyacı olanı alana kadar kaç trace geçti?) ve terk edilmiş konuşmalar (kapanış sinyali olmayan session'lar). Session seviyesinde canlı trace'ler üzerinde eval çalıştırmak, tur tur bakıldığında iyi görünen çok turlu hataları yakalama biçiminizdir.

Kod, sağlayıcıdan bağımsız

Bu parçacık yalnızca kararlı OTel ilkellerini kullanır. Sağlayıcı SDK'sı yok. Tek bir tur için bir kök span, retrieval için bir alt span, model çağrısı için bir alt span oluşturur ve üç turu tek bir session'a yerleştirmek için gen_ai.conversation.id ayarlar:

from opentelemetry import trace

tracer = trace.get_tracer("my-llm-app")

SESSION_ID = "conv-8f3a2c"  # same value on every turn

def handle_turn(user_message: str):
    with tracer.start_as_current_span("chat_request") as root:
        # You set this. It does not propagate automatically.
        root.set_attribute("gen_ai.conversation.id", SESSION_ID)

        with tracer.start_as_current_span("retrieval") as ret:
            ret.set_attribute("gen_ai.operation.name", "retrieval")
            docs = retrieve(user_message)

        with tracer.start_as_current_span("chat gpt-4o") as llm:
            llm.set_attribute("gen_ai.operation.name", "chat")
            llm.set_attribute("gen_ai.provider.name", "openai")
            llm.set_attribute("gen_ai.request.model", "gpt-4o")
            response = call_model(user_message, docs)
            llm.set_attribute("gen_ai.usage.input_tokens", 1_204)
            llm.set_attribute("gen_ai.usage.output_tokens", 312)

    return response

handle_turn'ü aynı SESSION_ID ile üç kez çağırın ve bu özniteliği okuyan herhangi bir arka uçta üç trace'in tümü tek bir session altında gruplanır. ID'yi değiştirin ve yeni bir session başlatmış olursunuz. Tüm mekanizma budur.

Beş Sağlayıcının Dokümanını Yan Yana Okuduk. Anlaşamıyorlar.

2026-07-30'da Langfuse, LangSmith, OpenInference / Phoenix ve Datadog için güncel veri modeli dokümanlarını yan yana okuduk; buna OpenTelemetry GenAI span şartnamesi de dahil. Beşinden dördü aynı nesneye farklı bir şey diyor. Yalnızca biri session'ı bir öznitelik değil, birinci sınıf bir nesne olarak ele alıyor. Bu sorgu için Google'da 1 numaralı sonuç olan Datadog'un terimler sayfası, bir session'ı hiç tanımlamıyor.

İlk satıra dair bir kaynak notu: OpenInference'ın session.id'si, yukarıda bağlantısı verilen ve on span kind'ını kapsayan traces şartnamesinde yer almaz. Kardeş dosya olan OpenInference semantik sözleşmeler dosyasında bir session'ın benzersiz tanımlayıcısı olarak tanımlanır. İki dosya, tek şartname.

Sağlayıcılar arası karşılaştırmayı biz icat etmedik; FutureAGI de bir OTel-sağlayıcı tablosu yayımlıyor. Bizim iki eklememiz session satırı (FutureAGI onu atlar) ve aynı-kelime-farklı-anlam tuzağıdır: Langfuse'un "observation"ı ve LangSmith'in "run"ı, span ile aynı nesnedir; Datadog'un ve OpenInference'ın span kind'ları ise aynı fikir için farklı sözcük dağarcıklarıdır.

Langfuse ona observation der, LangSmith ona run der, Datadog ona span der. Aynı nesne, üç pano; migrate ettiğinizde kırılır.

Bu, migrate maliyetine dair bizim okumamızdır, bir sağlayıcı iddiası değil. Ama "observation" veya "run" üzerine anahtarlanmış kayıtlı filtrelerin, eval yapılandırmalarının ve uyarı kurallarının, araç değiştirdiğiniz gün çalışmayı bırakmasının nedeni budur. Bir alanı yeniden adlandırmıyorsunuz. Bir seviyeyi yeniden adlandırıyorsunuz. Bu iki spesifik aracı tartıyorsanız, Langfuse ve LangSmith karşılaştırmamız bu ayrışmayı daha derinlemesine ele alır.

Okuyucuların yığınlarında hâlihazırda Opik, PostHog, Sentry veya Weights & Biases da olabilir; Google bu dördünün tümünü llm tracing ile ilişkilendirir ve her biri bu kavramları biraz farklı haritalar. Doğru olanı mı seçiyorsunuz? Gözlemlenebilirlik platformu toplu değerlendirmemiz bu alanı kapsar.

Bir güncellik notu: GenAI sözleşmeleri, ana semantic-conventions deposundan çıkarak kendi depolarına taşındı. Eski opentelemetry.io/docs/specs/semconv/gen-ai/ yolu artık yalnızca bir işaretçi taşıyor.

Hangi ID Nereye Gider?

Bir trace ID tek bir isteği tanımlar ve context üzerinden otomatik yayılır. Bir span ID o trace içindeki tek bir işlemi tanımlar, bu da otomatiktir. Bir correlation ID (veya request ID), tracing başlamadan önce web katmanınızdan gelir ve insanların trace ID'siyle en sık karıştırdığı şeydir. Session ID'si ise aykırı olanıdır: onu her turda, manuel olarak, siz ayarlarsınız.

Pratik kural: gen_ai.conversation.id'yi her turdaki kök span'in bir özniteliği olarak ekleyin ve user ID'yi de yanına basın. Bir turu atlarsanız, session seviyesindeki metrikleriniz o turu sessizce kaybeder.

Cardinality konusunda bir uyarı: user ID'ler ve session ID'ler yüksek cardinality'li değerlerdir. Bu, arka ucunuzun indeksleme faturası için önemlidir; bu da bir sonraki bölümün sorunudur.

Bir Span Ne Kadar Granüler Olmalı?

İki başarısızlık modu, ikisi de yaygın:

Aşırı span'lama. Fonksiyon çağrısı başına bir span, size kimsenin okuyamayacağı 400 span'lik bir trace ve kimsenin onaylamadığı span başına bir fatura verir. Barındırılan arka uçlar (Datadog, Langfuse Cloud) span hacmine göre fiyatlandırır. Her string birleştirmesini enstrümante eden geveze bir ajan döngüsü, bir öğleden sonra ücretsiz katmanı tüketir.

Yetersiz span'lama. "Tüm zincir" için tek bir span, size yavaş olduğunu söyler ama nerede olduğunu söylemez. Sonunda print ifadelerini geri eklersiniz; bu da tracing'in yerini alması gereken şeydir.

Pratik kural (ve bu bir pratik kuraldır, bir ölçüm değil): bir kararın veya harici bir çağrının gerçekleştiği sınırları span'leyin.

• Retrieval adımı: span'leyin.
• Rerank çağrısı: span'leyin.
• Her model çağrısı: span'leyin.
• Her araç çağrısı: span'leyin.
• Her guardrail kontrolü: span'leyin.
• Saf süreç içi dönüşümler (string biçimlendirme, JSON ayrıştırma, prompt montajı): kendi span'leri değil, üst span'in öznitelikleri.

Cardinality, örnekleme ve saklama üzerine:

• Yüksek cardinality'li öznitelikler (user ID'ler, tam prompt'lar) depolama maliyetlerini şişirir. Onları örnekleyin veya kısaltın.
• Çoğu arka uç, trace seviyesinde örneklemenize izin verir. Hata trace'lerinin %100'ünü tutun; mutlu yolu örnekleyin.
• Saklama pencereleri değişir: ücretsiz katmanlarda 7 gün, ücretlide 30–90 gün. Veriye ihtiyaç duymadan önce karar verin.

Span hacminin ve span başına fiyatlandırmanın arkasındaki gerçek maliyet modeli için LLM maliyet izleme rehberimize bakın. Burada yeniden kurmayacağız.

Techsy Buna Nasıl Yaklaşıyor

Müşteri ajan çalışmalarında üç kuralı standart hâle getiriyoruz:

1. Tur başına bir trace. Ajan dahili olarak döngüye girse bile iki kullanıcı turunu asla tek bir trace'te birleştirmeyin.
2. Her kök span'e basılan, uygulama kodunda ayarlanan, asla yayıldığı varsayılmayan bir session ID'si.
3. Span kind'larını küçük sabit bir kümede tutmak (retrieval, inference, tool, guardrail); böylece panolar bir sağlayıcı değişikliğinden sağ çıkar.

Üçüncü kural, ekiplerin atladığı kuraldır ve bir migrate'i kurtaran kuraldır. Span sözcük dağarcığınız tek bir sağlayıcının enum'una bağlıysa, her uyarı ve kayıtlı görünüm, araç değiştirdiğiniz gün kırılır.

Bir ajan sistemi kuruyorsanız ve tracing mimarisi için ikinci bir görüş istiyorsanız, ücretsiz bir danışmanlık alın.

Sıkça Sorulan Sorular

Dağıtık tracing'de span nedir?

Span, süresi ölçülen tek bir iş birimidir: bir adı, bir başlangıç zamanı, bir bitiş zamanı, bir durumu ve bir öznitelik kümesi vardır. Span'ler, üst-span-ID referansları aracılığıyla birbirine bağlanarak bir ağaç oluşturur. LLM uygulamalarında bir span genellikle tek bir model çağrısını, tek bir retrieval'ı veya tek bir araç çağrısını sarar.

Datadog'da span nedir?

Datadog'un LLM Observability'sinde span, aynı süresi ölçülen işlemdir; ancak Datadog bir span kind taksonomisi ekler: LLM, Workflow, Agent, Tool, Task, Embedding ve Retrieval. Yalnızca LLM, Workflow ve Agent kind'ları kök span görevi görebilir. Taksonomi Datadog'a özgüdür; OpenTelemetry standardının parçası değildir.

Gözlemlenebilirliğin dört sütunu nedir?

Dört sütun log'lar, metrikler, trace'ler ve (kimin çerçevesine bağlı olarak) profil'ler veya event'lerdir. Trace'ler, bu yazının içinde yaşadığı sütundur. LLM durumu bir kıvrım ekler: token kullanımı ve model kimliği, ayrı metrik akışları değil, trace span'leri üzerindeki özniteliklerdir; bu da iki sütun olacak şeyi tek bir sorguda birleştirir.

Gözlemlenebilirlik için dört altın sinyal nedir?

Gecikme, trafik, hatalar ve doygunluk. LLM sistemleri için gecikme, ilk token'a kadar geçen süre ve toplam üretim süresi demektir; trafik, model başına saniyedeki istek demektir; hatalar, başarısız span'ler (durum kodu ERROR) demektir; doygunluk, token bütçesinin tükenmesi veya kuyruk derinliği demektir. Sinyaller aynıdır; birimler farklıdır.

Session, OpenTelemetry şartnamesinin bir parçası mı?

Yapısal bir seviye olarak değil. OTel GenAI span sözleşmeleri, gen_ai.conversation.id'yi bir konuşma veya thread'deki mesajları ilişkilendirmek için koşullu gerekli bir öznitelik ("kullanılabilir olduğunda") olarak tanımlar. Span'ler üzerinde durur. Langfuse ve LangSmith gibi sağlayıcılar, onun üzerine kendi session veya thread nesnelerini inşa eder.

Trace ID, span ID ve correlation ID arasındaki fark nedir?

Bir trace ID tek bir isteği tanımlar ve tüm aşağı akış hizmetler boyunca otomatik yayılır. Bir span ID, o trace içindeki tek bir işlemi tanımlar. Bir correlation ID (veya request ID), tracing başlamadan önce web katmanınız tarafından üretilir ve insanların trace ID'siyle en sık karıştırdığı değerdir. Kapsamda örtüşürler ama farklı kökenlerden gelirler.

Bir trace'te kaç span olmalı?

Sabit bir yanıt yoktur, ancak tipik aralıklar bir RAG isteği için 3–30 ve birden çok araç çağrısı olan bir ajan döngüsü için 10–50+ arasıdır. Pratik kural: harici çağrıları ve karar noktalarını span'leyin, süreç içi dönüşümleri değil. Trace'iniz 100 span'i aşıyorsa, büyük olasılıkla aşırı enstrümantasyon yapıyorsunuzdur.

Langfuse "observation"ları span ile aynı şey mi?

Evet. Bir Langfuse observation'ı, bir OTel span'i ile aynı nesnedir: öznitelikleri olan, süresi ölçülen tek bir işlem. Langfuse, observation'ları üç türe ayırır (generation, span, event); OTel'in gen_ai.operation.name kullandığı yerde. Trace'lerinizi okuyan araçları değerlendiriyorsanız, LLM değerlendirme araçları toplu değerlendirmemiz hangilerinin her iki sözcük dağarcığını kabul ettiğini kapsar.

Çok turlu bir sohbet botu konuşmasını tek bir session'da nasıl gruplarsınız?

Her turdaki kök span'e aynı konuşma tanımlayıcısını ayarlayın. OTel terimleriyle bu, gen_ai.conversation.id'dir. Langfuse'ta, trace'leri oluştururken bir session_id geçirirsiniz. LangSmith'te, session_id veya thread_id metadata'sı ayarlarsınız. Bir turu kaçırırsanız o tur gruplamanın dışında kalır.

Yalnızca tek turlu istekleri ele alıyorsam session'lara ihtiyacım var mı?

Büyük olasılıkla hayır. Session'lar, birden çok trace'i tek bir konuşmada ilişkilendirmek için vardır. Her istek bağımsızsa (bir sınıflandırma API'si, tek seferlik bir özetleyici), trace seviyesindeki metrikler yeterlidir. Turlar arası metriklere ihtiyaç duyduğunuzda session ekleyin: çözüm oranı, yanıta ulaşma turu veya konuşma seviyesinde maliyet. LLM değerlendirme rehberimiz, session seviyesindeki eval'ların ne zaman hak ettiğini kapsar.

Kısa Versiyon

Span'ler trace'lerin içine yuvalanır; trace'ler session'larda gruplanır. Yuvalanma gerçektir, ancak şartname üç seviyeden yalnızca ikisini yapılandırır. gen_ai.conversation.id, kendiniz ayarladığınız bir özniteliktir, yayılan bir üst span değildir. Ve bugün seçtiğiniz sağlayıcı, bu nesneleri, 18 ay sonra geçeceğiniz sağlayıcıdan farklı adlandırır; bu yüzden span sözcük dağarcığınızı küçük ve taşınabilir tutun.

Bir platform seçiyorsanız, gözlemlenebilirlik platformu karşılaştırmamızla başlayın. Trace'lerinizin üzerine eval kuruyorsanız, LLM değerlendirme rehberi buradan devam eder.