AgentLoop:OpenTelemetry GenAI Utils ile LLM uygulamalarını izleyin

Kullanım senaryoları

LLM ve AI Agent uygulamaları büyüdükçe gözlemlenebilirlik kritik hale gelir. Agent'lar ile Model Bağlam Protokolü (MCP) araçları arasındaki çok turlu etkileşimleri, vLLM ve SGLang gibi çıkarım motorlarının zamanlama izlerini ve token kullanımı ile İlk Tokena Kadar Geçen Süre (TTFT) gibi ölçümleri toplamak ve analiz etmek için tek bir yönteme ihtiyacınız vardır. ARMS Uygulama İzleme, yaygın GenAI senaryoları için hazır prob çözümleri sağlar. MCP protokolüne dayalı uçtan uca iz konusundaki belgede, Python probunun LangChain Agent'larının ve MCP Sunucularının çağrı zincirini sıfır kod değişikliğiyle nasıl enstrümante ettiği gösterilir. vLLM/SGLang çıkarım motorları için gözlemlenebilirlik kılavuzu ise istek düzeyindeki Span'ları, gen_ai.latency.* niteliklerini ve TTFT ile TPOT gibi ölçümleri kapsar. Özel çerçeveler, çok dilli mimariler veya ayrıntılı Span denetimi gerektiren senaryolar için LLM çağrılarını, Agent orkestrasyonunu ve Tool yürütmesini uygulama kodunuzda manuel olarak enstrümante etmeniz gerekir. GenAI Utils bu senaryolara yönelik bir çözüm sunar.

GenAI Utils, Uygulama İzleme problarının yerine geçen değil, onları tamamlayan bir araçtır. Problar, bilinen çerçeveleri (LangChain, vLLM, MCP) kod yazmadan veya düşük kodlu yaklaşımla otomatik olarak enstrümante eder; bu da standart dağıtımlar için idealdir. GenAI Utils ise uygulama kodunuzda açık Handler API çağrıları gerektirir; bu nedenle özel Agent çerçeveleri, özel Span nitelikleri veya henüz problar tarafından desteklenmeyen entegrasyonlar için uygundur. Her iki yöntem de aynı GenAI Semantik Kurallarına uyan telemetri üretir ve ARMS konsolunda veya OpenTelemetry uyumlu herhangi bir arka uçta birlikte analiz edilebilir.

Nasıl çalışır?

GenAI Utils, üretken yapay zeka işlemleri için paylaşılan bir telemetri kitaplığıdır. LLM çıkarımı, Agent çağrıları, yerleştirme (embedding), Tool yürütme ve geri alma (retrieval) gibi işlemleri OpenTelemetry GenAI Semantik Kuralları ile uyumlu standart Span'lara, Olaylara ve ölçümlere eşler. Ayrıca start, stop ve fail gibi birleşik yaşam döngüsü API'leri sağlar.

OpenTelemetry topluluğu ilk olarak bir Python referans uygulaması olan opentelemetry-util-genai projesini yayınladı. Daha sonra Java, Go ve Node.js için eşdeğer uygulamalar takip etti; her biri aynı API tasarımını ve Semantik Kuralları kullanır.

Tipik bir veri akışı şu şekildedir:

Application code + GenAI Utils (generates Spans)
        ↓
OpenTelemetry SDK / Exporter (configures endpoint and authentication)
        ↓
ARMS Tracing OpenTelemetry Edition
        ↓
ARMS console Trace Explorer

Ön koşullar

GenAI Utils, Semantik Kurallara uygun Span'lar ve ölçümler üretir ancak bu verilerin ARMS İzleme OpenTelemetry Edition'a raporlanması için yapılandırılmış bir OpenTelemetry SDK ve Exporter gerekir. Uygulama kodunuzu yazmadan önce aşağıdaki ön koşulları tamamlayın:

1. ARMS İzleme OpenTelemetry Edition hizmetini etkinleştirin.

2. Bölgeniz için uç nokta alan adını, bağlantı noktasını ve kimlik doğrulama belirtecini alın.

3. OpenTelemetry SDK'sını veya Collector'ünü, OTLP gibi bir protokol üzerinden izleme verilerini ARMS'e raporlayacak şekilde yapılandırın.

Entegrasyon ayrıntıları, bölgesel uç noktalar, bağlantı noktası ve protokol eşlemeleri ile SDK veya Collector yapılandırması için entegrasyon kılavuzuna bakın. Bu kılavuz şunları kapsar:

• Ön koşullar: Uç noktaların, bağlantı noktalarının ve kimlik doğrulama belirteçlerinin nasıl alınacağı.

• OpenTelemetry entegrasyonu: OpenTelemetry SDK'sı veya Collector'ü ile veri raporlamanın nasıl yapılandırılacağı.

• Diğer istemci entegrasyon yöntemleri (Jaeger, Zipkin, SkyWalking vb.).

Uygulamanız Alibaba Cloud dışına dağıtılıyorsa, entegrasyon kılavuzunda açıklandığı gibi gerekli bağlantı noktalarını açmanız ve alan adı erişim izinlerini vermeniz gerekir.

Hızlı başlangıç (Python örneği)

GenAI Utils özelliğine ilk sahip olan dil Python'dur ve API tasarımı diğer diller için referans niteliğindedir. Aşağıdaki örnekte, bir LLM çağrısı için standart bir GenAI Span'ı toplamak üzere TelemetryHandler kullanılır.

GenAI Utils ve buna bağlı OpenTelemetry SDK ve Exporter paketlerini yükleyin:

pip install opentelemetry-util-genai

from opentelemetry.util.genai.handler import get_telemetry_handler
from opentelemetry.util.genai.types import InputMessage, LLMInvocation, OutputMessage, Text

handler = get_telemetry_handler()

invocation = LLMInvocation(
    provider="openai",
    request_model="gpt-4o-mini",
    input_messages=[
        InputMessage(role="user", parts=[Text(content="Explain OpenTelemetry in one sentence.")]),
    ],
)
with handler.llm(invocation) as inv:
    # Call the actual model API here
    inv.output_messages = [
        OutputMessage(
            role="assistant",
            parts=[Text(content="OpenTelemetry is an open standard and implementation for observability.")],
            finish_reason="stop",
        )
    ]
    inv.input_tokens = 10
    inv.output_tokens = 20

Entegrasyon adımları şöyledir: bağımlılıkları yükleyin → OpenTelemetry Provider'ı başlatın → bir handler oluşturun → model API çağrısını with handler.llm(...) ile sarın. Diğer işlem türleri veya mesaj içeriği toplama ilkeleri için programlama dilinize ilişkin belgelere bakın.

Veri raporlamayı doğrulayın

Örnek kodu çalıştırdıktan sonra ARMS konsolunda oturum açın. Trace Explorer sayfasında raporlanan GenAI Span'ını görüntüleyin. Span; kodunuzda ayarladığınız provider, request_model ve token kullanım değerlerine karşılık gelen gen_ai.system, gen_ai.request.model ve gen_ai.usage.* gibi standart nitelikleri içermelidir.

GenAI Utils belgeleri

Tüm dil uygulamaları aynı Semantik Kuralları ve Handler API tasarımını takip eder. Kurulum, API referansları ve kod örnekleri için dilinize ilişkin belgelere bakın: