@microsoft/agents-a365-observability package

Dışarı aktarma toplu işlemi başına en fazla yayılma alanı sayısı.

OpenTelemetry bağlam yayma için istek bagaj oluşturucusu başına.

Bu sınıf, OpenTelemetry bağlamında yayılacak bagaj değerlerini ayarlamak için akıcı bir API sağlar.

Örnek

const scope = new BaggageBuilder()
  .tenantId("tenant-123")
  .agentId("agent-456")
  .build();

scope.enter();
// Baggage is set in this context
// ... do work ...
scope.exit();
// Baggage is restored after exiting the context

Bagaj kapsamı için bağlam yöneticisi.

Bu sınıf, bagaj değerlerinin yaşam döngüsünü yönetir, girişte ayarlar ve çıkışta önceki bağlamı geri yükler.

OpenTelemetry izleme ile Agent 365'i yapılandırmak için oluşturucu

Yapay zeka aracı yürütme işlemleri için OpenTelemetry izleme kapsamı sağlar.

Oluşturma yapay zeka çıkarım işlemleri için OpenTelemetry izleme kapsamı sağlar.

Yapay zeka aracısı çağırma işlemleri için OpenTelemetry izleme kapsamı sağlar.

Gözlemlenebilirlik paketi için yapılandırma. Çalışma zamanı ayarlarını devralır ve gözlemlenebilirliğe özgü ayarlar ekler.

AI aracıları ve araçları için OpenTelemetry izleme sağlayan Agent 365 ana giriş noktası

Aracı 365 için OpenTelemetry sabitleri

OpenTelemetry izleme kapsamları için temel sınıf

Üst yayılma bağlantısıyla çıkış iletisi izlemesi için OpenTelemetry izleme kapsamı sağlar.

PerRequestSpanProcessor yapılandırması. Çalışma zamanı ayarlarını (clusterCategory, isNodeEnvDevelopment) devralır ve istek başına işlemci korumaları ekler.

PerRequestSpanProcessor yalnızca belirli senaryolarda kullanıldığından ve bu ayarların ortak ObservabilityConfiguration'da gösterilmemesi gerektiğinden, bu observabilityConfiguration'dan ayrılır.

Yapay zeka aracısı hakkındaki ayrıntılar

Satır içi ikili veriler (base64 ile kodlanmış).

Agent 365 Gözlemlenebilirlik Oluşturucusu için yapılandırma seçenekleri

Kapsam oluşturma için arayan ayrıntıları. İnsan arayanları, aracı arayanları veya her ikisini (zincirdeki bir insanla A2A) destekler.

Geçiş notu: v1'de insan arayan kimliğine (şimdi CallerDetails) başvurulan ad. v2'de hem insan hem de aracı çağıran bilgilerini gruplandıran bir sarmalayıcı olarak yeniden kullanıldı.

Geçiş kılavuzu için bkz. UserDetails — insan arayan kimliği (daha önce CallerDetails) bkz. CHANGELOG.md — hataya neden olan değişiklikler bölümü

Çağrı için kanalı temsil eder

Modele gönderilen giriş iletisi (OTEL gen-ai semantik kuralları).

Önceden yüklenmiş bir dosyaya başvuru.

Özel/gelecek türler için genişletilebilir bölüm.

Tür ayrıştırıcısı ile genişletilebilir sunucu aracı çağrı ayrıntıları.

Tür ayrıştırıcısı ile genişletilebilir sunucu aracı çağrı yanıtı.

Agent 365 gözlemlenebilirliği için özel günlükçü arabirimi Arka uçları günlüğe kaydetmeyi desteklemek için bu arabirimi uygulayın

Çıkarım çağrısının ayrıntıları

Çıkarım çağrısından yanıtı kaydetme ayrıntıları

Aracı kapsamını çağırma ayrıntıları.

Model tarafından oluşturulan bir çıkış iletisi (OTEL gen-ai semantik kuralları).

Bir aracıdan gelen çıkış iletilerini içeren bir yanıtı temsil eder. Çıkış iletisi izleme için OutputScope ile kullanılır. Düz dizeleri, yapılandırılmış OTEL OutputMessage nesnelerini veya ham bir dikteyi kabul eder (OTEL belirtimlerine göre araç çağrı sonucu olarak kabul edilir).

Zaman uyumsuz sınırlar arasında açık üst-alt bağlantı için üst yayılmaya başvuru. Otomatik bağlam yayma başarısız olduğunda (örneğin, WebSocket geri çağırmaları, dış olay işleyicileri) kullanılır.

Model mantığı / düşünce zinciri içeriği.

