Gözlemlenebilirlik SDK'sı

Önemli

Agent 365'te gözlemlenebilirliği etkinleştirmek için Microsoft OpenTelemetry Dağıtımı kullanın. Bu dağıtım, Microsoft genelinde tek bir gözlemlenebilirlik SDK'sı sunarak Agent 365, Microsoft Atölye, Azure İzleyici ve daha fazlasını destekliyor. Bu makalede açıklanan mevcut yaklaşım, herhangi bir uyumsuzluk oluşturmadan çalışmaya devam etmektedir. Dile göre geçiş rehberliği için aşağıdaki rehberlere bakınız:

• Python geçiş kılavuzu
• JavaScript/TypeScript geçiş kılavuzu
• .NET geçiş rehberi Temel veri modeli, kimlik ve kimlik doğrulama, kapsamlar ve onay ile her entegrasyon yoluna uygulanan sınırlar hakkında bilgi için Agent 365 gözlemlenebilirlik kavramlarına bakınız.

Not

Gözlemlenebilirlik, Agent 365 geliştirmeye başlama sürecindeki kademeli yetenek katmanlarından biridir ve tüm aracı türleri için geçerlidir.

Agent 365 ekosistemine katılmak için, aracınıza Agent 365 Gözlemlenebilirlik yeteneklerini ekleyin. Agent 365 Gözlemlenebilirliği, OpenTelemetry (OTel) üzerine inşa edilir ve tüm aracı platformlarında telemetriyi tutarlı ve güvenli şekilde yakalamak için birleşik bir çerçeve sunar. Bu gerekli bileşeni hayata geçirerek, BT yöneticilerinin Microsoft yönetim merkezinde aracınızın etkinliklerini izlemesini mümkün kılar ve güvenlik ekiplerinin uyumluluk ve tehdit tespiti için Defender ve Purview'u kullanmasına olanak tanırsınız.

Temel avantajlar

• Uçtan uca görünürlük: Her aracı çağrısı için, oturumlar, araç çağrıları ve istisnalar dahil olmak üzere kapsamlı telemetri toplanır; bu sayede platformlar arasında tam izlenebilirlik elde edilir.
• Güvenlik ve uyumluluk sağlama: Birleşik denetim kayıtlarını Defender ve Purview'e aktararak, aracınız için gelişmiş güvenlik senaryoları ve uyumluluk raporlaması sağlanır.
• Platformlar arası esneklik: OTel standartları üzerine inşa edilerek Copilot Studio, Foundry ve gelecekteki aracı çerçeveleri gibi çeşitli çalışma zamanları ve platformlar desteklenmektedir.
• Yöneticiler için operasyonel verimlilik: Microsoft 365 yönetim merkezinde merkezi gözlemlenebilirlik sağlanarak, sorun giderme süresi azaltılır ve aracınızı yöneten BT ekipleri için rol tabanlı erişim kontrolleriyle yönetişim iyileştirilir.

Desteklenen aracılar

Aşağıdaki aracı türleri Agent 365 gözlemlenebilirliğini destekler:

• Microsoft Agent 365 özellikli aracılar: Aracınıza gözlemlenebilirlik eklemek için gözlemlenebilirlik SDK'sını kullanın.
• Özel motor aracıları: Aracınızı görüntülemek için gözlemlenebilirlik SDK'sını kullanın.
• Bildirim temelli aracılar: Gözlemlenebilirlik kutudan çıktığı gibi desteklenir. SDK uygulaması gerekmiyor.

Yükleme

Agent 365 tarafından desteklenen diller için gözlemlenebilirlik modüllerini yüklemek üzere bu komutları kullanın.

Python

Temel gözlemlenebilirlik ve çalışma zamanı paketlerini kurun. Agent 365 Observability kullanan tüm aracılar için bu paketler gereklidir.

pip install microsoft-agents-a365-observability-core
pip install microsoft-agents-a365-runtime

Aracınız Microsoft Agents Hosting paketini kullanıyorsa, barındırma entegrasyon paketini kurun. O, TurnContext'den baggage (bagaj) ve kapsamları otomatik olarak dolduran bir ara yazılım sağlar ve gözlemlenebilirlik dışa aktarıcısı için token önbelleğe alma özelliğini içerir.

pip install microsoft-agents-a365-observability-hosting

Aracınız desteklenen AI frameworklerinden birini kullanıyorsa, ilgili otomatik enstrümantasyon uzantısını yükleyerek telemetriyi manuel enstrümantasyon kodu olmadan otomatik olarak yakalayabilirsiniz. Konfigürasyon detayları için Otomatik enstrümantasyon bölümüne bakın.

# For Semantic Kernel
pip install microsoft-agents-a365-observability-extensions-semantic-kernel

# For OpenAI Agents SDK
pip install microsoft-agents-a365-observability-extensions-openai

# For Microsoft Agent Framework
pip install microsoft-agents-a365-observability-extensions-agent-framework

# For LangChain
pip install microsoft-agents-a365-observability-extensions-langchain

JavaScript

Temel gözlemlenebilirlik ve çalışma zamanı paketlerini kurun. Agent 365 Observability kullanan tüm aracılar için bu paketler gereklidir.

npm install @microsoft/agents-a365-observability
npm install @microsoft/agents-a365-runtime

Aracınız @microsoft/agents-hosting paketini kullanıyorsa, hosting entegrasyon paketini kurun. O, TurnContext'den baggage (bagaj) ve kapsamları otomatik olarak dolduran bir ara yazılım sağlar ve gözlemlenebilirlik dışa aktarıcısı için token önbelleğe alma özelliğini içerir.

npm install @microsoft/agents-a365-observability-hosting

Aracınız desteklenen AI frameworklerinden birini kullanıyorsa, ilgili otomatik enstrümantasyon uzantısını yükleyerek telemetriyi manuel enstrümantasyon kodu olmadan otomatik olarak yakalayabilirsiniz. Konfigürasyon detayları için Otomatik enstrümantasyon bölümüne bakın.

// For OpenAI Agents SDK
npm install @microsoft/agents-a365-observability-extensions-openai

// For LangChain
npm install @microsoft/agents-a365-observability-extensions-langchain

.NET

Çekirdek gözlemlenebilirlik ve çalışma zamanı paketini kurun. Agent 365 Observability kullanan tüm aracılar için bu paket gereklidir.

dotnet add package Microsoft.Agents.A365.Observability.Runtime

Eğer aracınız Microsoft.Agents.A365.Observability.Hosting NuGet paketini kullanıyorsa, hosting entegrasyon paketini kurun. Bu, TurnContext'den gelen verileri otomatik olarak dolduran bir ara yazılım sağlar ve gözlemlenebilirlik dışa aktarıcısı için belirteç önbelleklemesini içerir.

dotnet add package Microsoft.Agents.A365.Observability.Hosting

Aracınız desteklenen AI frameworklerinden birini kullanıyorsa, ilgili otomatik enstrümantasyon uzantısını yükleyerek telemetriyi manuel enstrümantasyon kodu olmadan otomatik olarak yakalayabilirsiniz. Konfigürasyon detayları için Otomatik enstrümantasyon bölümüne bakın.

// For Semantic Kernel
dotnet add package Microsoft.Agents.A365.Observability.Extensions.SemanticKernel

// For OpenAI
dotnet add package Microsoft.Agents.A365.Observability.Extensions.OpenAI

// For Agent Framework
dotnet add package Microsoft.Agents.A365.Observability.Extensions.AgentFramework

Konfigürasyon

Aracınızda Agent 365 Gözlemlenebilirliğini etkinleştirmek ve özelleştirmek için aşağıdaki ayarları uygulayın.

Python

Gözlemlenebilirlik için ENABLE_A365_OBSERVABILITY_EXPORTER ortam değişkenini true değerine ayarlayın. Bu ayar, logların servise aktarılmasını sağlar ve bir token_resolver sağlanmasını gerektirir. Aksi takdirde, konsol dışa aktarıcısı kullanılır.

from microsoft_agents_a365.observability.core import configure

def token_resolver(agent_id: str, tenant_id: str) -> str | None:
    # Implement secure token retrieval here
    return "Bearer <token>"

configure(
    service_name="my-agent-service",
    service_namespace="my.namespace",
    token_resolver=token_resolver,
)

Token çözümcüsü konsola giriş yapmaktan hariç tutulur.

Agent365ExporterOptions örneğini exporter_options parametresine geçirerek dışa aktarıcı davranışını özelleştirebilirsiniz. exporter_options sağlandığında, token_resolver ve cluster_category parametrelerine göre öncelikli olur.

from microsoft_agents_a365.observability.core import configure, Agent365ExporterOptions

configure(
    service_name="my-agent-service",
    service_namespace="my.namespace",
    exporter_options=Agent365ExporterOptions(
        cluster_category="prod",
        token_resolver=token_resolver,
    ),
    suppress_invoke_agent_input=True,
)

Aşağıdaki tabloda configure() için isteğe bağlı parametreler açıklanmaktadır.

Parametre	Açıklama	Varsayılan
logger_name	Hata ayıklama ve konsol günlük çıktısı için kullanılan Python logger'ın adı.	microsoft_agents_a365.observability.core
exporter_options	Belirteç çözümcüsü ve küme kategorisini birlikte yapılandıran bir Agent365ExporterOptions örneği.	None
suppress_invoke_agent_input	True olduğunda, InvokeAgent aralıklarında giriş mesajlarını bastırır.	False

Aşağıdaki tabloda Agent365ExporterOptions için isteğe bağlı özellikler açıklanmaktadır.

Özellik	Açıklama	Varsayılan
use_s2s_endpoint	True olduğunda, hizmetten hizmete uç nokta yolunu kullanır.	False
max_queue_size	Toplu işlemci için maksimum kuyruk boyutu.	2048
scheduled_delay_ms	Dışarı aktarma toplu işleri arasındaki gecikme (milisaniye cinsinden).	5000
exporter_timeout_ms	Dışarı aktarma işlemi için zaman aşımı (milisaniye cinsinden).	30000
max_export_batch_size	Dışarı aktarma işlemleri için maksimum toplu boyut.	512

