SDK for observerbarhet

Viktig!

Aktiver observabilitet i Agent 365 ved å bruke Microsoft OpenTelemetry Distro. Denne distribusjonen tilbyr en felles observabilitets-SDK for hele Microsoft, som driver Agent 365, Microsoft Foundry, Azure Monitor og flere andre tjenester. Den eksisterende tilnærmingen beskrevet i denne artikkelen fortsetter å fungere uten endringer som bryter kompatibilitet. For migrasjonsveiledning etter språk, se følgende veiledninger:

• Veiledning for Python-overføring
• JavaScript/TypeScript-migreringsveiledning
• .NET migreringsveiledning For den underliggende datamodellen, identitet og autentisering, scopes og samtykke, samt begrensninger – som gjelder for alle integrasjonsveier – se Agent 365 observability-konsepter.

Notat

Observabilitet er et av de inkrementelle kapabilitetsnivåene i Get Started with Agent 365-utvikling og gjelder for alle agenttyper.

For å delta i Agent 365-økosystemet, legg til Agent 365 Observability-funksjoner i agenten din. Agent 365 Observability bygger på OpenTelemetry (OTel) og gir et samlet rammeverk for å fange telemetri konsekvent og sikkert på tvers av alle agentplattformer. Ved å implementere denne nødvendige komponenten, gjør du det mulig for IT-administratorer å overvåke agentens aktivitet i Administrasjonssenteret for Microsoft, og gir sikkerhetsteam mulighet til å bruke Defender og Purview for etterlevelse og trusseldeteksjon.

Hovedfordeler

• Helhetlig synlighet: Fang omfattende telemetri for hver agentutførelse, inkludert økter, verktøykall og unntak, slik at du får full sporbarhet på tvers av plattformer.
• Aktivering av sikkerhet og etterlevelse: Overfør enhetlige revisjonslogger til Defender og Purview, noe som aktiverer avanserte sikkerhetsscenarier og rapportering om etterlevelse for agenten din.
• Fleksibilitet på tvers av plattformer: Bygg på OTel-standarder og støtt ulike kjøretider og plattformer som Copilot Studio, Foundry og fremtidige agentrammeverk.
• Operasjonell effektivitet for administratorer: Gi sentralisert observabilitet i Administrasjonssenter for Microsoft 365, reduserer feilsøkingstiden og forbedrer styringen med rollebaserte tilgangskontroller for IT-team som administrerer agenten din.

Støttede agenter

Følgende agenttyper støtter observabilitet for Agent 365:

• Microsoft Agent 365-aktiverte agenter: Bruk observability SDK for å instrumentere agenten din.
• Egendefinerte motoragenter: Bruk observability SDK for å instrumentere agenten din.
• Deklarative agenter: Observabilitet støttes som standard. Ingen SDK-implementering kreves.

Installasjon

Bruk disse kommandoene for å installere observabilitetsmodulene for språkene som støttes av Agent 365.

Python

Installer kjernepakkene for observabilitet og kjøretidspakker. Alle agenter som bruker Agent 365 Observability trenger disse pakkene.

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

Hvis agenten din bruker Microsoft Agents Hosting-pakken, installer hosting-integrasjonspakken. Den tilbyr mellomvare som automatisk fyller inn baggasje og omfang fra TurnContext, og inkluderer tokenbufring for observabilitetseksportøren.

pip install microsoft-agents-a365-observability-hosting

Hvis agenten din bruker en av de støttede AI-rammeverkene, installer den tilsvarende utvidelsen for autoinstrumentering for å registrere telemetri automatisk uten behov for manuell instrumentering. For konfigurasjonsdetaljer, se Auto-instrumentering.

# 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

Installer kjernepakkene for observabilitet og kjøretidspakker. Alle agenter som bruker Agent 365 Observability trenger disse pakkene.

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

Hvis agenten din bruker @microsoft/agents-hosting-pakken, installer hostingintegrasjonspakken. Den tilbyr mellomvare som automatisk fyller inn baggasje og omfang fra TurnContext, og inkluderer tokenbufring for observabilitetseksportøren.

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

Hvis agenten din bruker en av de støttede AI-rammeverkene, installer den tilsvarende utvidelsen for autoinstrumentering for å registrere telemetri automatisk uten behov for manuell instrumentering. For konfigurasjonsdetaljer, se Auto-instrumentering.

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

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

.NET

Installer kjerneobservabilitets- og kjøretidspakken. Alle agenter som bruker Agent 365 Observability må installere denne pakken.

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

Hvis agenten din bruker Microsoft.Agents.A365.Observability.Hosting NuGet-pakken, installer integrasjonspakken for hosting. Den tilbyr mellomvare som automatisk fyller inn baggasje og omfang fra TurnContext, og inkluderer tokenbufring for observabilitetseksportøren.

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

