AI Destekli Yazılım Geliştirmede Ajan Telemetrisi ve Replay

AI Destekli Yazılım Geliştirmede İzlenebilirlik Sınırını Tanımlamak

Bir kod ajanında HTTP erişim günlüğü tek başına yeterli değildir: aynı istek, modelin seçtiği araçlar, araç argümanları, araç çıktıları ve yeniden deneme zinciri görülmeden tekrar üretilemez. Her çalıştırmaya değişmez bir run_id, her model çağrısına span_id verin; OpenTelemetry ile model, tool ve doğrulama adımlarını iç içe span olarak kaydedin. W3C traceparent üst bilgisini API katmanından sandbox işçisine taşıyarak, örneğin "testler neden iki kez çalıştı?" sorusunu tek trace üzerinde yanıtlayabilirsiniz.

• llm.request: model adı, temperature, input/output token sayıları, cache hit bilgisi
• agent.tool: araç adı, şeması doğrulanmış argüman özeti, süre, çıkış kodu
• agent.decision: seçilen eylem, candidate sayısı, retry nedeni

Ham prompt, kaynak kod veya erişim belirteçlerini span attribute olarak göndermeyin. Bunun yerine SHA-256 digest, byte uzunluğu ve allow-list ile seçilmiş alanları kaydedin. Bu ayrım önemlidir: çoğu OTLP toplayıcısı trace verisini merkezi depoya yollar; prompt içindeki müşteri verisi bu akışta beklenmedik bir veri sınıfına dönüşür.

Vibe coding eğitimi veya vibe coding kursu katılımcılarının sık yaptığı hata, yalnızca nihai diff'i ölçmektir. Oysa başarısızlığın kaynağı çoğu zaman diff değil, hatalı araç çağrısıdır: örneğin ajan grep sonucundaki eski bir API kullanımını bağlamına almadan düzenleme yapmış olabilir. Trace üzerinde tool.name=repo.search ve tool.result_count alanlarını filtrelemek, bu tür yanlış kararları model cevabından önce ayırır.

OpenTelemetry ile LLM ve Araç Çağrılarını Kod Düzeyinde İzlemek

Node.js servisinde OpenTelemetry SDK'yı uygulama kodundan önce başlatın; aksi halde HTTP veya fetch enstrümantasyonu modülleri yamalamadan önce yüklenir ve parent-child span ilişkisi kopar. Aşağıdaki örnek OTLP/HTTP ile bir collector'a iz gönderir ve model çağrısının token ile gecikme alanlarını standart dışı ama sorgulanabilir attribute olarak ekler.

// telemetry.mjs -- node --import ./telemetry.mjs server.mjs
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { resourceFromAttributes } from '@opentelemetry/resources';

const exporter = new OTLPTraceExporter({
  url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
});
const sdk = new NodeSDK({
  resource: resourceFromAttributes({
    'service.name': 'code-agent',
    'deployment.environment': process.env.NODE_ENV || 'development'
  }),
  spanProcessor: new SimpleSpanProcessor(exporter)
});
await sdk.start();
process.on('SIGTERM', () => sdk.shutdown());

Çağrı tarafında yalnızca ölçüm için gereken değerleri ekleyin ve span'ı finally içinde kapatın; exception yolunda kapanmayan span'lar p95 hesaplarını yapay biçimde düşürür. promptDigest için Node'un crypto.createHash('sha256') API'sini kullanın; prompt'un kendisini telemetry backend'e taşımayın.

import { trace, SpanStatusCode } from '@opentelemetry/api';
import { createHash } from 'node:crypto';

const tracer = trace.getTracer('code-agent');
export async function askModel(client, prompt) {
  return tracer.startActiveSpan('llm.request', async (span) => {
    const started = performance.now();
    try {
      span.setAttributes({
        'gen_ai.operation.name': 'chat',
        'llm.prompt.sha256': createHash('sha256').update(prompt).digest('hex'),
        'llm.prompt.bytes': Buffer.byteLength(prompt)
      });
      const result = await client.responses.create({ input: prompt });
      span.setAttributes({
        'llm.input_tokens': result.usage.input_tokens,
        'llm.output_tokens': result.usage.output_tokens,
        'llm.latency_ms': Math.round(performance.now() - started)
      });
      return result;
    } catch (err) {
      span.recordException(err);
      span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
      throw err;
    } finally {
      span.end();
    }
  });
}