Telemetri bağlamı olan bir isteği temsil eder. Kanal ve konuşma izleme için tüm kapsam türlerinde kullanılır.

Sunucu tarafı araç çağırma.

Sunucu tarafı araç yanıtı.

Aracı çağırma için bir uç noktayı temsil eder

Kapsam oluşturma için span yapılandırma ayrıntıları. OpenTelemetry span seçeneklerini tek bir nesne halinde gruplandırarak kapsam yöntemi imzasının yeni seçenekler eklendikçe kararlı kalmasını sağlar.

Düz metin içeriği.

Aracı tarafından yapılan araç çağrısının ayrıntıları

Model tarafından istenen bir araç çağrısı.

Araç çağrısının sonucu.

Dış URI başvurusu.

İnsan kullanıcı çağıranı hakkındaki ayrıntılar.

İzleme bağlamı yaymada kullanılan HTTP üst bilgileri için taşıyıcı türü. Node.js GelenHttpHeaders ve düz dize eşlemeleriyle uyumludur.

için recordInputMessageskabul edilen giriş. Tek bir dizeyi, dize dizisini (geriye dönük uyumluluk) veya sürümlenmiş sarmalayıcıyı destekler.

OTEL gen-ai semantik kuralları başına tüm ileti parça türlerinin birleşimi.

Not: GenericPart , özel veya gelecekteki parça türleriyle ileriye dönük uyumluluk için tümünü yakalama işlevi görür. değeri type (değişmez değer değil) olduğundan string , üzerinde switch kapsamlı /casepart.type olması işlenmeyen durumlar için derleme zamanı hataları üretmez.

Gözlemlenebilirlik yapılandırma seçenekleri - çalışma zamanı seçeneklerini genişletir. Tüm geçersiz kılmalar, her özellik erişiminde çağrılan işlevlerdir.

RuntimeConfigurationOptions'dan devralındı:

• clusterCategory
• isNodeEnvDevelopment

Not: isDevelopmentEnvironment geçersiz kılınabilir bir seçenek değil, yapılandırma sınıfındaki türetilmiş bir alıcıdır (clusterCategory temelinde).

için recordOutputMessageskabul edilen giriş. Tek bir dizeyi, dize dizisini (geriye dönük uyumluluk) veya sürümlenmiş sarmalayıcıyı destekler.

Yayılma alanı oluşturma için üst bağlam. Kabul eder:

• ParentSpanRef: açık traceId/spanId çifti (el ile yaklaşım)
• ParentContext: bir OTel Bağlamı, genellikle extractContextFromHeaders veya propagation.extract()

PerRequestSpanProcessor için yapılandırma seçenekleri - çalışma zamanı seçeneklerini genişletir. Tüm geçersiz kılmalar, her özellik erişiminde çağrılan işlevlerdir.

RuntimeConfigurationOptions'dan devralındı:

• clusterCategory, isNodeEnvDevelopment

için OutputResponse.messageskabul edilen giriş. Düz dizeleri, yapılandırılmış OutputMessage'ları veya ham bir dikteyi destekler (OTEL belirtimi başına bir araç çağrı sonucu olarak ele alınır ve doğrudan JSON.stringify aracılığıyla serileştirilir).

Agent365Exporter tarafından günlüğe kaydetme ve izleme için kullanılan olay adları. Bunlar, verimli izleme ve toplama sağlamak için düşük kardinaliteye sahip olay türleridir.

Otel gen-ai semantik kurallarına göre modelin oluşturmayı durdurmasının nedeni.

Model çıkarımı türleri için farklı işlemi temsil eder

Aracı çağırabilen farklı rolleri temsil eder

OTEL gen-ai semantik kuralları başına bir ileti katılımcısının rolü.

Blob, dosya ve URI bölümleri için medya kalıcılığı.

Açık üst yayılma alanı başvurusuyla yeni bir Bağlam oluşturur. Bu, zaman uyumsuz bağlam bozulsa bile alt span'ların doğru şekilde üst öğeye sahip olmasını sağlar.

Genel olarak kaydedilen W3C yayıcısını kullanarak gelen HTTP üst bilgilerinden izleme bağlamını ayıklar. Kapsam sınıflarına ParentContext olarak geçirilebilen bir OTel döndürür.

Örnek

const parentCtx = extractContextFromHeaders(req.headers);
const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails, undefined, { parentContext: parentCtx });

İleti ve yığın izleme ile günlüğe kaydetme için hata nesnesini biçimlendirme

Belirli bir OTel Bağlamından (veya etkin olandan) istek başına dışarı aktarma belirtecini alın.

Geçerli günlükçü örneğini alma