Hvis agenten din bruker en av de støttede AI-rammeverkene, installer den tilsvarende utvidelsen for autoinstrumentering for å registrere telemetri automatisk uten behov for manuell instrumentering. For konfigurasjonsdetaljer, se Auto-instrumentering.

// 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

Konfigurasjon

Bruk følgende innstillinger for å aktivere og tilpasse Agent 365 Observability for agenten din.

Python

Sett ENABLE_A365_OBSERVABILITY_EXPORTER-miljøvariabelen til true for observabilitet. Denne innstillingen eksporterer logger til tjenesten og krever at en token_resolver oppgis. Ellers brukes konsolleksportøren.

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-resolveren er ekskludert fra loggføring til konsollen.

Du kan tilpasse eksportørens oppførsel ved å sende en Agent365ExporterOptions forekomst til exporter_options. Når exporter_options er oppgitt, har den forrang over parameterne token_resolver og cluster_category.

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,
)

Tabellen nedenfor beskriver de valgfrie parameterne for configure().

Parameter	Description	Standard
logger_name	Navnet på Python-loggeren som brukes til feilsøking og logg til konsoll.	microsoft_agents_a365.observability.core
exporter_options	En Agent365ExporterOptions-instans som konfigurerer både token-resolveren og klyngekategorien sammen.	None
suppress_invoke_agent_input	Når True, undertrykker inndatameldinger på InvokeAgent spenn.	False

Tabellen nedenfor beskriver de valgfrie egenskapene for Agent365ExporterOptions.

Egenskap	Description	Standard
use_s2s_endpoint	Når True brukes tjeneste-til-tjeneste-endepunktbanen.	False
max_queue_size	Maksimal køstørrelse for partiprosessoren.	2048
scheduled_delay_ms	Forsinkelse i millisekunder mellom eksportpartiene.	5000
exporter_timeout_ms	Tidsavbrudd i millisekunder for eksportoperasjonen.	30000
max_export_batch_size	Maksimal partistørrelse for eksportoperasjoner.	512

JavaScript

Sett ENABLE_A365_OBSERVABILITY_EXPORTER-miljøvariabelen til true for observabilitet. Denne innstillingen eksporterer logger til tjenesten og krever at det leveres en token-resolver. Ellers brukes konsolleksportøren.

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();

Som et alternativ til miljøvariabler kan du konfigurere observability programmatisk ved hjelp av en konfigurasjonsleverandør via withConfigurationProvider-metoden. Hvis du også bruker individuelle builder-metoder (for eksempel withExporterOptions eller withClusterCategory), har disse metodene forrang over verdier fra konfigurasjonsleverandøren.

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();

Du kan tilpasse eksportørens oppførsel ved å sende en Agent365ExporterOptions forekomst til withExporterOptions. Dette alternativet lar deg kontrollere batching, tidsavbrudd og rutemodus.

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();

Tabellen nedenfor beskriver de valgfrie egenskapene for Agent365ExporterOptions.

Egenskap	Description	Standard
useS2SEndpoint	Når true brukes tjeneste-til-tjeneste-endepunktbanen.	false
maxQueueSize	Maksimal køstørrelse for partiprosessoren.	2048
scheduledDelayMilliseconds	Forsinkelse i millisekunder mellom eksportpartiene.	5000
exporterTimeoutMilliseconds	Tidsavbrudd i millisekunder for hele eksportoperasjonen.	90000
httpRequestTimeoutMilliseconds	Tidsavbrudd i millisekunder for hver enkelt HTTP-forespørsel til serverdelen.	30000
maxExportBatchSize	Maksimal partistørrelse for eksportoperasjoner.	512

Du kan også tilby en egendefinert logger som implementerer ILogger-grensesnittet (info, warn, error, event). Gi den til builderen ved å bruke withCustomLogger.

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

Sett EnableAgent365Exporter til true i appsettings.json.

I Program.cs legger du til Agent365ExporterOptions i tjenestesamlingen. Denne endringen konfigurerer delegaten trace-eksportøren bruker for å hente tokenet.

Legg til observabilitetsrelaterte avhengigheter ved å bruke AddA365Tracing().

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();

Du kan tilpasse eksportørens oppførsel ved å sende en konfigurering-delegat og eksportørtype til AddA365Tracing().

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

Tabellen nedenfor beskriver de valgfrie egenskapene for Agent365ExporterOptions.