Generative AI Ajanlarında Gecikme ve Maliyet Profillemesi

Generative AI akışını hızlandırmak için ilk iş model değişimi değil, trace verisinden baseline çıkarmaktır. Grafana Tempo veya Jaeger'da son 500 başarılı run_id için şu üç dağılımı ayrı hesaplayın: uçtan uca süre, toplam output token ve tool çağrısı sayısı. Ardından aynı görev setini, sabit model yapılandırmasıyla, önce mevcut prompt ve sonra değişiklik uygulanmış prompt üzerinden çalıştırın. Ortalama tek başına yanıltıcıdır; tool timeout'ları ve kuyruk gecikmeleri uzun kuyruk oluşturduğu için p50, p95 ve hata oranını birlikte karşılaştırın.

Örnek bir optimizasyon: ajan her turda tüm repository tree'sini prompt'a ekliyorsa, dosya listesi büyüdükçe input token maliyeti doğrusal artar; ayrıca modelin dikkat bütçesinin ilgili dosyalardan uzaklaşması yanlış düzenleme olasılığını artırır. git diff --name-only BASE_SHA HEAD ile değişmiş dosyaları ve rg -l 'symbolName' --glob '*.ts' ile en fazla 12 ilgili dosyayı seçin. Bu seçimi trace'e context.file_count ve context.bytes olarak yazın; yalnızca token düşüşü değil, görev başarı oranındaki değişim de görünür olur.

# Baseline ve değişiklik sonrası aynı evaluation setini çalıştırın.
# Her satır JSONL trace export'undan bir kök run'ı temsil eder.
jq -s 'map(select(.status == "ok")) |
  {n:length,
   p50_ms: (map(.duration_ms)|sort|.[length/2|floor]),
   p95_ms: (map(.duration_ms)|sort|.[(length*0.95)|floor]),
   mean_tokens: ((map(.input_tokens + .output_tokens)|add) / length),
   tool_error_rate: ((map(select(.tool_errors > 0))|length) / length)}'   traces-before.jsonl > before.json
jq -s 'map(select(.status == "ok")) |
  {n:length, p50_ms:(map(.duration_ms)|sort|.[length/2|floor]),
   p95_ms:(map(.duration_ms)|sort|.[(length*0.95)|floor]),
   mean_tokens:((map(.input_tokens+.output_tokens)|add)/length)}'   traces-after.jsonl > after.json

Önemli edge case: streaming yanıt süresini yalnızca son token anından ölçmek, kullanıcının ilk görünür çıktıyı beklediği süreyi gizler. Span'a hem llm.time_to_first_token_ms hem llm.total_generation_ms yazın. Bir reverse proxy'nin buffer'laması açıksa ilk token metrikte iyi görünür fakat kullanıcıya ulaşmaz; NGINX tarafında ilgili streaming endpoint için proxy_buffering off; doğrulamasını ayrı bir entegrasyon testiyle yapın.

LLM Eğitimi İçin Deterministik Replay ve Araç Sözleşmeleri

LLM eğitimi sırasında incelenen bir hata, canlı Git deposu veya canlı API üzerinde yeniden koşturulmamalıdır; repo HEAD'i, bağımlılık çözümü ve araç çıktısı değişir. Replay paketi; system prompt digest'i, model parametreleri, araç şeması sürümü, çağrı sırası, araç sonucunun canonical JSON hali ve sandbox imaj digest'ini içermelidir. Model sağlayıcısı seed parametresi sunsa bile tam determinism varsaymayın: altyapı sürümü ve sampling uygulaması değişebilir. Bu nedenle replay'in hedefi birebir metin eşitliği değil, araç çağrısı dizisi ve doğrulama sonucu eşitliğidir.

// tool sonucu için anahtar sıralı, tekrar oynatılabilir fixture
import { createHash } from 'node:crypto';
function canonical(value) {
  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
  if (value && typeof value === 'object') {
    return `{${Object.keys(value).sort().map(k =>
      `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
  }
  return JSON.stringify(value);
}
export function recordToolCall(call, result) {
  const payload = canonical({ name: call.name, args: call.args, result });
  return { payload, sha256: createHash('sha256').update(payload).digest('hex') };
}