JavaScript

Gözlemlenebilirlik için ENABLE_A365_OBSERVABILITY_EXPORTER ortam değişkenini true değerine ayarlayın. Bu ayar, logları servise aktarır ve bir token çözücü sağlanmasını gerektirir. Aksi takdirde, konsol dışa aktarıcısı kullanılır.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';

// Define a token resolver to authenticate with the observability service for exporting logs
const tokenResolver = (agentId, tenantId) => {
    // Your token resolution logic here
    return "your-token";
};

// Advanced configuration with builder pattern
const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withTokenResolver((agentId, tenantId) => {
      return tokenResolver(agentId, tenantId);
    })
);

builder.start();

Ortam değişkenlerine alternatif olarak, withConfigurationProvider yöntemiyle bir yapılandırma sağlayıcı kullanarak gözlemlenebilirliği programatik olarak yapılandırabilirsiniz. Eğer ayrıca bireysel yapıcı yöntemler (örneğin withExporterOptions veya withClusterCategory) kullanırsanız, bireysel yapıcı yöntemler yapılandırma sağlayıcısının değerlerine göre öncelik kazanır.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { ObservabilityConfiguration } from '@microsoft/agents-a365-observability';

const configProvider = new ObservabilityConfiguration({
  isObservabilityExporterEnabled: () => true,
  // Set log levels as pipe-separated values (for example, 'info|warn|error')
  observabilityLogLevel: () => 'info|warn|error',
});

const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withConfigurationProvider(configProvider)
    .withTokenResolver((agentId, tenantId) => {
      return tokenResolver(agentId, tenantId);
    })
);

builder.start();

Agent365ExporterOptions örneğini withExporterOptions parametresine geçirerek dışa aktarıcı davranışını özelleştirebilirsiniz. Bu seçenek sayesinde toplu işlem, zaman aşımları ve rota modunu kontrol edebilirsiniz.

import {
  ObservabilityManager,
  Agent365ExporterOptions,
} from '@microsoft/agents-a365-observability';
import { ClusterCategory } from '@microsoft/agents-a365-runtime';

const exporterOptions = new Agent365ExporterOptions();
exporterOptions.maxQueueSize = 10;

const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withClusterCategory(ClusterCategory.prod)
    .withExporterOptions(exporterOptions)
    .withTokenResolver(tokenResolver)
);

builder.start();

Aşağıdaki tabloda Agent365ExporterOptions için isteğe bağlı özellikler açıklanmaktadır.

Özellik	Açıklama	Varsayılan
useS2SEndpoint	true olduğunda, hizmetten hizmete uç nokta yolunu kullanır.	false
maxQueueSize	Toplu işlemci için maksimum kuyruk boyutu.	2048
scheduledDelayMilliseconds	Dışarı aktarma toplu işleri arasındaki gecikme (milisaniye cinsinden).	5000
exporterTimeoutMilliseconds	Tüm dışarı aktarma işlemi için zaman aşımı (milisaniye cinsinden).	90000
httpRequestTimeoutMilliseconds	Arka ucuna yapılan her bir HTTP isteği için zaman aşımı (milisaniye cinsinden).	30000
maxExportBatchSize	Dışarı aktarma işlemleri için maksimum toplu boyut.	512

Ayrıca, ILogger arayüzünü uygulayan özel bir logger sağlayabilirsiniz (info, warn, error, event). Bunu withCustomLogger kullanarak yapıcıya aktarın.

const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withCustomLogger({
      info: (message, ...args) => { /* your logging logic */ },
      warn: (message, ...args) => { /* your logging logic */ },
      error: (message, ...args) => { /* your logging logic */ },
      event: (eventName, success, durationMs, message, details) => { /* your logging logic */ }
    })
    .withTokenResolver((agentId, tenantId) => {
      return tokenResolver(agentId, tenantId);
    })
);

builder.start();

.NET

EnableAgent365Exporter değerini true olarak appsettings.json içinde ayarlayın.

Program.cs içinde, Agent365ExporterOptions'yi hizmet koleksiyonuna ekleyin. Bu değişiklik, iz ihracatçısının token almak için kullandığı delegeyi yapılandırır.

AddA365Tracing() ile gözlemlenebilirlikle ilgili bağımlılıkları ekleyin.

using Microsoft.Agents.A365.Observability.Runtime;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Exporters;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton(sp =>
    {
        return new Agent365ExporterOptions
        {
            TokenResolver = async (agentId, tenantId) =>
            {
                // It's recommended to implement caching in your token provider for performance.
                var token = await tokenProvider.GetObservabilityTokenAsync(agentId, tenantId);
                return token;
            }
        };
    });

builder.AddA365Tracing();

Exporter davranışını, yapılandırma delegesi ve exporter tipini AddA365Tracing()'ye ileterek özelleştirebilirsiniz.

builder.AddA365Tracing(
    configure: tracingBuilder =>
    {
        // Use the builder to add extensions (e.g., WithSemanticKernel(), WithOpenAI())
    },
    agent365ExporterType: Agent365ExporterType.Agent365ExporterAsync
);

Aşağıdaki tabloda Agent365ExporterOptions için isteğe bağlı özellikler açıklanmaktadır.

Özellik	Açıklama	Varsayılan
UseS2SEndpoint	true olduğunda, hizmetten hizmete uç nokta yolunu kullanır.	false
MaxQueueSize	Toplu işlemci için maksimum kuyruk boyutu.	2048
ScheduledDelayMilliseconds	Dışarı aktarma toplu işleri arasındaki gecikme (milisaniye cinsinden).	5000
ExporterTimeoutMilliseconds	Dışarı aktarma işlemi için zaman aşımı (milisaniye cinsinden).	30000
MaxExportBatchSize	Dışarı aktarma işlemleri için maksimum toplu boyut.	512

Bagaj öznitelikleri

BaggageBuilder kullanarak bir istekteki tüm aralıklar arasında akan bağlamsal bilgileri ayarlayın. SDK, tüm boş olmayan bagaj girdilerini yeni başlatılan aralıklara kopyalayan bir SpanProcessor uygular ve mevcut özniteliklerin üzerine yazmaz.

Python

from microsoft_agents_a365.observability.core import BaggageBuilder

with (
    BaggageBuilder()
    .tenant_id("tenant-123")
    .agent_id("agent-456")
    .conversation_id("conv-789")
    .build()
):
    # Any spans started in this context will receive these as attributes
    pass

BaggageBuilder'i TurnContext'den otomatik olarak doldurmak için, microsoft-agents-a365-observability-hosting paketindeki populate yardımcıyı kullanın. Bu yardımcı, etkinlikten arayanı, aracıyı, kiracıyı, kanalı ve konuşma ayrıntılarını otomatik olarak ayıklar.

from microsoft_agents.hosting.core.turn_context import TurnContext
from microsoft_agents_a365.observability.core import BaggageBuilder
from microsoft_agents_a365.observability.hosting.scope_helpers.populate_baggage import populate

builder = BaggageBuilder()
populate(builder, turn_context)

with builder.build():
    # Baggage is auto-populated from the TurnContext activity
    pass

JavaScript

import { BaggageBuilder } from '@microsoft/agents-a365-observability';

// Create and apply baggage context
const baggageScope = new BaggageBuilder()
  // Core identifiers
  .tenantId('tenant-123')
  .agentId('agent-456')
  .conversationId('conv-789')
  .build();

// Execute operations within the baggage context
baggageScope.run(() => {
  // All spans created within this context will inherit the baggage values

  // Invoke another agent
  const agentScope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
  // ... agent logic

  // Execute tools
  const toolScope = ExecuteToolScope.start(request, toolDetails, agentDetails);
  // ... tool logic
});

BaggageBuilder'i TurnContext'den otomatik olarak doldurmak için, @microsoft/agents-a365-observability-hosting paketindeki fromTurnContext yardımcıyı kullanın. Bu yardımcı, etkinlikten arayanı, aracıyı, kiracıyı, kanalı ve konuşma ayrıntılarını otomatik olarak ayıklar.

import { BaggageBuilder } from '@microsoft/agents-a365-observability';
import { BaggageBuilderUtils } from '@microsoft/agents-a365-observability-hosting';

const baggageScope = BaggageBuilderUtils.fromTurnContext(new BaggageBuilder(), context)
  .invokeAgentServer(context.activity.serviceUrl, 3978)
  .build();

await baggageScope.run(async () => {
  // Baggage is auto-populated from the TurnContext activity
});

.NET

using Microsoft.Agents.A365.Observability.Runtime.Common;

using var baggageScope = new BaggageBuilder()
    .TenantId("tenant-123")
    .AgentId("agent-456")
    .ConversationId("conv-789")
    .Build();
// Any spans started in this context will receive them as attributes.

BaggageBuilder öğesini ITurnContext öğesinden otomatik olarak doldurmak için Microsoft.Agents.A365.Observability.Hosting paketindeki FromTurnContext genişletme yöntemini kullanın. Bu yöntem, etkinlikten arayanı, aracıyı, kiracıyı, kanalı ve konuşma ayrıntılarını otomatik olarak ayıklar.

using Microsoft.Agents.A365.Observability.Runtime.Common;
using Microsoft.Agents.A365.Observability.Hosting.Extensions;

using var baggageScope = new BaggageBuilder()
    .FromTurnContext(turnContext)
    .Build();

Bagaj ara yazılımı

Aracınız barındırma tümleştirme paketini kullanıyorsa, gelen her istek için bagajı otomatik olarak doldurmak üzere bagaj ara yazılımını kaydedin. Bu adım, her etkinlik işleyicisinde BaggageBuilder öğesini el ile çağırma gereksinimini ortadan kaldırır.

Python

Adaptör ara yazılım setine BaggageMiddleware kaydedin. Gelen her TurnContext öğesinden çağıran, aracı, kiracı, kanal ve konuşma ayrıntılarını otomatik olarak ayıklar ve isteği bir baggage kapsamında sarmalanır.

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

Alternatif olarak, diğer barındırma özellikleriyle birlikte baggage middleware'i yapılandırmak için ObservabilityHostingManager kullanın:

from microsoft_agents_a365.observability.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

options = ObservabilityHostingOptions(enable_baggage=True)
ObservabilityHostingManager.configure(adapter.middleware_set, options)

Ara yazılım, orijinal isteğin zaten ayarladığı bagajın üzerine yazılmasını önlemek için zaman uyumsuz yanıtlar (ContinueConversation olayları) için bagaj kurulumunu atlar.

JavaScript

BaggageMiddleware öğesini bağdaştırıcıya kaydedin. Gelen her TurnContext öğesinden çağıran, aracı, kiracı, kanal ve konuşma ayrıntılarını otomatik olarak ayıklar ve isteği bir baggage kapsamında sarmalanır.

import { BaggageMiddleware } from '@microsoft/agents-a365-observability-hosting';

// Option 1: Register middleware directly on the adapter
adapter.use(new BaggageMiddleware());

Alternatif olarak, diğer barındırma özellikleriyle birlikte baggage middleware'i yapılandırmak için ObservabilityHostingManager kullanın:

import { ObservabilityHostingManager } from '@microsoft/agents-a365-observability-hosting';

const manager = new ObservabilityHostingManager();
manager.configure(adapter, { enableBaggage: true });

Ara yazılım, orijinal isteğin zaten ayarladığı bagajın üzerine yazılmasını önlemek için zaman uyumsuz yanıtlar (ContinueConversation olayları) için bagaj kurulumunu atlar.

.NET

BaggageTurnMiddleware öğesini bağdaştırıcıya kaydedin. Gelen her ITurnContext öğesinden çağıran, aracı, kiracı, kanal ve konuşma ayrıntılarını otomatik olarak ayıklar ve isteği bir baggage kapsamında sarmalanır.

using Microsoft.Agents.A365.Observability.Hosting.Middleware;

adapter.Use(new BaggageTurnMiddleware());

Ara yazılım, orijinal isteğin zaten ayarladığı bagajın üzerine yazılmasını önlemek için zaman uyumsuz yanıtlar (ContinueConversation olayları) için bagaj kurulumunu atlar.

HTTP düzeyinde baggage gerekiyorsa (örneğin, Bot Framework işlem hattı çalışmadan önce kiracı ve aracı kimliklerini ayarlamak için), UseObservabilityRequestContext uzantı yöntemini kullanarak ObservabilityBaggageMiddleware öğesini ASP.NET Core işlem hattında kaydedin. HTTP bağlamından kiracı kimliğini ve aracı kimliğini ayıklayan bir çözümleyici işlevi sağlamanız gerekir.

using Microsoft.Agents.A365.Observability.Hosting.Middleware;

app.UseObservabilityRequestContext((httpContext) =>
{
    // Extract tenant and agent IDs from your request context
    var tenantId = GetTenantIdFromContext(httpContext);
    var agentId = GetAgentIdFromContext(httpContext);
    return (tenantId, agentId);
});

Token çözümleyici

Agent 365 dışa aktarıcısını kullandığınızda, kimlik doğrulama belirteonu döndüren bir token çözümleyici fonksiyonu sağlamanız gerekir. Agent 365 Observability SDK'yı Agent Hosting çerçevesi ile kullandığınızda, from aracı faaliyetlerini kullanarak TurnContext token oluşturabilirsiniz.

Python

Aşağıdaki kod örneği, microsoft_agents.hosting.core SDK kullanılarak bir token oluşturmanın nasıl yapılacağını gösterir. Burada oluşturulan kimlik doğrulama belirteci, span'lerin A365 veri alım servisine aktarılmasında kullanılır. Aracılar, örneğin Microsoft Authentication Library (MSAL) kullanarak, kendi tokenlarını oluşturabilirler; ancak, bu tokenın gözlemlenebilirlik kapsamına sahip olduğundan emin olmaları gerekir.

from microsoft_agents.activity import load_configuration_from_env
from microsoft_agents.authentication.msal import MsalConnectionManager
from microsoft_agents.hosting.aiohttp import CloudAdapter
from microsoft_agents.hosting.core import (
    AgentApplication,
    Authorization,
    MemoryStorage,
    TurnContext,
    TurnState,
)
from microsoft_agents_a365.runtime import (
    get_observability_authentication_scope,
)

agents_sdk_config = load_configuration_from_env(environ)

STORAGE = MemoryStorage()
CONNECTION_MANAGER = MsalConnectionManager(**agents_sdk_config)
ADAPTER = CloudAdapter(connection_manager=CONNECTION_MANAGER)
ADAPTER.use(TranscriptLoggerMiddleware(ConsoleTranscriptLogger()))
AUTHORIZATION = Authorization(STORAGE, CONNECTION_MANAGER, **agents_sdk_config)

AGENT_APP = AgentApplication[TurnState](
    storage=STORAGE, adapter=ADAPTER, authorization=AUTHORIZATION, **agents_sdk_config
)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    aau_auth_token = await AGENT_APP.auth.exchange_token(
                        context,
                        scopes=get_observability_authentication_scope(),
                        auth_handler_id="AGENTIC",
                    )
    # cache this auth token and return via token resolver

A365 CLI ile oluşturulmuş, bir AI takım arkadaşı ve Microsoft Agent 365 Observability Hosting Library paketini kullanan bir aracı için, token önbelleklemesini otomatik olarak yönetmek üzere AgenticTokenCache kullanın. Token'ı bir etkinlik işleyici sırasında her bir aracı ve kiracı için bir kez kaydedin ve gözlemlenebilirlik yapılandırmanızda cache.get_observability_token'i token_resolver parametresi olarak geçirin.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.hosting.token_cache_helpers import (
    AgenticTokenCache,
    AgenticTokenStruct,
)
from microsoft_agents_a365.runtime import get_observability_authentication_scope

# Create a shared cache instance
token_cache = AgenticTokenCache()

# Use the cache as your token resolver in configure()
configure(
    service_name="my-agent-service",
    service_namespace="my.namespace",
    token_resolver=token_cache.get_observability_token,
)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    token_cache.register_observability(
        agent_id="agent-456",
        tenant_id="tenant-123",
        token_generator=AgenticTokenStruct(
            authorization=AGENT_APP.auth,
            turn_context=context,
        ),
        observability_scopes=get_observability_authentication_scope(),
    )

JavaScript

Aşağıdaki kod örneği, @microsoft/agents-hosting SDK kullanılarak bir token oluşturmanın nasıl yapılacağını gösterir. Burada oluşturulan kimlik doğrulama belirteci, span'lerin A365 veri alım servisine aktarılmasında kullanılır. Aracılar, örneğin Microsoft Authentication Library (MSAL) kullanarak, kendi tokenlarını oluşturabilirler; ancak, bu tokenın gözlemlenebilirlik kapsamına sahip olduğundan emin olmaları gerekir.

import {
  TurnState,
  AgentApplication,
  MemoryStorage,
  TurnContext,
} from '@microsoft/agents-hosting';
import { ActivityTypes } from '@microsoft/agents-activity';
import { getObservabilityAuthenticationScope } from '@microsoft/agents-a365-runtime';

interface ConversationState {
  count: number;
}
type ApplicationTurnState = TurnState<ConversationState>;

const storage = new MemoryStorage();

export const agentApplication = new AgentApplication<ApplicationTurnState>({
  authorization: {
    agentic: {}, // We have the type and scopes set in the .env file
  },
  storage,
});

agentApplication.onActivity(
  ActivityTypes.Message,
  async (context: TurnContext, state: ApplicationTurnState) => {
    const aauAuthToken = await agentApplication.authorization.exchangeToken(context, 'agentic', {
      scopes: getObservabilityAuthenticationScope()
    });
    // cache this auth token and return via token resolver
  }
);

A365 CLI ile oluşturulmuş, bir AI takım arkadaşı ve @microsoft/agents-a365-observability-hosting paketini kullanan bir aracı için, token önbelleklemesini otomatik olarak yönetmek üzere AgenticTokenCacheInstance kullanın. Her bir aracı ve kiracı için, bir etkinlik işleyicisi sırasında RefreshObservabilityToken'yi bir kez çağırın ve gözlemlenebilirlik yapılandırmanızda AgenticTokenCacheInstance.getObservabilityToken’yi tokenResolver olarak iletin.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { AgenticTokenCacheInstance } from '@microsoft/agents-a365-observability-hosting';
import { getObservabilityAuthenticationScope } from '@microsoft/agents-a365-runtime';

// Use the cache as your token resolver in configure()
const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withTokenResolver((agentId, tenantId) =>
      AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId)
    )
);

builder.start();

agentApplication.onActivity(
  ActivityTypes.Message,
  async (context: TurnContext, state: ApplicationTurnState) => {
    const agentId = context.activity.recipient?.agenticAppId || '';
    const tenantId = context.activity.recipient?.tenantId || '';

    await AgenticTokenCacheInstance.RefreshObservabilityToken(
      agentId,
      tenantId,
      context,
      agentApplication.authorization,
      getObservabilityAuthenticationScope()
    );
  }
);

.NET

Aşağıdaki kod parçası, Microsoft.Agents barındırma SDK'sı kullanılarak bir kimlik doğrulama tokenı oluşturmanın yolunu gösteriyor. Oluşturduğunuz kimlik doğrulama tokenını kullanarak span’leri A365 alım servisine aktarın. Aracılar, örneğin Microsoft Authentication Library (MSAL) kullanarak, kendi tokenlarını oluşturabilirler; ancak, bu tokenın gözlemlenebilirlik kapsamına sahip olduğundan emin olmaları gerekir.

Agent365ExporterOptions'i bir TokenResolver Temsilcisi ile kaydederek bir belirteç çözümleyici sağlayın. Delege, agentId ve tenantId’yi alır ve bir kimlik doğrulama belirteci döndürür.

using Microsoft.Agents.A365.Observability.Runtime.Tracing.Exporters;

builder.Services.AddSingleton(sp =>
    {
        return new Agent365ExporterOptions
        {
            TokenResolver = async (agentId, tenantId) =>
            {
                // Implement your token retrieval logic here
                return await GetTokenAsync(agentId, tenantId);
            }
        };
    });