Egenskap	Description	Standard
UseS2SEndpoint	Når true brukes tjeneste-til-tjeneste-endepunktbanen.	false
MaxQueueSize	Maksimal køstørrelse for partiprosessoren.	2048
ScheduledDelayMilliseconds	Forsinkelse i millisekunder mellom eksportpartiene.	5000
ExporterTimeoutMilliseconds	Tidsavbrudd i millisekunder for eksportoperasjonen.	30000
MaxExportBatchSize	Maksimal partistørrelse for eksportoperasjoner.	512

Bagasjeattributter

Bruk BaggageBuilder til å angi kontekstuell informasjon som følger alle strekk i en forespørsel. SDK-en implementerer en SpanProcessor som kopierer alle ikke-tomme bagasjeoppføringer til nylig opprettede strekk uten å overskrive eksisterende attributter.

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

For å fylle ut BaggageBuilder automatisk fra TurnContext bruker du populate-hjelperen i microsoft-agents-a365-observability-hosting-pakken. Denne hjelperen henter automatisk ut detaljer om kaller, agent, leietaker, kanal og samtale fra aktiviteten.

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
});

For å fylle ut BaggageBuilder automatisk fra TurnContext bruker du fromTurnContext-hjelperen i @microsoft/agents-a365-observability-hosting-pakken. Denne hjelperen henter automatisk ut detaljer om kaller, agent, leietaker, kanal og samtale fra aktiviteten.

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.

For å fylle ut BaggageBuilder automatisk fra ITurnContext bruker du utvidelsesmetoden FromTurnContext i Microsoft.Agents.A365.Observability.Hosting-pakken. Denne metoden trekker automatisk ut kaller-, agent-, leietaker-, kanal- og samtaledetaljer fra aktiviteten.

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

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

Bagasjemellomvare

Hvis agenten din bruker vertsintegrasjonspakken, registrerer du bagasjemellomvare for automatisk å fylle ut bagasje for hver innkommende forespørsel. Dette trinnet fjerner behovet for å kalle BaggageBuilder manuelt i hver aktivitetsbehandlingsprogram.

Python

Registrer BaggageMiddleware i adapter-middleware-settet. Den trekker automatisk ut detaljer om kaller, agent, leietaker, kanal og samtale fra hver innkommende TurnContext og pakker forespørselen inn i en bagasjekontekst.

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

Alternativt kan du bruke ObservabilityHostingManager til å konfigurere bagasje-mellomvare sammen med andre hostingfunksjoner:

from microsoft_agents_a365.observability.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

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

Mellomvaren unngår å sette bagasje for asynkrone svar (ContinueConversation-hendelser) for å unngå å overskrive bagasje som den opprinnelige forespørselen allerede har satt.

JavaScript

Registrer BaggageMiddleware på adapteren. Den trekker automatisk ut detaljer om kaller, agent, leietaker, kanal og samtale fra hver innkommende TurnContext og pakker forespørselen inn i en bagasjekontekst.

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

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

Alternativt kan du bruke ObservabilityHostingManager til å konfigurere bagasje-mellomvare sammen med andre hostingfunksjoner:

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

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

Mellomvaren unngår å sette bagasje for asynkrone svar (ContinueConversation-hendelser) for å unngå å overskrive bagasje som den opprinnelige forespørselen allerede har satt.

.NET

Registrer BaggageTurnMiddleware på adapteren. Den trekker automatisk ut detaljer om kaller, agent, leietaker, kanal og samtale fra hver innkommende ITurnContext og pakker forespørselen inn i en bagasjekontekst.

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

adapter.Use(new BaggageTurnMiddleware());

Mellomvaren unngår å sette bagasje for asynkrone svar (ContinueConversation-hendelser) for å unngå å overskrive bagasje som den opprinnelige forespørselen allerede har satt.

Hvis du trenger bagasje på HTTP-nivå (f.eks. for å sette leietaker- og agent-ID-er før Bot Framework-rørledningen kjører), registrerer du ObservabilityBaggageMiddleware i ASP.NET Core-rørledningen ved å bruke utvidelsesmetoden UseObservabilityRequestContext. Du må implementere en funksjon som trekker ut leietaker-ID og agent-ID fra HTTP-konteksten.

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-løser

Når du bruker Agent 365-eksportøren, må du implementere en token resolver-funksjon som returnerer et autentiseringstoken. Når du bruker Agent 365 Observability SDK sammen med Agent Hosting-rammeverket, kan du generere autentiseringstoken ved å bruke TurnContext fra agent-aktivitetene.

Python

Følgende kodeeksempel viser hvordan du genererer et token ved hjelp av microsoft_agents.hosting.core SDK. Autentiseringstokenet som genereres her, brukes til å eksportere spans til A365-inntakstjenesten. Agenter kan generere et token selv, for eksempel ved å bruke Microsoft Authentication Library (MSAL), men de må sørge for at tokenet har observabilitetsomfanget.

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