Genel olarak kaydedilen W3C yayıcısını kullanarak sağlanan üst bilgi nesnesine geçerli izleme bağlamını (traceparent/tracestate üst bilgiler) ekler.

Örnek

const headers: Record<string, string> = {};
injectContextToHeaders(headers);
await fetch('http://service-b/process', { headers });

İstek başına dışarı aktarmanın etkinleştirilip etkinleştirilmediğini denetleyin. Öncelik: iç geçersiz kılma yapılandırma > sağlayıcısı > ortam değişkeni. Etkinleştirildiğinde, BatchSpanProcessor yerine PerRequestSpanProcessor kullanılır. Belirteç dışarı aktarma zamanında OTel Bağlamı (zaman uyumsuz yerel depolama) aracılığıyla geçirilir.

bir InputMessagesParam sürümünü bir sarmalayıcıya InputMessages normalleştirir.

• string / string[] → dönüştürüldü ChatMessage[] ve sarmalandı
• InputMessages → döndürülen as-is

bir OutputMessagesParam sürümünü bir sarmalayıcıya OutputMessages normalleştirir.

• string / string[] → dönüştürüldü OutputMessage[] ve sarmalandı
• OutputMessages → döndürülen as-is

Varsayılan konsol günlükçüsne sıfırlama (temel olarak test için)

İstek başına dışarı aktarma belirtecini taşıyan bir Bağlam içinde bir işlev çalıştırın. Bu, belirteci hiçbir kayıt defterinde değil yalnızca OTel Bağlamı'nda (ALS) tutar.

Belirteç daha sonra izleme temizlenmeden önce aracılığıyla updateExportToken() güncelleştirilebilir; geri arama uzun süre çalıştığında ve özgün belirtecin süresi dışarı aktarmadan önce dolabilir.

Gelen HTTP üst bilgilerinden izleme bağlamını ayıklar ve bu bağlamda geri çağırmayı çalıştırır. Geri çağırma içinde oluşturulan tüm span'lar ayıklanan izlemenin üst öğesi olur.

Örnek

runWithExtractedTraceContext(req.headers, () => {
  const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
  scope.dispose();
});

Açık üst yayılma alanı başvurusu olan bir bağlam içinde bir geri çağırma işlevi çalıştırır. Bu, bağlam yayma işleminin bozuk olduğu zaman uyumsuz geri çağırmalarda alt yayılmalar oluşturmak için kullanışlıdır.

Değerin her zaman JSON ayrıştırılabilir bir dize olmasını sağlar.

• Nesneler JSON.stringify aracılığıyla serileştirilir.
• Geçerli JSON nesneleri/dizileri olan dizeler geçirilir.
• Diğer tüm dizeler (çıplak JSON temel öğeleri dahil) sarmalanmıştır: { [key]: value }.

JSON sürümüne sahip bir ileti sarmalayıcısını seri hale getirmektedir.

Çıktı, tam sarmalayıcı nesnesidir: {"version":"0.1.0","messages":[...]}.

Try/catch, ileti bölümleri JSON serileştirilebilir olmayan değerler (bigInt, dairesel refs gibi) içerdiğinde bile telemetri kaydının oluşturmamasını sağlar.

Gözlemlenebilirlik SDK'sı için özel günlükçü uygulaması ayarlama

Winston ile örnek:

import * as winston from 'winston';
import { setLogger } from '@microsoft/agents-a365-observability';

const winstonLogger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' })
  ]
});

setLogger({
  info: (msg, ...args) => winstonLogger.info(msg, ...args),
  warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
  error: (msg, ...args) => winstonLogger.error(msg, ...args),
  event: (eventType, isSuccess, durationMs, message, details) => {
    // eventType is ExporterEventNames enum value
    winstonLogger.log({ level: isSuccess ? 'info' : 'error', eventType, isSuccess, durationMs, message, ...details });
  }
});

Etkin OTel Bağlamında dışarı aktarma belirtecini güncelleştirin. Uzun süre çalışan bir istek sırasında özgün belirtecin süresi dolmuş olabilirken kök aralığı sonlandırmadan önce belirteci yenilemek için bunu çağırın.

tarafından runWithExportTokenoluşturulan aynı zaman uyumsuz bağlam içinde çağrılmalıdır.

ObservabilityConfiguration için paylaşılan varsayılan sağlayıcı.

PerRequestSpanProcessorConfiguration için paylaşılan varsayılan sağlayıcı.

Geriye dönük uyumluluk için varsayılan günlükçü örneği. setLogger() aracılığıyla değiştirilebilen genel günlükçüye temsilciler.