A365 CLI ile oluşturulmuş, bir AI takım arkadaşı ve Microsoft.Agents.A365.Observability.Hosting NuGet paketi kullanan bir aracı için, token önbelleğini bağımlılık enjeksiyonu yoluyla otomatik olarak yönetmek için AddAgenticTracingExporter() yöntemini kullanabilirsiniz.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

Aracı uygulamasında tokenı kaydet.

using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.App.UserAuth;
using Microsoft.Extensions.Logging;
using Microsoft.Agents.A365.Observability.Hosting.Caching;
using Microsoft.Agents.A365.Observability.Runtime.Common;
using System;
using System.Threading.Tasks;

public class MyAgent : AgentApplication
{
    private readonly IExporterTokenCache<AgenticTokenStruct> _agentTokenCache;
    private readonly ILogger<MyAgent> _logger;

    public MyAgent(AgentApplicationOptions options, IExporterTokenCache<AgenticTokenStruct> agentTokenCache, ILogger<MyAgent> logger)
        : base(options)
    {
        _agentTokenCache = agentTokenCache ?? throw new ArgumentNullException(nameof(agentTokenCache));
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
    }

    protected async Task MessageActivityAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        using var baggageScope = new BaggageBuilder()
            .TenantId(turnContext.Activity.Recipient.TenantId)
            .AgentId(turnContext.Activity.Recipient.AgenticAppId)
            .Build();

        try
        {
            _agentTokenCache.RegisterObservability(
                turnContext.Activity.Recipient.AgenticAppId,
                turnContext.Activity.Recipient.TenantId,
                new AgenticTokenStruct(
                    userAuthorization: UserAuthorization,
                    turnContext: turnContext,
                    authHandlerName: "AGENTIC"
                ),
                EnvironmentUtils.GetObservabilityAuthenticationScope()
            );
        }
        catch (Exception ex)
        {
            _logger.LogWarning($"Error registering for observability: {ex.Message}");
        }
    }
}

Otomatik enstrümantasyon