For en agent bygget med A365 CLI som bruker en AI-assistent og Microsoft Agent 365 Observability Hosting Library-pakken, bruk AgenticTokenCache for å håndtere token-caching automatisk. Angi tokenet én gang for hver agent og leietaker i en aktivitetshåndterer, og angi cache.get_observability_token som token_resolver i observabilitetskonfigurasjonen din.

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

Følgende kodeeksempel viser hvordan du genererer et token ved hjelp av @microsoft/agents-hosting SDK. Autentiseringstokenet som genereres her, brukes til å eksportere spans til A365-inntakstjenesten. Agenter kan generere et token selv, for eksempel ved å bruke Microsoft Authentication Library (MSAL), men de må sørge for at tokenet har observabilitetsomfanget.

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
  }
);

For en agent bygget med A365 CLI som bruker en AI-assistent og @microsoft/agents-a365-observability-hosting-pakken, bruk AgenticTokenCacheInstance for å håndtere token-caching automatisk. Kall RefreshObservabilityToken én gang per agent og leietaker under en aktivitetshåndterer, og send AgenticTokenCacheInstance.getObservabilityToken som tokenResolver i observabilitetskonfigurasjonen.

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

Følgende kodeeksempel viser hvordan du genererer et token ved å bruke Microsoft.Agents hosting-SDK-en. Bruk autentiseringstokenet du genererer til å eksportere spans til A365-inntakstjenesten. Agenter kan generere et token selv, for eksempel ved å bruke Microsoft Authentication Library (MSAL), men de må sørge for at tokenet har observabilitetsomfanget.

Registrer Agent365ExporterOptions med en TokenResolver Delegate for å tilby en token-resolver. Delegaten mottar agentId og tenantId og returnerer et autentiseringstoken.

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);
            }
        };
    });

For en agent bygget med A365 CLI som bruker en AI-lagkamerat og Microsoft.Agents.A365.Observability.Hosting NuGet-pakken, bruk metoden AddAgenticTracingExporter() for å håndtere tokencaching automatisk gjennom avhengighetsinjeksjon.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

Registrer tokenet i agentapplikasjonen.

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}");
        }
    }
}

Auto-Instrumentering

Auto-instrumentering overvåker automatisk agentrammeverks eksisterende sporingssignaler fra telemetri og videresender dem til observabilitetstjenesten til Agent 365. Denne funksjonen gjør det unødvendig for utviklere å skrive overvåkingskode manuelt, forenkler oppsettet og sikrer konsekvent ytelsessporing.

Viktig!

Auto-instrumentering angir kun standard OTel-attributter. Du må legge til Microsoft-spesifikke attributter gjennom BaggageBuilder. For å se hvilke attributter som mangler, valider span-utdata fra konsollen mot Store-loggene for å finne forskjellene.

Flere SDK-er og plattformer støtter auto-instrumentering:

Plattform	Støttede SDK-er / rammeverk
.NET	Semantic Kernel, OpenAI, Agent Framework
Python	Semantic Kernel, OpenAI, Agent Framework, LangChain
Node.js	OpenAI, LangChain

Notat

Støtte for auto-instrumentering varierer etter plattform og SDK-implementering.

Semantic Kernel

Automatisk instrumentering krever bruk av baggage builder. Sett agent-ID og tenant-ID ved å bruke BaggageBuilder.

Python

Installer pakken.

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

Konfigurer observabilitet.

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

Semantic Kernel støttes ikke i JavaScript.

.NET

Legg til avhengigheter i ServiceCollection.

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

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

Sett AgentId og TenantId ved å bruke BaggageBuilder. Sørg for at ID-en du bruker når du oppretter en ChatCompletionAgent stemmer overens med agent-ID-en du sender til BaggageBuilder.

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

Automatisk instrumentering krever bruk av baggage builder. Sett agent-ID og tenant-ID ved å bruke BaggageBuilder.

Python

Installer pakken.

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

Konfigurer observabilitet.

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

Installer pakken.

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

Konfigurer observabilitet.

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

Legg til avhengigheter i ServiceCollection.

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

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

Sett AgentId og TenantId ved å bruke BaggageBuilder. For verktøykall, start en trace ved å bruke Trace() på en ChatToolCall instans.

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

Automatisk instrumentering krever bruk av baggage builder. Sett agent-ID og tenant-ID ved å bruke BaggageBuilder.

Python

Installer pakken.

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

Konfigurer observabilitet.

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 støttes ikke for JavaScript.

.NET

Legg til avhengigheter i ServiceCollection.

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

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

Sett AgentId og TenantId ved å bruke BaggageBuilder.

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-rammeverk