Araç argümanını JSON Schema ile doğrulamak replay kalitesini doğrudan etkiler. Ajv kullanarak additionalProperties: false koyun; aksi halde modelin ürettiği görünmez veya işe yaramayan alanlar fixture'a girer ve sonraki şema değişikliklerinde geriye dönük uyumluluğu yanlış biçimde başarılı gösterir. Örneğin dosya yazma aracı için mutlak yol, .. segmenti ve allow-list dışındaki uzantıları şema sonrası uygulama doğrulamasıyla reddedin; JSON Schema tek başına dosya sistemi semantiğini çözmez.

Bir yapay zeka kursu ya da kurumsal yapay zeka eğitimi laboratuvarında katılımcılara sadece "ajan çalıştı" çıktısı vermek yerine, bozuk replay fixture'ı verin: araç çıktısındaki alan adı değişsin, test komutu 124 ile timeout versin veya prompt digest'i uyuşmasın. Katılımcıdan trace sorgusu, fixture diff'i ve düzeltici commit istemek; teknoloji eğitimi içinde üretim teşhis becerisini ölçen somut bir ödevdir.

Yazılım Eğitimi Programında Telemetriyi Değerlendirme Kriterine Dönüştürmek

Yazılım eğitimi müfredatında ajan projesini değerlendirirken yalnızca unit test sayısını puanlamayın. CI içinde her senaryo için trace_id, assertion sonucu, input/output token, araç hata sayısı ve replay artifact yolu üreten bir JSONL raporu saklayın. GitHub Actions'ta artifact saklama süresini bilinçli belirleyin; örneğin başarısız run'ların fixture'ını 30 gün, başarılı run'ların yalnızca özet metriklerini 7 gün saklamak depolama maliyetini ve hassas veri yüzeyini sınırlar.

AI destekli yazılım geliştirme ve yapay zeka eğitimi içeriklerinde ölçülebilir kabul kriteri şudur: aynı 20 görevlik sabit sette değişiklik sonrası görev başarı oranı düşmeyecek, p95 uçtan uca süre için tanımlı bir bütçe aşılmayacak ve izin verilmeyen araç çağrısı sıfır kalacaktır. Bu üç eşiği CI'da fail-fast kontrolüne bağlayın. Böylece ai destekli yazılım geliştirme pratiği, sezgisel demo yerine trace, replay ve test artifact'larıyla denetlenebilir bir mühendislik sürecine dönüşür.

Sık Sorulan Sorular

AI destekli yazılım geliştirmede OpenTelemetry ile hangi alanlar izlenmeli?

Kök run için run_id ve sonuç; her LLM çağrısı için model, input/output token, TTFT ve toplam süre; her araç için ad, doğrulanmış argüman özeti, süre ve çıkış kodu kaydedin. Prompt ve secret'ları doğrudan attribute olarak göndermek yerine SHA-256 digest ve byte uzunluğu kullanın.

Vibe coding eğitimi projelerinde ajan hatası nasıl tekrar üretilir?

Model yanıtını tek başına saklamayın. Araç çağrı sırası, canonical JSON araç sonuçları, sandbox container image digest'i, commit SHA ve model parametrelerini JSONL fixture'a yazın. Replay'de metin eşitliği yerine araç çağrısı dizisi, patch doğrulaması ve test sonucu eşitliğini assertion yapın.

Yapay zeka kursu için LLM maliyet ve gecikme ölçümü nasıl yapılır?

Jaeger veya Grafana Tempo'dan aynı görev setindeki en az 500 başarılı kök trace'i dışa aktarın; before/after JSONL verisinde p50, p95, token ortalaması ve tool_error_rate hesaplayın. Değişiklik olarak örneğin tüm repo yerine rg ve git diff ile seçilmiş dosyaları prompt'a koyun; başarı oranını da aynı sette kontrol edin.

Generative AI ajanlarında streaming için hangi gecikme metriği önemlidir?

Hem time-to-first-token hem total-generation sürelerini kaydedin. Ayrıca istemci tarafında ilk byte zamanını ölçün; proxy buffering açıksa sağlayıcıdan ilk token hızlı gelse bile kullanıcı geç görür. NGINX streaming endpoint yapılandırmasında proxy_buffering off ayarını entegrasyon testiyle doğrulayın.