Otomatik enstrümantasyon, aracıik çerçeveleri (SDK'lar) mevcut telemetri sinyallerini izler için otomatik dinler ve bunları Agent 365 gözlemlenebilirlik hizmetine iletir. Bu özellik, geliştiricilerin izleme kodunu manuel olarak yazma ihtiyacını ortadan kaldırır, kurulumu kolaylaştırır ve tutarlı performans takibi sağlar.

Önemli

Otomatik enstrümantasyon yalnızca standart OTel özelliklerini doldurur. Microsoft'a özel öznitelikleri BaggageBuilder aracılığıyla eklemeniz gerekir. Hangi özelliklerin eksik olduğunu görmek için, konsol span çıktınızı diferensial setin store loglarıyla doğrulayın.

Birden fazla SDK ve platform otomatik enstrümantasyonu destekler:

Platform	Desteklenen SDK'lar / Çerçeveler
.NET	Semantik Çekirdek, OpenAI, Agent Framework
Python	Semantik Çekirdek, OpenAI, Agent Framework, LangChain
Node.js	OpenAI, LangChain

Not

Otomatik enstrümantasyon desteği, platform ve SDK'nın uygulamasına bağlı olarak değişiklik gösterir.

Semantik Çekirdek

Otomatik enstrümantasyon için baggage oluşturucu kullanılması gerekir. Aracı ID'si ve kiracı kimliğini BaggageBuilder kullanarak ayarlayın.

Python

Paketi yükleyin.

pip install microsoft-agents-a365-observability-extensions-semantic-kernel

Gözlemlenebilirliği yapılandırın.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.extensions.semantickernel.trace_instrumentor import SemanticKernelInstrumentor

# Configure observability
configure(
    service_name="my-semantic-kernel-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
instrumentor = SemanticKernelInstrumentor()
instrumentor.instrument()

# Your Semantic Kernel code is now automatically traced

JavaScript

Semantik Çekirdek JavaScript ile desteklenmiyor.

.NET

Hizmet koleksiyonuna bağımlılıkları ekleyin.

using Microsoft.Agents.A365.Observability.Extensions.SemanticKernel;

builder.AddA365Tracing(configure: config => config.WithSemanticKernel());

BaggageBuilder kullanarak AgentId ve TenantId ayarlayın. ChatCompletionAgent oluştururken kullandığınız ID'nin, BaggageBuilder için ilettiğiniz aracı ID'siyle eşleştiğinden emin olun.

using Microsoft.Agents.A365.Observability.Extensions.SemanticKernel;
using Microsoft.Agents.A365.Observability.Runtime.Common;
public class MyAgent
{
    public async Task<AgentResponse> ProcessUserRequest(string userInput)
    {
      using var baggageScope = new BaggageBuilder()
          .AgentId(<your-agent-id>) // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. 
          .TenantId(<your-tenant-id>) // NOTE: This will be the tenant ID with which the TokenResolver delegate is invoked.
          .Build();
      
      var chatCompletionAgent = new ChatCompletionAgent
      {
          // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. Should match above.
          Id = <your-agent-id>,
          ...
      };
    }
}

OpenAI

Otomatik enstrümantasyon için baggage oluşturucu kullanılması gerekir. Aracı ID'si ve kiracı kimliğini BaggageBuilder kullanarak ayarlayın.

Python

Paketi yükleyin.

pip install microsoft-agents-a365-observability-extensions-openai

Gözlemlenebilirliği yapılandırın.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.extensions.openai import OpenAIAgentsTraceInstrumentor

# Configure observability
configure(
    service_name="my-openai-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
instrumentor = OpenAIAgentsTraceInstrumentor()
instrumentor.instrument()

# Your OpenAI Agents code is now automatically traced

JavaScript

Paketi yükleyin.

npm install @microsoft/agents-a365-observability-extensions-openai

Gözlemlenebilirliği yapılandırın.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { OpenAIAgentsTraceInstrumentor } from '@microsoft/agents-a365-observability-extensions-openai';

// Configure observability first
const sdk = ObservabilityManager.configure((builder) =>
  builder
    .withService('My Agent Service', '1.0.0')
);

// Create and enable the instrumentor
const instrumentor = new OpenAIAgentsTraceInstrumentor({
  enabled: true,
  tracerName: 'openai-agents-tracer',
  tracerVersion: '1.0.0'
});

sdk.start();

instrumentor.enable();

.NET

Hizmet koleksiyonuna bağımlılıkları ekleyin.

using Microsoft.Agents.A365.Observability.Extensions.OpenAI;

builder.AddA365Tracing(configure: config => config.WithOpenAI());

BaggageBuilder kullanarak AgentId ve TenantId ayarlayın. Araç çağrıları için, bir ChatToolCall örneği üzerinde Trace() kullanarak bir iz başlatın.

using Microsoft.Agents.A365.Observability.Extensions.OpenAI;
using Microsoft.Agents.A365.Observability.Runtime.Common;

public class MyAgent
{
    public async Task<AgentResponse> ProcessUserRequest(string userInput)
    {
      using var baggageScope = new BaggageBuilder()
          .AgentId(<your-agent-id>) // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. 
          .TenantId(<your-tenant-id>) // NOTE: This will be the tenant ID with which the TokenResolver delegate is invoked.
          .Build();
      
      // NOTE: This will be the agent and tenant ID with which the TokenResolver delegate will be invoked. 
      using var scope = chatToolCall.Trace(agentId: <your-agent-id>, <your-tenant-id>);
    }
}

Agent Framework

Otomatik enstrümantasyon için baggage oluşturucu kullanılması gerekir. Aracı ID'si ve kiracı kimliğini BaggageBuilder kullanarak ayarlayın.

Python

Paketi yükleyin.

pip install microsoft-agents-a365-observability-extensions-agent-framework

Gözlemlenebilirliği yapılandırın.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.extensions.agentframework import (
    AgentFrameworkInstrumentor,
)

# Configure observability
configure(
    service_name="AgentFrameworkTracingWithAzureOpenAI",
    service_namespace="AgentFrameworkTesting",
)

# Enable auto-instrumentation
AgentFrameworkInstrumentor().instrument()

JavaScript

Agent Framework JavaScript'te desteklenmiyor.

.NET

Hizmet koleksiyonuna bağımlılıkları ekleyin.

using Microsoft.Agents.A365.Observability.Extensions.AgentFramework;

builder.AddA365Tracing(configure: config => config.WithAgentFramework());

BaggageBuilder kullanarak AgentId ve TenantId ayarlayın.

using Microsoft.Agents.A365.Observability.Runtime.Common;

public class MyAgent : AgentApplication
{
    protected async Task MessageActivityAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
      using var baggageScope = new BaggageBuilder()
          .AgentId(<your-agent-id>) // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. 
          .TenantId(<your-tenant-id>) // NOTE: This will be the tenant ID with which the TokenResolver delegate is invoked.
          .Build();
    }
}

LangChain Çerçevesi

Not

LangChain çerçevesi için otomatik enstrümantasyon ayrıca LangGraph ve Deep Aracılar'i destekler. Aynı uzantı, bu çerçevelerden herhangi birine sahip olan aracılar için otomatik olarak telemetri yakalar.

Otomatik enstrümantasyon için baggage builder kullanılması gereklidir. Aracı ID'si ve kiracı kimliğini BaggageBuilder kullanarak ayarlayın.

Python

Paketi yükleyin.

pip install microsoft-agents-a365-observability-extensions-langchain

Gözlemlenebilirliği yapılandırın.

from microsoft_agents_a365.observability.core.config import configure
from microsoft_agents_a365.observability.extensions.langchain import CustomLangChainInstrumentor

# Configure observability
configure(
    service_name="my-langchain-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
CustomLangChainInstrumentor()

# Your LangChain code is now automatically traced

JavaScript

Paketi yükleyin.

npm install @microsoft/agents-a365-observability-extensions-langchain

Gözlemlenebilirliği yapılandırın.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { LangChainTraceInstrumentor } from '@microsoft/agents-a365-observability-extensions-langchain';
import * as LangChainCallbacks from '@langchain/core/callbacks/manager';

// Configure observability first
const sdk = ObservabilityManager.configure((builder) =>
  builder
    .withService('My Agent Service', '1.0.0')
);

sdk.start();

// Enable LangChain auto-instrumentation
LangChainTraceInstrumentor.instrument(LangChainCallbacks);

// Your LangChain code is now automatically traced

.NET

LangChain, .NET'te desteklenmiyor.

Manuel Enstrümantasyon

Aracının iç işleyişini anlamak için Agent 365 gözlemlenebilirlik SDK'sını kullanın. SDK, başlatabileceğiniz kapsamlar sağlar: InvokeAgentScope, ExecuteToolScope, InferenceScope ve OutputScope.

Aracı çağırma

Bu kapsamı aracı sürecinizin başında kullanın. Aracı çağırma kapsamını kullanarak, çağrılan mevcut aracı, aracı kullanıcı verileri ve benzeri özellikleri yakalayabilirsiniz.

Python

from microsoft_agents_a365.observability.core import (
    InvokeAgentScope,
    InvokeAgentScopeDetails,
    AgentDetails,
    CallerDetails,
    UserDetails,
    Channel,
    Request,
    ServiceEndpoint,
)

agent_details = AgentDetails(
    agent_id="agent-456",
    agent_name="My Agent",
    agent_description="An AI agent powered by Azure OpenAI",
    agentic_user_id="auid-123",
    agentic_user_email="agent@contoso.com",
    agent_blueprint_id="blueprint-789",
    tenant_id="tenant-123",
)

scope_details = InvokeAgentScopeDetails(
    endpoint=ServiceEndpoint(hostname="myagent.contoso.com", port=443),
)

request = Request(
    content="User asks a question",
    session_id="session-42",
    conversation_id="conv-xyz",
    channel=Channel(name="msteams"),
)

caller_details = CallerDetails(
    user_details=UserDetails(
        user_id="user-123",
        user_email="jane.doe@contoso.com",
        user_name="Jane Doe",
    ),
)

with InvokeAgentScope.start(request, scope_details, agent_details, caller_details):
    # Perform agent invocation logic
    response = call_agent(...)

JavaScript

import {
  InvokeAgentScope,
  InvokeAgentScopeDetails,
  AgentDetails,
  CallerDetails,
  UserDetails,
  Channel,
  Request,
  ServiceEndpoint,
} from '@microsoft/agents-a365-observability';

// Use the same agentDetails instance across all scopes in a request
const agentDetails: AgentDetails = {
  agentId: 'agent-456',
  agentName: 'Email Assistant',
  agentDescription: 'An AI agent powered by Azure OpenAI',
  agentAuid: 'auid-123',
  agentEmail: 'agent@contoso.com',
  agentBlueprintId: 'blueprint-789',
  tenantId: 'tenant-123',
};

const scopeDetails: InvokeAgentScopeDetails = {
  endpoint: { host: 'myagent.contoso.com', port: 443 } as ServiceEndpoint,
};

// Use the same request instance across all scopes in a request
const request: Request = {
  content: 'Please help me organize my emails',
  sessionId: 'session-42',
  conversationId: 'conv-xyz',
  channel: { name: 'msteams' } as Channel,
};

// Optional: Caller details (human user, or agent-to-agent)
const callerDetails: CallerDetails = {
  userDetails: {
    userId: 'user-123',
    userEmail: 'jane.doe@contoso.com',
    userName: 'Jane Doe',
  } as UserDetails,
};

const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails, callerDetails);

try {
  await scope.withActiveSpanAsync(async () => {
    // Record input messages
    scope.recordInputMessages(['Please help me organize my emails', 'Focus on urgent items']);

    // Your agent invocation logic here
    const response = await invokeAgent(request.content);

    // Record output messages
    scope.recordOutputMessages(['I found 15 urgent emails', 'Here is your organized inbox']);
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

Eğer aracınız @microsoft/agents-a365-observability-hosting paketini kullanıyorsa, aracı detayları, arayan detayları ve kanal bilgileri TurnContext'den otomatik olarak türetilerek kapsamı oluşturmak için ScopeUtils.populateInvokeAgentScopeFromTurnContext kullanabilirsiniz.

import { InvokeAgentScopeDetails, AgentDetails, ServiceEndpoint } from '@microsoft/agents-a365-observability';
import { ScopeUtils } from '@microsoft/agents-a365-observability-hosting';

const agentDetails: AgentDetails = { agentId: 'agent-456' };
const scopeDetails: InvokeAgentScopeDetails = {
  endpoint: { host: 'myagent.contoso.com', port: 443 } as ServiceEndpoint,
};

const scope = ScopeUtils.populateInvokeAgentScopeFromTurnContext(
  agentDetails,
  scopeDetails,
  context,     // TurnContext
  authToken    // authentication token string
);

try {
  await scope.withActiveSpanAsync(async () => {
    // Agent details, caller details, and channel are auto-populated from context
    const response = await invokeAgent(context.activity.text);
    scope.recordOutputMessages([response]);
  });
} finally {
  scope.dispose();
}

.NET

using System;
using System.Threading.Tasks;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

public class MyAgent
{
    public async Task<AgentResponse> ProcessUserRequest(string userInput)
    {
        var agentDetails = new AgentDetails(
            agentId: "agent-456",
            agentName: "MyAgent",
            agentDescription: "Handles user requests.",
            agenticUserId: "auid-123",
            agenticUserEmail: "agent@contoso.com",
            agentBlueprintId: "blueprint-789",
            tenantId: "tenant-123"
        );

        var scopeDetails = new InvokeAgentScopeDetails(
            endpoint: new Uri("https://myagent.contoso.com")
        );

        var request = new Request(
            content: userInput,
            sessionId: "session-abc",
            channel: new Channel("msteams"),
            conversationId: "conv-xyz"
        );

        var callerDetails = new CallerDetails(
            userDetails: new UserDetails(
                userId: "user-123",
                userEmail: "jane.doe@contoso.com",
                userName: "Jane Doe"
            )
        );

        // Start the scope
        using var scope = InvokeAgentScope.Start(
            request: request,
            scopeDetails: scopeDetails,
            agentDetails: agentDetails,
            callerDetails: callerDetails
        );

        // Record input messages
        scope.RecordInputMessages(new[] { userInput });

        // ... your agent logic here ...

        var output = $"Processed: {userInput}";
        scope.RecordOutputMessages(new[] { output });

        return new AgentResponse { Content = output };
    }
}

public class AgentResponse
{
    public string Content { get; set; }
}

Araç çalıştırma

Aşağıdaki örnekler, aracınızın araç çalıştırmasına gözlemlenebilirlik takibi eklemenin nasıl yapılacağını gösterir. Bu izleme, izleme ve denetim amacıyla telemetri yakalar.

Python

from microsoft_agents_a365.observability.core import (
    ExecuteToolScope,
    ToolCallDetails,
    Request,
    ServiceEndpoint,
)

# Use the same agent_details and request instances from the InvokeAgentScope example above

tool_details = ToolCallDetails(
    tool_name="summarize",
    tool_type="function",
    tool_call_id="tc-001",
    arguments="{'text': '...'}",
    description="Summarize provided text",
    endpoint=ServiceEndpoint(hostname="tools.contoso.com", port=8080),
)

with ExecuteToolScope.start(request, tool_details, agent_details) as scope:
    result = run_tool(tool_details)
    scope.record_response(result)

JavaScript

import { ExecuteToolScope, ToolCallDetails } from '@microsoft/agents-a365-observability';

// Use the same agentDetails and request instances from the InvokeAgentScope example above

const toolDetails: ToolCallDetails = {
  toolName: 'email-search',
  arguments: JSON.stringify({ query: 'from:boss@company.com', limit: 10 }),
  toolCallId: 'tool-call-456',
  description: 'Search emails by criteria',
  toolType: 'function',
  endpoint: {
    host: 'tools.contoso.com',
    port: 8080,  // Will be recorded since not 443
    protocol: 'https'
  },
};

const scope = ExecuteToolScope.start(request, toolDetails, agentDetails);

try {
  return await scope.withActiveSpanAsync(async () => {
    // Execute the tool
    const result = await searchEmails(toolDetails.arguments);

    // Record the tool execution result
    scope.recordResponse(result);

    return result;
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

Eğer aracınız @microsoft/agents-a365-observability-hosting paketini kullanıyorsa, kapsamı TurnContext'ten otomatik olarak türetilen aracı detaylarıyla ScopeUtils.populateExecuteToolScopeFromTurnContext kullanarak oluşturun.

import { ToolCallDetails } from '@microsoft/agents-a365-observability';
import { ScopeUtils } from '@microsoft/agents-a365-observability-hosting';

const toolDetails: ToolCallDetails = {
  toolName: 'email-search',
  arguments: JSON.stringify({ query: 'from:boss@company.com' }),
  toolCallId: 'tool-call-456',
  toolType: 'function',
};

const scope = ScopeUtils.populateExecuteToolScopeFromTurnContext(
  toolDetails,
  context,     // TurnContext
  authToken    // authentication token string
);

try {
  await scope.withActiveSpanAsync(async () => {
    const result = await searchEmails(toolDetails.arguments);
    scope.recordResponse(JSON.stringify(result));
  });
} finally {
  scope.dispose();
}

.NET

using System;
using System.Threading.Tasks;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

// Use the same agentDetails and request instances from the InvokeAgentScope example above

var toolCallDetails = new ToolCallDetails(
    toolName: "summarize",
    arguments: "{\"text\": \"...\"}",
    toolCallId: "tc-001",
    description: "Summarize provided text",
    toolType: "function",
    endpoint: new Uri("https://tools.contoso.com:8080")
);

using var scope = ExecuteToolScope.Start(
    request: request,
    details: toolCallDetails,
    agentDetails: agentDetails
);

// ... your tool logic here ...

scope.RecordResponse("{\"summary\": \"The text was summarized.\"}");

Çıkarım

Aşağıdaki örnekler, yapay zeka model çıkarım çağrılarını gözlemlenebilirlik takibiyle enstrümante ederek token kullanımı, model detayları ve yanıt meta verilerini nasıl yakalayacağınızı gösterir.

Python

from microsoft_agents_a365.observability.core import (
    InferenceScope,
    InferenceCallDetails,
    InferenceOperationType,
)

# Use the same agent_details and request instances from the InvokeAgentScope example above

inference_details = InferenceCallDetails(
    operationName=InferenceOperationType.CHAT,
    model="gpt-4o-mini",
    providerName="azure-openai",
    inputTokens=123,
    outputTokens=456,
    finishReasons=["stop"],
)

with InferenceScope.start(request, inference_details, agent_details) as scope:
    completion = call_llm(...)
    scope.record_output_messages([completion.text])
    scope.record_input_tokens(completion.usage.input_tokens)
    scope.record_output_tokens(completion.usage.output_tokens)

JavaScript

import { InferenceScope, InferenceDetails, InferenceOperationType } from '@microsoft/agents-a365-observability';

// Use the same agentDetails and request instances from the InvokeAgentScope example above

const inferenceDetails: InferenceDetails = {
  operationName: InferenceOperationType.CHAT,
  model: 'gpt-4o-mini',
  providerName: 'azure-openai',
};

const scope = InferenceScope.start(request, inferenceDetails, agentDetails);

try {
  return await scope.withActiveSpanAsync(async () => {
    // Record input messages
    scope.recordInputMessages(['Summarize the following emails for me...']);

    // Call the LLM
    const response = await callLLM();

    // Record detailed telemetry with granular methods
    scope.recordOutputMessages(['Here is your email summary...']);
    scope.recordInputTokens(145);
    scope.recordOutputTokens(82);
    scope.recordFinishReasons(['stop']);

    return response.text;
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

Aracınız @microsoft/agents-a365-observability-hosting paketini kullanıyorsa, kapsamı aracı detayları TurnContext üzerinden otomatik olarak türetilerek ScopeUtils.populateInferenceScopeFromTurnContext ile oluşturabilirsiniz.

import { InferenceDetails, InferenceOperationType } from '@microsoft/agents-a365-observability';
import { ScopeUtils } from '@microsoft/agents-a365-observability-hosting';

const inferenceDetails: InferenceDetails = {
  operationName: InferenceOperationType.CHAT,
  model: 'gpt-4o-mini',
  providerName: 'azure-openai',
};

const scope = ScopeUtils.populateInferenceScopeFromTurnContext(
  inferenceDetails,
  context,     // TurnContext
  authToken    // authentication token string
);

try {
  await scope.withActiveSpanAsync(async () => {
    const response = await callLLM();
    scope.recordOutputMessages([response.text]);
    scope.recordInputTokens(response.usage.inputTokens);
    scope.recordOutputTokens(response.usage.outputTokens);
  });
} finally {
  scope.dispose();
}

.NET

using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

// Use the same agentDetails and request instances from the InvokeAgentScope example above

var inferenceDetails = new InferenceCallDetails(
    operationName: InferenceOperationType.Chat,
    model: "gpt-4o-mini",
    providerName: "Azure OpenAI",
    inputTokens: 123,
    outputTokens: 456,
    finishReasons: new[] { "stop" }
);

using var scope = InferenceScope.Start(
    request: request,
    details: inferenceDetails,
    agentDetails: agentDetails
);

// ... your inference logic here ...

scope.RecordOutputMessages(new[] { "AI response message" });
scope.RecordInputTokens(123);
scope.RecordOutputTokens(456);

Çıktı

Bu kapsamı, InvokeAgentScope, ExecuteToolScope veya InferenceScope çıktı verisini senkron olarak yakalayamıyorsa asenkron senaryolarda kullanın. OutputScope'i, üst öğe kapsamı tamamlandıktan sonra nihai çıktı mesajlarını kaydetmek için bir alt öğe span olarak başlatın.

Python

from microsoft_agents_a365.observability.core import (
    OutputScope,
    Response,
    SpanDetails,
)

# Use the same agent_details and request instances from the InvokeAgentScope example above

# Get the parent context from the originating scope
parent_context = invoke_scope.get_context()

response = Response(messages=["Here is your organized inbox with 15 urgent emails."])

with OutputScope.start(
    request,
    response,
    agent_details,
    span_details=SpanDetails(parent_context=parent_context),
):
    # Output messages are recorded automatically from the response
    pass

JavaScript

import { OutputScope, OutputResponse, SpanDetails } from '@microsoft/agents-a365-observability';

// Use the same agentDetails and request instances from the InvokeAgentScope example above

// Get the parent context from the originating scope
const parentContext = invokeScope.getSpanContext();

const response: OutputResponse = {
  messages: ['Here is your organized inbox with 15 urgent emails.'],
};

const scope = OutputScope.start(
  request,
  response,
  agentDetails,
  undefined, // userDetails
  { parentContext } as SpanDetails
);

// Output messages are recorded automatically from the response
scope.dispose();

.NET

using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

// Use the same agentDetails and request instances from the InvokeAgentScope example above

// Get the parent context from the originating scope
var parentContext = invokeScope.GetActivityContext();

var response = new Response(new[] { "Here is your organized inbox with 15 urgent emails." });

using var scope = OutputScope.Start(
    request: request,
    response: response,
    agentDetails: agentDetails,
    spanDetails: new SpanDetails(parentContext: parentContext)
);
// Output messages are recorded automatically from the response

Yerel doğrulama

Gözlemlenebilirlik SDK'sı ile başarılı bir şekilde entegre olup olmadığınızı doğrulamak için, aracınız tarafından oluşturulan konsol günlüklerini ve gözlemlenebilirlik SDK'sının günlüklerini inceleyin.

Python

ENABLE_A365_OBSERVABILITY_EXPORTER ortam değişkenini false olarak ayarlayın. Bu ayar, span'ları (izler, traces) konsola yazdırır.

Dışa aktarma hatalarını araştırmak için, ENABLE_A365_OBSERVABILITY_EXPORTER ortam değişkenini true olarak ayarlayın ve uygulamanızın başlangıcında debug kaydını yapılandırarak ayrıntılı kaydı etkinleştirin:

import logging

logging.basicConfig(level=logging.DEBUG)
logging.getLogger("microsoft_agents_a365.observability.core").setLevel(logging.DEBUG)

# Or target only the exporter:
logging.getLogger(
    "microsoft_agents_a365.observability.core.exporters.agent365_exporter"
).setLevel(logging.DEBUG)

Ana günlük mesajları:

DEBUG  Token resolved for agent {agentId} tenant {tenantId}
DEBUG  Exporting {n} spans to {url}
DEBUG  HTTP 200 - correlation ID: abc-123
ERROR  Token resolution failed: {error}
ERROR  HTTP 401 exporting spans - correlation ID: abc-123
INFO   No spans with tenant/agent identity found; nothing exported.

JavaScript

ENABLE_A365_OBSERVABILITY_EXPORTER ortam değişkenini false olarak ayarlayın. Bu ayar, span'ları (izler, traces) konsola yazdırır.

Dışa aktarma hatalarını incelemek için, ortam değişkenlerini .env veya kabukta ayarlayın.

# Enable the Agent365 exporter
ENABLE_A365_OBSERVABILITY_EXPORTER=true

# Enable verbose logging
A365_OBSERVABILITY_LOG_LEVEL=info|warn|error

Konsol çıktısında aşağıdaki gibi mesajları kontrol edin:

[INFO]  [Agent365Exporter] Exporting 245 spans
[INFO]  [Agent365Exporter] Partitioned into 3 identity groups (2 spans skipped)
[INFO]  [Agent365Exporter] Token resolved successfully via tokenResolver
[EVENT] export-group succeeded in 98ms {"tenantId":"...","agentId":"...","correlationId":"abc-123"}
[ERROR] [Agent365Exporter] Failed with status 401, correlation ID: abc-123
[WARN]  export-partition-span-missing-identity: 5 spans skipped due to missing tenant or agent ID

İsteğe bağlı olarak, dışa aktarma olaylarını bir dosyaya kaydetmek için özel bir logger kullanabilirsiniz:

import { setLogger, ExporterEventNames } from '@microsoft/agents-a365-observability';

setLogger({
  info: (msg, ...args) => myLogger.info(msg, ...args),
  warn: (msg, ...args) => myLogger.warn(msg, ...args),
  error: (msg, ...args) => myLogger.error(msg, ...args),
  event: (eventType: ExporterEventNames, isSuccess: boolean, durationMs: number,
          message?: string, details?: Record<string, string>) => {
    myLogger.info({ eventType, isSuccess, durationMs, message, ...details });
  }
});

.NET

EnableAgent365Exporter değerini false olarak appsettings.json içinde ayarlayın. Bu ayar, span'ları (izler, traces) konsola yazdırır.

Dışa aktarma hatalarını incelemek için, ayrıntılı günlük kaydını appsettings.json'de yapılandırın.

{
  "EnableAgent365Exporter": "True",
  "Logging": {
    "LogLevel": {
      "Microsoft.Agents.A365.Observability": "Debug"
    }
  }
}

Veya ortam değişkenlerini ayarlayın:

EnableAgent365Exporter=True
A365_OBSERVABILITY_DOMAIN_OVERRIDE=https://your-test-endpoint.example.com
A365_OBSERVABILITY_SCOPE_OVERRIDE=https://api.powerplatform.com/.default

Ana günlük mesajları:

info: Agent365ExporterCore: Obtained token for agent {agentId} tenant {tenantId}.
info: Agent365ExporterCore: Sending {count} spans to {requestUri} for agent {agentId} tenant {tenantId}.
info: Agent365ExporterCore: HTTP {statusCode} exporting spans. 'x-ms-correlation-id': '{correlationId}'.
error: Agent365Exporter: Exception exporting spans: {exception}
warn: Agent365ExporterCore: No token obtained for agent {agentId} tenant {tenantId}. Skipping export.

Not

Eğer ILoggerFactory'i DI'ya kaydetmezseniz, dışa aktarıcı otomatik olarak konsol logger'a geri döner.

Dışa aktarılmış günlükleri görüntüleme

Aracı telemetrisi verilerini Microsoft Purview veya Microsoft Defender'da görüntülemek için aşağıdaki gereksinimlerin karşılandığından emin olun:

• Microsoft Purview: Kuruluşunuz için denetim açık olması gerekir. Yönergeler için bkz. Denetimi açma veya kapatma.
• Microsoft Defender: CloudAppEvents tablosuna erişmek için gelişmiş aramaya ilişkin konfigürasyon yapılması gerekir. Ayrıntılar için bkz. Gelişmiş arama şemasında CloudAppEvents tablosu.

Store'da yayınlama için doğrulama

Önemli

Mağaza doğrulamasının başarılı olması için aracınızın InvokeAgentScope, InferenceScope ve ExecuteToolScope kapsamlarını uygulaması gerekir. Bu üç kapsam yayınlama için gereklidir.

Yayınlamadan önce, gerekli invoke agent, execute tool, inference ve output kapsamlarını uygulayarak konsol loglarını kullanın ve aracınızın gözlemlenebilirlik entegrasyonunu doğrulayın. Ardından, gerekli tüm özniteliklerin mevcut olduğunu doğrulamak için aracınızın günlüklerini aşağıdaki öznitelik listeleriyle karşılaştırın. Her kapsamda veya baggage builder aracılığıyla öznitelikleri yakalayın ve isteğe bağlı öznitelikleri tercihinize göre ekleyin.

Store yayınlama gereksinimleri hakkında daha fazla bilgi için Store doğrulama yönergelerini inceleyin.

InvokeAgentScope öznitelikleri

Aşağıdaki liste, bir InvokeAgentScope başlatıldığında kaydedilen gerekli ve isteğe bağlı telemetri özniteliklerini özetlemektedir.

"attributes": {
        "error.type": "Optional",
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "microsoft.a365.caller.agent.blueprint.id": "Optional",
        "microsoft.a365.caller.agent.id": "Optional",
        "microsoft.a365.caller.agent.name": "Optional",
        "microsoft.a365.caller.agent.platform.id": "Optional",
        "microsoft.a365.caller.agent.user.email": "Optional",
        "microsoft.a365.caller.agent.user.id": "Optional",
        "microsoft.a365.caller.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.input.messages": "Required",
        "gen_ai.operation.name": "Required",
        "gen_ai.output.messages": "Required",
        "server.address": "Required",
        "server.port": "Required",
        "microsoft.session.id": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.tenant.id": "Required"
    }

ExecuteToolScope öznitelikleri

Aşağıdaki liste, bir ExecuteToolScope başlatıldığında kaydedilen gerekli ve isteğe bağlı telemetri özniteliklerini özetlemektedir.

"attributes": {
        "error.type": "Optional",
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.operation.name": "Required",
        "gen_ai.tool.call.arguments": "Required",
        "gen_ai.tool.call.id": "Required",
        "gen_ai.tool.call.result": "Required",
        "gen_ai.tool.description": "Optional",
        "gen_ai.tool.name": "Required",
        "gen_ai.tool.type": "Required",
        "server.address": "Optional",
        "server.port": "Optional",
        "microsoft.session.id": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.tenant.id": "Required"
    }

InferenceScope öznitelikleri

Aşağıdaki liste, bir InferenceScope başlatıldığında kaydedilen gerekli ve isteğe bağlı telemetri özniteliklerini özetlemektedir.

"attributes": {
        "error.type": "Optional",
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.a365.agent.thought.process": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.input.messages": "Required",
        "gen_ai.operation.name": "Required",
        "gen_ai.output.messages": "Required",
        "gen_ai.provider.name": "Required",
        "gen_ai.request.model": "Required",
        "gen_ai.response.finish_reasons": "Optional",
        "gen_ai.usage.input_tokens": "Optional",
        "gen_ai.usage.output_tokens": "Optional",
        "server.address": "Optional",
        "server.port": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.session.id": "Optional",
        "microsoft.tenant.id": "Required"
    }

OutputScope öznitelikleri

Aşağıdaki liste, bir OutputScope başlatıldığında kaydedilen gerekli ve isteğe bağlı telemetri özniteliklerini özetlemektedir. Bu kapsamı, üst öğe kapsamının çıktı verisini eşzamanlı olarak kaydedemediği asenkron senaryolar için kullanın.

"attributes": {
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.operation.name": "Required",
        "gen_ai.output.messages": "Required",
        "microsoft.session.id": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.tenant.id": "Required"
    }

Aracınızı gözlemlenebilirlikle test edin

Aracınızda gözlemlenebilirliği uyguladıktan sonra, telemetriyi doğru şekilde yakaladığından emin olmak için test edin. Ortamınızı kurmak için test rehberini takip edin. Ardından, gözlemlenebilirlik uygulamanızın doğru çalıştığını doğrulamak için öncelikle Gözlemlenebilirlik günlüklerini görüntüle bölümüne odaklanın.

Doğrulama:

• Şuraya gidin: https://admin.cloud.microsoft/#/agents/all
• Aracınızı seçin > Aktivite
• Oturumları ve araç çağrılarını görüyorsunuz

Sorun giderme

Bu bölüm, gözlemlenebilirliği uygularken ve kullanırken karşılaşılan yaygın sorunları ele alır.

Sorun	Açıklama
Gözlemlenebilirlik verileri görünmüyor	Herhangi bir telemetri görünmüyor; çünkü dışa aktarma etkin değil, yapılandırma yanlış veya token çözümlemesi başarısız oluyor.
Kiracı kimliği veya aracı kimliği eksik - yayılmalar atlandı	Bölümleme için gerekli kimlik nitelikleri eksikse, spanlar dışa aktarmadan önce atılır.
Belirteç çözümü başarısızlığı - dışarı aktarma atlandı veya yetkisiz	Dışa aktarma talepleri, çözümleyici bir token döndürmezse veya bir istisna ile karşılaşırsa başarısızlıkla sonuçlanır veya atlanır.
HTTP 401 Yetkisiz	Kimlik doğrulama sözdizimsel olarak başarılı olur, ancak token kapsamı, türü veya geçerlilik süresi nedeniyle sisteme alınamaz.
HTTP 403 Yasak	Kiracı lisans eksiklikleri veya gözlemlenebilirlik izinlerinin eksikliği nedeniyle erişim reddedilir.
HTTP 403 Yasak - Aracı Kimliği uyuşmazlığı	İstek, URL'deki aracı kimliği ile token tarafından temsil edilen kimlik uyuşmadığında reddedilir.
HTTP 429 veya 5xx hataları - Geçici hatalar	Geçici sınırlandırma veya servis tarafı arızaları dışa aktarmayı kesintiye uğratır ve yeniden deneme yapılandırması gerekebilir.
Dışa aktarma zaman aşımı	Telemetri paketleri, ağ gecikmesi veya uç nokta yanıt hızından dolayı yapılandırılmış zaman aşım pencerelerini aşar.
Dışa aktarım başarılı olur ancak telemetri Defender veya Purview'da görünmez	Alım tamamlanır, ancak sonraki görünürlük ürün önkoşulları nedeniyle gecikir veya engellenir.

İpucu

Agent 365 Sorun Giderme Kılavuzu yüksek seviyeli sorun giderme önerileri, en iyi uygulamalar ve Agent 365 geliştirme yaşam döngüsünün her aşamasına yönelik sorun giderme içeriğine bağlantılar sunar.

Gözlemlenebilirlik verileri görünmüyor

Belirtiler:

• Aracı çalışıyor
• Yönetim merkezinde telemetri yok
• Aracı etkinliğini göremiyorsunuz

Temel Neden:

• Gözlemlenebilirlik etkinleştirilmemiş
• Yapılandırma hataları
• Belirteç çözümleyici sorunları

Çözümler: Sorunu çözmek için aşağıdaki adımları deneyin:

• Gözlemlenebilirlik dışa aktarıcısının etkin olduğunu doğrulayın

  Agent 365 dışa aktarıcısını açıkça etkinleştirmeniz gerekir. Devre dışı bırakıldığında, SDK konsol dışa aktarıcısına geri dönüyor ve telemetri servise gönderilmiyor. Yapılandırma ayrıntıları için Yapılandırma bölümüne bakın.

• Belirteç çözümleyici yapılandırmasını kontrol edin

  Dışa aktarıcı, her dışa aktarma isteği için bir Bearer belirteci döndüren geçerli bir belirteç çözümleyici gerektirir. Belirteç çözümleyici eksikse veya null döndürürse, dışa aktarma sessizce atlanır. Kodunuzun token çözümleyiciyi doğru şekilde entegre ettiğinden emin olun. Detaylar için Belirteç düzenleyici bölümüne bakınız.

• Günlüklerde hata olup olmadığını kontrol edin

  Ayrıntılı loglamayı etkinleştirin ve gözlemlenebilirlik ile ilgili hataları loglarda aramak için az webapp log tail komutunu kullanın. Her platformda loglamayı nasıl etkinleştireceğiniz hakkında ayrıntılar için Yerel doğrulama bölümüne bakınız.

  # Look for observability-related errors
  az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"
  

• Telemetri dışa aktarımını doğrulayın

  Telemetri beklendiği gibi üretilip dışa aktarıldığını doğrulayın.

  • Bir konsol dışa aktarıcısı ekleyin ve telemetri yerel olarak üretilip üretilmediğini kontrol edin. Konsol dışa aktarıcısını nasıl kullanacağınız ve çıktıyı nasıl doğrulayacağınız hakkında detaylar için Yerel Doğrulama bölümüne bakınız.

Kiracı kimliği veya aracı kimliği eksik — yayılımlar atlandı

Belirtiler: Sistem yayılımları sessizce bırakır ve bunları hiçbir zaman dışa aktarmaz. Bazı SDK'lar atlanan span'ların sayısını veya "Kiracı/aracı kimliğiyle span bulunamadı" şeklinde bir mesajı kaydeder. Diğerleri ise herhangi bir kayıt tutmadan atlar.

Çözüm:

• Dışa aktarma öncesinde, SDK span'leri kiracı ve aracı kimliğine göre ayırır. Sistem, kiracı kimliği veya aracı kimliği olmayan span'leri düşürür ve bunları asla servise göndermez.
• BaggageBuilder öğesinin yayılımlar oluşturmadan önce kiracı kimliği ve aracı kimliği ile ayarlandığından emin olun. Bu değerler OpenTelemetry bağlamı aracılığıyla yayılır ve bagaj kapsamı içinde oluşturulan tüm yayılımlara eklenir. Platform'a özgü API için bkz. Bagaj öznitelikleri.
• Baggage middleware'ı veya hosting entegrasyon paketindeki turn context helper'ı kullanarak bu kimlikleri dolduruyorsanız, TurnContext etkinliğinin aracı kimliğine sahip geçerli bir alıcıya sahip olduğunu doğrulayın.

Belirteç çözümleme başarısızlığı — dışa aktarma atlandı veya yetkisiz

Belirtiler: Belirteç çözümleyici null döndürür veya bir hata oluşturur. SDK'ya bağlı olarak, dışa aktarma ya tamamen atlanır ya da istek yetkilendirme başlığı olmadan gönderilir ve HTTP 401 hatası ile başarısız olur.

Çözüm:

• Belirteç çözümleyici başlatma sırasında zorunludur. Eksikse, dışa aktarıcı başlangıçta bir hata oluşturur. Belirteç çözümleyicisinin sağlandığını ve geçerli bir Bearer belirteci döndürdüğünü doğrulayın.
• Doğru kiracı kimliği ve aracı kimliğinin BaggageBuilder için kullanıldığından emin olun, çünkü bu değerler token çözümcüsüne iletilir.
• Azure'da barındırılan aracılar için, Yönetilen Kimliğin gözlemlenebilirlik kapsamı için gerekli API izinlerine sahip olduğunu doğrulayın.

HTTP 401 Yetkisiz

Belirtiler: Dışa aktarma işlemi HTTP 401 hatası ile başarısız olur. Dışa aktarıcı bu hatayı yeniden denenmez.

Çözüm:

• Belirteç izleyicisinin gözlemlenebilirlik uç noktası kapsamı ile eşleştiğini doğrulayın.
• Belirteç çözümleyicisinin temsilci kullanıcı belirteci, yanlış izleyici için bir belirteç veya süresi dolmuş bir belirteç döndürmediğini kontrol edin.

HTTP 403 Yasak

Belirtiler: Dışa aktarma işlemi HTTP 403 hatası ile başarısız olur. Dışa aktarıcı bu hatayı yeniden denenmez.

Temel neden: HTTP 403 hatası farklı nedenlere sahip olabilir. Sırasıyla aşağıdaki çözümleri kontrol edin.

Çözüm:

• Eksik lisans — Kiracınızda Microsoft 365 yönetim merkezi içinde aşağıdaki lisanslardan birinin atandığını doğrulayın:

  • Test - Microsoft 365 E7
  • Microsoft 365 E7
  • Microsoft Agent 365 Frontier

• Eksik Agent365.Observability.OtelWrite izin — Eğer yakın zamanda gözlemlenebilirlik paketlerinizi yükselttiyseniz, bu izni vermeniz gerekir. Önemli notu bir sonraki bölümde inceleyin.

Önemli

Mevcut aracılar bu paket sürümlerine yükseltildiğinde ekstra bir adım gereklidir

Bu adım yalnızca mevcut aracıyı yükseltiyorsanız geçerlidir. Yeni aracı kurulumlarında bu adım gerekmez. Aşağıdaki paket sürümlerine veya daha yenilerine yükseltme yapıyorsanız, kimliğinize (Yönetilen Kimlik veya uygulama kaydı) yeni Agent365.Observability.OtelWrite iznini vermeniz gerekir. Bu izin olmadan, telemetri dışa aktarımı HTTP 403 hatasıyla başarısız olur.

Platform	Bu adımı gerektiren minimum sürüm
.NET	0.3-beta
Node.js	0.2.0-preview.1
Python	0.3.0

Aşağıdaki seçeneklerden birini kullanarak izni verin.

Seçenek A — Agent 365 CLI (Global Administrator hesabı gerektirir; a365.config.json içeren aracı proje dizininden çalıştırın veya --agent-name kullanın)

a365 setup permissions bot

Alternatif olarak, yapılandırma dosyası olmadan:

a365 setup permissions bot --agent-name "<agent-name>"

Bu komut, Observability kapsamları dahil olmak üzere blueprint'teki eksik tüm izinleri verir.

Seçenek B — Entra Portal (yapılandırma dosyası gerekmez; blueprint uygulaması kaydına Global Administrator erişimi gerektirir)

1. Entra portalına>Uygulama kayıtlarına> gidin ve Blueprint uygulamanızı seçin.
2. API izinleri>İzin ekle>Kuruluşumun kullandığı API'ler> öğesine gidin ve 9b975845-388f-4429-889e-eab1ef63949c arayın.
3. Temsilci izinleri> seçin, Agent365.Observability.OtelWrite> işaretleyin ve İzin ekle öğesine tıklayın.
4. 2-3. adımları tekrarlayın, bu sefer Uygulama izinleri> seçeneğini seçin ve Agent365.Observability.OtelWrite>İzin ekle seçeneğini işaretleyin.
5. Yönetici onayı ver öğesine tıklayın ve onaylayın.

Hem Agent365.Observability.OtelWrite (Delege) hem de Agent365.Observability.OtelWrite (Uygulama) Granted statüsünü göstermelidir.

HTTP 403 Yasak — Aracı Kimliği uyuşmazlığı

Belirtiler: HTTP 403 hatası ile dışa aktarma başarısız olur ve 403 Forbidden ile agent-ID-mismatch hatasına benzer bir sunucu iletisi gösterilir. Agent 365 izlemeleri uç noktalarını çağırırken bu hata oluşur.

Temel neden: Bu hata, aracı ayrıntılarını ayarlarken aracı örneği istemci kimliği yerine şema istemci kimliği kullandığınızda oluşur. Dışa aktarma URL'sindeki aracı kimliği belirteç tarafından yetkilendirilen kimlikle eşleşmediğinden, izlemeleri uç noktası isteği reddeder.

Çözüm:

• Kiracı kimliğinin Agent 365 izin verilen kiracı listesine eklenip eklenmediğini doğrulayın.
• Aracı ayrıntılarını aracı örneği istemci kimliği ile ayarlayın (şema istemci kimliği değil).
• Oluşturulan dışa aktarma URL'sini doğrulayın - logger'ınızı etkinleştirirseniz günlüğe kaydedilir. URL'deki aracı kimliğinin aracı örneği istemci kimliğiyle eşleştiğini doğrulayın.
• Tanı kaydını SDK bazında etkinleştirmek için, bkz: Yerelde Doğrulama.

HTTP 429 veya 5xx hataları - Geçici hatalar

Belirtiler: Dışa aktarma, 429 veya 5xx gibi geçici bir HTTP durum koduyla başarısız olur.

Çözüm:

• Bu hatalar genellikle geçicidir ve kendi kendilerine çözülür. Python ve JavaScript SDK'leri, HTTP 408, 429 ve 5xx durum kodlarında, üstel aralıklarla otomatik olarak üç kez yeniden dener. .NET SDK otomatik olarak tekrar denemez.
• Hatalar devam ederse, hizmet sağlığı panosunu kontrol edin.
• Dışa aktarma sıklığını azaltmak için, partiler arasındaki planlı gecikmeyi artırmayı veya maksimum dışa aktarma parti boyutunu artırmayı düşünün. Her platform için yapılandırma seçenekleri için, Yapılandırma bölümündeki Agent365ExporterOptions tabloya bakınız.

Dışa aktarma zaman aşımı

Belirtiler: Dışa aktarma denemeleri zaman aşımına uğrar.

Çözüm:

• Gözlemlenebilirlik uç noktasına ağ bağlantısını kontrol edin.
• Zaman aşımı için varsayılan değerler platforma göre değişir. Varsayılan HTTP isteği zaman aşımı süresi 30 saniyedir. Bazı SDK'larda, denemeler dahil olmak üzere tüm dışa aktarma döngüsünü kapsayan ayrı bir genel dışa aktarma zaman aşımı da bulunur. Platforma özgü kesin özellikler ve varsayılan değerler için Yapılandırma bölümündeki Agent365ExporterOptions tablosuna bakın.
• Zaman aşımları sık sık meydana geliyorsa, dışa aktarma seçeneklerinizde ilgili zaman aşımı değerini artırın.

Dışa aktarma başarılı olur ancak telemetri, Defender veya Purview'da görünmez

Belirtiler: Loglar başarılı bir dışa aktarma olduğunu gösteriyor ancak telemetri Microsoft Defender veya Microsoft Purview'da görünmüyor.

Çözüm:

• Dışa aktarılan günlükleri görüntülemek için gerekli ön koşulları yerine getirdiğinizden emin olun. Purview için denetim özelliği etkinleştirilmiş olmalıdır. Defender için gelişmiş aramayı yapılandırmanız gerekir. Daha fazla bilgi için bkz: Dışa aktarılan günlükleri görüntüleme.
• Telemetri, başarılı bir dışa aktarmanın ardından doldurulması birkaç dakika sürebilir. Daha fazla araştırma yapmadan önce verilerin görünmesini bekleyin.

Gözlemlenebilirlik testleri hakkında daha fazla bilgi edinmek için bakınız:

• Test kılavuzu - Gözlemlenebilirlik loglarını görüntüleyin
• Gözlemlenebilirlik yapılandırması

İlgili içerik

• Agent 365 gözlemlenebilirlik kavramları - Her tümleştirme yolu için geçerli olan veri akışı, kimlik modelleri, kimlik doğrulaması, kapsamlar ve sınırlar.
• Agent 365 gözlemlenebilirlik öznitelik başvurusu - Agent 365 tarafından alınan her aralığın uyması gereken kanonik aralık özniteliği şeması.
• Microsoft OpenTelemetry Distro - Yeni entegrasyonlar için önerilen birleşik SDK.