Autoinstrumentering krever bruk av baggage builder. Sett agent-ID og tenant-ID ved å bruke BaggageBuilder.

Python

Installer pakken.

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

Konfigurer observabilitet.

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

Installer pakken.

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

Konfigurer observabilitet.

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 støttes ikke med .NET.

Manuell instrumentering

Bruk Agent 365 observability SDK for å forstå agentens interne virkemåte. SDK-en gir omfang som du kan starte: InvokeAgentScope, ExecuteToolScope, InferenceScope og OutputScope.

Agentaktivering

Bruk dette omfanget i starten av agentprosessen. Ved å bruke agentkall-omfanget kan du registrere egenskaper som den nåværende agenten som påkalles, agentbrukerdata og mer.

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();
}

Hvis agenten din bruker @microsoft/agents-a365-observability-hosting-pakken, kan du bruke ScopeUtils.populateInvokeAgentScopeFromTurnContext til å opprette omfanget med agentdetaljer, oppringerdetaljer og kanalinformasjon automatisk hentet fra TurnContext.

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; }
}

Verktøykjøring

Følgende eksempler viser hvordan du kan legge til observabilitetssporing i agentens verktøyutførelse. Denne sporingen fanger opp telemetri for overvåking og revisjon.

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();
}

Hvis agenten din bruker @microsoft/agents-a365-observability-hosting-pakken, bruk ScopeUtils.populateExecuteToolScopeFromTurnContext til å opprette omfanget med agentdetaljer automatisk hentet fra TurnContext.

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.\"}");

Inferens

Følgende eksempler viser hvordan du kan instrumentere AI-modellinferensanrop med observabilitetssporing for å samle tokenbruk, modelldetaljer og responsmetadata.

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();
}

Hvis agenten din benytter @microsoft/agents-a365-observability-hosting-pakken, kan du bruke ScopeUtils.populateInferenceScopeFromTurnContext for å opprette et omfang med agentdetaljer som automatisk utledes fra TurnContext.

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);

Output

Bruk dette omfanget for asynkrone scenarioer der InvokeAgentScope, ExecuteToolScope eller InferenceScope ikke kan fange opp data synkront. Start OutputScope som en underordnet span for å registrere de siste utdatameldingene etter at overordnet omfang er avsluttet.

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

Valider lokalt

For å verifisere at du har lykkes med å integrere med observability-SDK-en, undersøk konsolloggene generert av agenten din og loggene fra observability-SDK-en.

Python

Angi miljøvariabelen ENABLE_A365_OBSERVABILITY_EXPORTER til false. Denne innstillingen eksporterer spans (traces) til konsoll.

For å undersøke eksportfeil, aktiver detaljert logging ved å sette ENABLE_A365_OBSERVABILITY_EXPORTER til true og konfigurere feilsøkingslogging ved oppstart av applikasjonen:

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)

Nøkkel-loggmeldinger:

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

Angi miljøvariabelen ENABLE_A365_OBSERVABILITY_EXPORTER til false. Denne innstillingen eksporterer spans (traces) til konsoll.

For å feilsøke eksportfeil, sett miljøvariabler i .env eller shell:

# Enable the Agent365 exporter
ENABLE_A365_OBSERVABILITY_EXPORTER=true

# Enable verbose logging
A365_OBSERVABILITY_LOG_LEVEL=info|warn|error

Gå gjennom konsollutgangen for meldinger som:

[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

Eventuelt kan du bruke en egendefinert logger for å logge eksporthendelser til en fil:

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

Sett EnableAgent365Exporter til false i appsettings.json. Denne innstillingen eksporterer spans (traces) til konsoll.

For å undersøke eksportfeil, konfigurer verbose logging i appsettings.json:

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

Eller angi miljøvariabler:

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

Nøkkel-loggmeldinger:

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.

Notat

Hvis du ikke registrerer en ILoggerFactory i DI, faller eksportøren automatisk tilbake til en konsollogger.

Se eksporterte logger

For å se agenttelemetri i Microsoft Purview eller Microsoft Defender må du sørge for at følgende krav er oppfylt:

• Microsoft Purview: Revisjon må være aktivert for organisasjonen din. For instruksjoner kan du se Aktiver eller deaktiver revisjon.
• Microsoft Defender: Avansert jakt må konfigureres for å få tilgang til CloudAppEvents-tabellen. For mer informasjon kan du se CloudAppEvents-tabellen i skjemaet for avansert jakt.

Valider for publisering i lagring

Viktig!

For vellykket validering i lagring må agenten din må implementere InvokeAgentScope, InferenceScope og ExecuteToolScope omfang. Disse tre omfangene er påkrevd for publisering.

Før publisering bruker du konsollogger for å validere observabilitetsintegrasjonen for agenten ved å implementere de nødvendige invoke agent, execute tool, inference og output omfangene. Sammenlign deretter agentens logger med følgende attributtlister for å verifisere at alle påkrevde attributter er til stede. Fang attributter på hvert omfang eller gjennom bagasjebyggeren, og inkluder valgfrie attributter etter eget skjønn.

For mer informasjon om krav til Store-publisering, se Store-valideringsretningslinjer.

InvokeAgentScope attributter

Følgende liste oppsummerer de påkrevde og valgfrie telemetriattributtene som registreres når du starter en InvokeAgentScope.

"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 attributter

Følgende liste oppsummerer de påkrevde og valgfrie telemetriattributtene som registreres når du starter en ExecuteToolScope.

"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 attributter

Følgende liste oppsummerer de påkrevde og valgfrie telemetriattributtene som registreres når du starter en InferenceScope.

"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 attributter

Følgende liste oppsummerer de påkrevde og valgfrie telemetriattributtene som registreres når du starter en OutputScope. Bruk dette omfanget for asynkrone scenarioer der det overordnede omfanget ikke kan fange opp utdata synkront.

"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"
    }

Test agenten din med observerbarhet

Etter at du har implementert observabilitet i agenten din, test den for å sikre at den fanger opp telemetri korrekt. Følg testguiden for å sette opp miljøet ditt. Fokuser deretter hovedsakelig på seksjonen Se observabilitetslogger for å bekrefte at observabilitetsimplementeringen din fungerer som forventet.

Verifikasjon:

• Gå til: https://admin.cloud.microsoft/#/agents/all
• Velg agenten din > Aktivitet
• Du ser økter og verktøykall

Feilsøking

Denne delen beskriver vanlige problemer ved implementering og bruk av observabilitet.

Problem	Description
Observerbarhetsdata vises ikke	Ingen telemetri er synlig fordi eksport ikke er aktivert, konfigurasjonen er feil, eller token-oppløsningen feiler.
Manglende leier-ID eller agent-ID – strekk hoppes over	Spanene blir droppet før eksport når identitetsattributter som kreves for partisjonering mangler.
Tokenoppløsningsfeil – eksport hoppet over eller uautorisert	Eksportforespørsler mislykkes eller blir utelatt når resolveren ikke returnerer en token eller støter på en unntak.
HTTP 401 Uautorisert	Autentisering lykkes rent syntaktisk, men tokenet er ugyldig for inntak på grunn av omfang, type eller utløpsdato.
HTTP 403 Ikke tillatt	Tilgang nektes på grunn av manglende leietakerlisens eller manglende tillatelser for observabilitet.
HTTP 403 Forbudt – Agent-ID-konflikt	Forespørselen avvises hvis agentidentiteten i nettadressen ikke stemmer overens med identiteten representert av tokenet.
HTTP 429 eller 5xx-feil – Midlertidige feil	Midlertidig begrensning eller tjenestesidefeil avbryter eksporten og kan kreve finjustering av gjentakelseslogikken.
Eksporttidsavbrudd	Telemetribatcher overskrider konfigurerte tidsavgrensninger på grunn av nettverksforsinkelse eller treg responstid fra endepunktet.
Eksport lykkes, men telemetri vises ikke i Defender eller Purview	Inntak fullføres, men nedstrøms synlighet blir forsinket eller blokkert av produktforutsetninger.

Tips

Feilsøkingsveiledning for Agent 365 inneholder anbefalinger på høyt nivå for feilsøking, anbefalte fremgangsmåter og koblinger til feilsøkingsinnhold for hver fase i utviklingssyklusen i Agent 365.

Observerbarhetsdata vises ikke

Symptomer:

• Agenten kjører
• Ingen telemetri i administrasjonssenteret
• Kan ikke se agentaktivitet

Rotårsak:

• Observerbarhet er ikke aktivert
• Konfigurasjonsfeil
• Tokenløserproblemer

Løsninger: Prøv følgende trinn for å løse problemet:

• Verifiser observabilitetseksportøren er aktivert

  Du må eksplisitt aktivere Agent 365-eksporten. Når eksportøren er deaktivert, faller SDK-en tilbake til en konsolleksportør, og telemetri sendes ikke til tjenesten. For konfigurasjonsdetaljer, se Konfigurasjon.

• Sjekk konfigurasjonen for tokenløser

  Eksportøren krever en gyldig tokenløser som returnerer en bærertoken for hver eksportforespørsel. Hvis tokenløseren mangler eller returnerer null, blir eksporten hoppet over uten varsel. Sørg for at koden din implementerer tokenresolveren riktig. Se tokenresolver for detaljer.

• Sjekk loggene for feil

  Slå på detaljert logging og bruk az webapp log tail-kommandoen for å finne feil relatert til observabilitet i loggene. For detaljer om hvordan logging aktiveres per plattform, se Valider lokalt.

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

• Verifiser telemetrieksport

  Bekreft at telemetri genereres og eksporteres som forventet.

  • Legg til en konsolleksportør og sjekk om telemetri genereres lokalt. For detaljer om hvordan du bruker konsolleksportøren og validerer utdata, se Valider lokalt.

Manglende leier-ID eller agent-ID – strekk hoppet over

Symptomer: Systemet senker stille strekk og eksporterer dem aldri. Noen SDK-er logger antall utelatte spans eller en melding som «Ingen spans med tenant-/agentidentitet funnet». Andre dropper dem uten å logge dem.

Løsning.

• Før eksport deler SDK-en opp spans etter leietaker- og agentidentitet. Systemet dropper spans som mangler enten leier-ID eller agent-ID og sender dem aldri til tjenesten.
• Sørg for at BaggageBuilder er satt opp med leietaker-ID og agent-ID før du oppretter strekk. Disse verdiene videreføres gjennom OpenTelemetry-konteksten og legges til alle strekk som opprettes innenfor bagasjeomfanget. For den plattformspesifikke API-en kan du se Bagasjeattributter.
• Bekreft at TurnContext-aktiviteten har en gyldig mottaker med agentidentitet hvis du bruker baggage-middleware eller turn context helper fra hosting-integrasjonspakken for å sette disse ID-ene.

Tokenoppløsningsfeil – eksport utelatt eller uautorisert

Symptomer: Tokenløseren returnerer null eller kaster en feil. Avhengig av SDK-en kan eksporten enten bli utelatt helt, eller forespørselen sendes uten en autorisasjonsheader og feiler med HTTP 401.

Løsning.

• Token-resolveren kreves ved initialisering. Hvis det mangler, gir eksportøren en feilmelding ved oppstart. Kontroller at en tokenløser er oppgitt og returnerer et gyldig bærertoken.
• Sørg for at riktig leietaker-ID og agent-ID brukes for BaggageBuilder, fordi disse verdiene sendes til token-resolveren.
• For Azure-baserte agenter må du sørge for at administrert identitet har de nødvendige API-rettighetene for observerbarhetsomfanget.

HTTP 401 Uautorisert

Symptomer: Eksport mislykkes med HTTP 401. Eksportøren forsøker ikke på nytt ved denne feilen.

Løsning.

• Verifiser at tokenmålgruppen samsvarer med observerbarhetsendepunktets omfang.
• Sjekk at tokenløseren ikke returnerer en delegert brukertoken, et token for feil målgruppe eller et utløpt token.

HTTP 403 Ikke tillatt

Symptomer: Eksport mislykkes med HTTP 403. Eksportøren forsøker ikke på nytt ved denne feilen.

Rotårsak: En HTTP 403-feil kan ha ulike årsaker. Sjekk følgende løsninger i rekkefølge.

Løsning.

• Manglende lisens – Kontroller at leietakeren din har én av følgende lisenser tildelt i Administrasjonssenteret for Microsoft 365:

  • Test – Microsoft 365 E7
  • Microsoft 365 E7
  • Microsoft Agent 365 Frontier

• Manglende Agent365.Observability.OtelWritetillatelse — Hvis du nylig har oppgradert observabilitetspakkene dine, må du gi denne tillatelsen. Se den viktige merknaden i neste seksjon.

Viktig!

Eksisterende agenter som oppgraderer til disse pakkeversjonene krever et ekstra trinn

Dette trinnet gjelder kun hvis du oppgraderer en eksisterende agent. Nye agentinstallasjoner krever ikke dette trinnet. Hvis du oppgraderer til følgende pakkeversjoner eller nyere, må du gi den nye Agent365.Observability.OtelWrite-tillatelsen til identiteten din (administrert identitet eller appregistrering). Uten denne tillatelsen feiler telemetrieksport med HTTP 403.

Plattform	Minimumsversjon som krever dette trinnet
.NET	0.3-beta
Node.js	0.2.0-preview.1
Python	0.3.0

Gi tillatelsen ved å bruke ett av følgende alternativer.

Alternativ A — Agent 365 CLI (krever en Global Administrator-konto; kjør fra agentprosjektkatalogen som inneholder a365.config.json, eller bruk --agent-name)

a365 setup permissions bot

Eller uten konfigurasjonsfil:

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

Denne kommandoen gir alle manglende tillatelser på blueprinten, inkludert observabilitetsscopene.

Alternativ B — Entra-portalen (ingen konfigurasjonsfiler kreves; krever Global Administrator-tilgang til blueprint-appens registrering)

1. Gå til Entra Portal>Appregistreringer> velg blåkopiappen.
2. Gå til API-tillatelser>Legg til en tillatelse>API-er organisasjonen min bruker> søk etter 9b975845-388f-4429-889e-eab1ef63949c.
3. Velg Delegerte tillatelser>, merk av Agent365.Observability.OtelWrite>Legg til tillatelser.
4. Gjenta trinn 2–3, denne gangen velg Applikasjonstillatelser>, sjekk Agent365.Observability.OtelWrite>Legg til tillatelser.
5. Klikk på Gi administratorsamtykke og bekreft.

Både Agent365.Observability.OtelWrite (Delegert) og Agent365.Observability.OtelWrite (Applikasjon) skal vise Granted status.

HTTP 403 Forbudt – Agent-ID-konflikt

Symptomer: Eksporten mislykkes med HTTP 403 og en servermelding som ligner på 403 Forbidden med agent-ID-mismatch-feil ved kall til Agent 365-sporendepunkter.

Rotårsak: Denne feilen oppstår når du bruker blåkopiklient-ID-en i stedet for klient-ID-en til agentforekomsten når du konfigurerer agentdetaljene. Agent-ID-en i eksportnettadressen samsvarer ikke med identiteten autorisert av tokenet, så sporendepunktet avviser forespørselen.

Løsning.

• Verifiser at leietaker-ID-en er lagt til i listen over tillatte leietakere for Agent 365.
• Konfigurer agentdetaljene med klient-ID-en til agentforekomst (ikke blåkopiklient-ID-en).
• Verifiser eksportnettadressen som genereres – den logges hvis logging er aktivert. Bekreft at agent-ID-en i nettadressen samsvarer med agentforekomstens klient-ID.
• For å aktivere diagnostisk logging per SDK, se Valider lokalt.

HTTP 429 eller 5xx-feil – Midlertidige feil

Symptomer: Eksport feiler med en midlertidig HTTP-statuskode som 429 eller 5xx.

Løsning.

• Disse feilene er vanligvis forbigående og løser seg av seg selv. Python- og JavaScript-SDK-ene prøver automatisk på nytt ved HTTP-statuskodene 408, 429 og 5xx opptil tre ganger med eksponentiell tilbaketrekning. .NET SDK-en prøver ikke automatisk på nytt.
• Hvis feilene vedvarer, sjekker du tjenestetilstandsinstrumentbordet.
• Vurder å redusere eksportfrekvensen ved å øke den planlagte forsinkelsen mellom batchene eller øke maksimal eksportbatchstørrelse. For konfigurasjonsalternativer per plattform, se Agent365ExporterOptions tabellen i Konfigurasjon.

Eksporttidsavbrudd

Symptomer: Eksportforsøk har tidsavbrudd.

Løsning.

• Kontroller nettverkstilkoblingen til observerbarhetsendepunktet.
• Timeout-standarder varierer avhengig av plattform. Standard HTTP-forespørseltidsavbrudd er 30 sekunder. Noen SDK-er har også en separat samlet timeout for eksportøren som dekker hele eksportprosessen, inkludert gjentatte forsøk. For nøyaktige egenskaper og standardinnstillinger per plattform, se Agent365ExporterOptions tabellen i Konfigurasjon.
• Hvis timeout oppstår ofte, øk den relevante timeout-verdien i eksportørinnstillingene dine.

Eksport lykkes, men telemetri vises ikke i Defender eller Purview

Symptomer: Loggene viser en vellykket eksport, men telemetri er ikke synlig i Microsoft Defender eller Microsoft Purview.

Løsning.

• Kontroller at du oppfyller forutsetningene for å se eksporterte logger. For Purview må loggføring aktiveres. For Defender må du konfigurere avansert jakt. For mer informasjon, se Visning av eksporterte logger.
• Det kan ta flere minutter før telemetridata blir tilgjengelig etter en vellykket eksport. Vent på at dataene skal dukke opp før du undersøker videre.

For mer informasjon om testing av observabilitet, se:

• Testveiledning – Vis observabilitetslogger
• Observabilitetskonfigurasjon

Relatert innhold

• Agent 365 observerbarhetskonsepter – Dataflyt, identitetsmodeller, autentisering, omfang og grenser som gjelder for alle integrasjonsbaner.
• Agent 365-attributtreferanse for observerbarhet – Kanonisk strekkattributtskjema som hvert strekk registreres av Agent 365 må overholde.
• Microsoft OpenTelemetry Distro – Den anbefalte enhetlige SDK-en for nye integrasjoner.