SDK Παρατηρησιμότητας

Σημαντικό

Για να ενεργοποιήσετε την παρατηρησιμότητα στο Agent 365, χρησιμοποιήστε τη Microsoft OpenTelemetry Distro. Αυτή η διανομή παρέχει ένα ενιαίο SDK παρατηρησιμότητας σε όλη τη Microsoft, ενεργοποιώντας το Agent 365, το Microsoft Foundry, το Azure Monitor και άλλα. Η υπάρχουσα προσέγγιση που περιγράφεται σε αυτό το άρθρο συνεχίζει να λειτουργεί χωρίς ασυμβατότητες. Για οδηγίες μετεγκατάστασης ανά γλώσσα, ανατρέξτε στους παρακάτω οδηγούς:

Σημείωμα

Η παρατηρησιμότητα αποτελεί ένα από τα διαδοχικά επίπεδα δυνατοτήτων στην Ξεκινήστε με την ανάπτυξη του Agent 365 και ισχύει για όλους τους τύπους παραγόντων.

Για να συμμετάσχετε στο οικοσύστημα Agent 365, προσθέστε δυνατότητες παρατηρησιμότητας Agent 365 στον παράγοντά σας. Η παρατηρησιμότητα του Agent 365 βασίζεται στο OpenTelemetry (OTel) και παρέχει ένα ενοποιημένο πλαίσιο για την καταγραφή της τηλεμετρίας με συνέπεια και ασφάλεια σε όλες τις πλατφόρμες παραγόντων. Με την υλοποίηση αυτού του απαραίτητου στοιχείου, δίνετε τη δυνατότητα στους διαχειριστές IT να παρακολουθούν τη δραστηριότητα του παράγοντα σας στο Microsoft admin center και επιτρέπετε στις ομάδες ασφαλείας να χρησιμοποιούν το Defender και το Purview για συμμόρφωση και εντοπισμό απειλών.

Βασικά πλεονεκτήματα

  • Ορατότητα από άκρο σε άκρο: Καταγράψτε ολοκληρωμένη τηλεμετρία για κάθε κλήση παράγοντα, συμπεριλαμβανομένων περιόδων λειτουργίας, κλήσεων εργαλείων και εξαιρέσεων, παρέχοντας πλήρη ιχνηλασιμότητα σε όλες τις πλατφόρμες.
  • Ενεργοποίηση ασφάλειας και συμμόρφωσης: Τροφοδοτήστε ενοποιημένα αρχεία καταγραφής ελέγχου στο Defender και το Purview, επιτρέποντας προηγμένα σενάρια ασφαλείας και αναφορές συμμόρφωσης για τον παράγοντα σας.
  • Ευελιξία μεταξύ πλατφορμών: Βασιστείτε στα πρότυπα OTel και υποστηρίξτε διαφορετικούς χρόνους εκτέλεσης και πλατφόρμες όπως το Copilot Studio, το Foundry και μελλοντικά πλαίσια παραγόντων.
  • Λειτουργική αποτελεσματικότητα για διαχειριστές: Παρέχετε κεντρική παρατηρησιμότητα στο κέντρο διαχείρισης του Microsoft 365, μειώνοντας τον χρόνο αντιμετώπισης προβλημάτων και βελτιώνοντας τη διαχείριση με στοιχεία ελέγχου πρόσβασης βάσει ρόλων για ομάδες IT που διαχειρίζονται τον παράγοντά σας.

Υποστηριζόμενοι παράγοντες

Οι ακόλουθοι τύποι παραγόντων υποστηρίζουν την παρατηρησιμότητα του Agent 365:

Εγκατάσταση

Χρησιμοποιήστε αυτές τις εντολές για να εγκαταστήσετε τις μονάδες παρατηρησιμότητας για τις γλώσσες που υποστηρίζονται από το Agent 365.

Εγκαταστήστε τα πακέτα παρατηρησιμότητας και χρόνου εκτέλεσης. Όλοι οι παράγοντες που χρησιμοποιούν το Agent 365 Observability χρειάζονται αυτά τα πακέτα.

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

Εάν ο παράγοντας σας χρησιμοποιεί το πακέτο Microsoft Agents Hosting, εγκαταστήστε το πακέτο ενοποίησης φιλοξενίας. Παρέχει ενδιάμεσο λογισμικό που συμπληρώνει αυτόματα τα χαρακτηριστικά baggage και scopes από το TurnContext, και περιλαμβάνει προσωρινή αποθήκευση διακριτικών για τον observability exporter.

pip install microsoft-agents-a365-observability-hosting

Εάν ο παράγοντας σας χρησιμοποιεί ένα από τα υποστηριζόμενα AI frameworks, εγκαταστήστε την αντίστοιχη επέκταση αυτόματης οργανοποίησης ώστε να γίνεται αυτόματη καταγραφή τηλεμετρίας χωρίς την ανάγκη χειροκίνητης οργανοποίησης. Για λεπτομέρειες διαμόρφωσης, δείτε Αυτόματη οργανοποίηση.

# 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

Ρύθμιση παραμέτρων

Χρησιμοποιήστε τις παρακάτω ρυθμίσεις για να ενεργοποιήσετε και να προσαρμόσετε το Agent 365 Observability για τον παράγοντα σας.

Ορίστε τη μεταβλητή περιβάλλοντος ENABLE_A365_OBSERVABILITY_EXPORTER σε true για παρατηρησιμότητα. Αυτή η ρύθμιση εξάγει τα αρχεία καταγραφής στην υπηρεσία και απαιτεί να παρέχεται ένα token_resolver. Διαφορετικά, χρησιμοποιείται ο εξαγωγέας κονσόλας.

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

Ο μηχανισμός επίλυσης διακριτικών δεν καταγράφεται στην κονσόλα.

Μπορείτε να προσαρμόσετε τη συμπεριφορά του εξαγωγέα παρέχοντας μια Agent365ExporterOptions παρουσία στο exporter_options. Όταν παρέχεται το exporter_options, έχει προτεραιότητα έναντι των παραμέτρων token_resolver και 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,
)

Ο παρακάτω πίνακας περιγράφει τις προαιρετικές παραμέτρους για configure().

Παράμετρος Περιγραφή Προεπιλογή
logger_name Το όνομα του Python logger που χρησιμοποιείται για εντοπισμό σφαλμάτων και έξοδο καταγραφής στην κονσόλα. microsoft_agents_a365.observability.core
exporter_options Ένα Agent365ExporterOptions αντικείμενο που διαμορφώνει από κοινού τον resolver διακριτικών και την κατηγορία συμπλέγματος. None
suppress_invoke_agent_input Όταν True, αποκρύπτει μηνύματα εισόδου στα spans του InvokeAgent. False

Ο παρακάτω πίνακας περιγράφει τις προαιρετικές ιδιότητες για Agent365ExporterOptions.

Ιδιότητα Περιγραφή Προεπιλογή
use_s2s_endpoint Όταν True, χρησιμοποιείται η διαδρομή τερματικού σημείου υπηρεσία προς υπηρεσία. False
max_queue_size Μέγιστη χωρητικότητα ουράς για τον επεξεργαστή παρτίδας. 2048
scheduled_delay_ms Καθυστέρηση σε χιλιοστά του δευτερολέπτου μεταξύ των παρτίδων εξαγωγής. 5000
exporter_timeout_ms Χρονικό όριο σε χιλιοστά του δευτερολέπτου για τη λειτουργία εξαγωγής. 30000
max_export_batch_size Μέγιστο μέγεθος παρτίδας για εξαγωγικές εργασίες. 512

Χαρακτηριστικά αποσκευών

Χρησιμοποιήστε BaggageBuilder για να ορίσετε συμφραζόμενες πληροφορίες που μεταφέρονται σε όλα τα span μιας αίτησης. Το SDK υλοποιεί έναν SpanProcessor που αντιγράφει όλες τις μη κενές καταχωρήσεις αποσκευών σε νέα span χωρίς να αντικαθιστά υπάρχοντα χαρακτηριστικά.

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 από το TurnContext, χρησιμοποιήστε τον βοηθό populate στο πακέτο microsoft-agents-a365-observability-hosting. Αυτός ο βοηθός εξάγει αυτόματα λεπτομέρειες καλούντος, παράγοντας, μισθωτή, καναλιού και συνομιλίας από τη δραστηριότητα.

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

Ενδιάμεσο λογισμικό διαχείρισης αποσκευών

Εάν ο παράγοντας σας χρησιμοποιεί το πακέτο ενσωμάτωσης φιλοξενίας, καταχωρήστε το ενδιάμεσο λογισμικό αποσκευών ώστε να ενημερώνονται αυτόματα οι αποσκευές για κάθε εισερχόμενο αίτημα. Αυτό το βήμα εξαλείφει την ανάγκη χειροκίνητης κλήσης του BaggageBuilder σε κάθε χειριστή δραστηριότητας.

Καταχωρίστε το BaggageMiddleware στο σύνολο ενδιάμεσου λογισμικού του προσαρμογέα. Ανακτά αυτόματα τα στοιχεία του καλούντος, του παράγοντα, του μισθωτή, του καναλιού και της συνομιλίας από κάθε εισερχόμενο TurnContext και εντάσσει το αίτημα σε ένα πεδίο εφαρμογής αποσκευών.

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

Εναλλακτικά, χρησιμοποιήστε το ObservabilityHostingManager για να διαμορφώσετε το baggage middleware μαζί με άλλες δυνατότητες φιλοξενίας:

from microsoft_agents_a365.observability.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

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

Το ενδιάμεσο λογισμικό παραλείπει τη ρύθμιση αποσκευών για ασύγχρονες απαντήσεις (ContinueConversation συμβάντα) για να αποφύγει την αντικατάσταση αποσκευών που έχει ήδη ορίσει η αρχική αίτηση.

Μηχανισμός επίλυσης διακριτικών

Όταν χρησιμοποιείτε τον εξαγωγέα Agent 365, πρέπει να παρέχετε μια συνάρτηση επίλυσης διακριτικών που επιστρέφει ένα διακριτικό ελέγχου ταυτότητας. Όταν χρησιμοποιείτε το SDK παρατηρησιμότητας Agent 365 με το πλαίσιο φιλοξενίας παράγοντα, μπορείτε να δημιουργήσετε διακριτικά χρησιμοποιώντας τις TurnContext δραστηριότητες από παράγοντα.

Το παρακάτω απόσπασμα δείχνει πώς μπορείτε να δημιουργήσετε ένα διακριτικό χρησιμοποιώντας το microsoft_agents.hosting.core SDK. Το διακριτικό ελέγχου ταυτότητας που δημιουργείται εδώ χρησιμοποιείται για την εξαγωγή των καλύψεων στην υπηρεσία απορρόφησης A365. Οι παράγοντες μπορούν να δημιουργήσουν διακριτικό οι ίδιοι, για παράδειγμα χρησιμοποιώντας τη Βιβλιοθήκη ελέγχου ταυτότητας της Microsoft (MSAL), αλλά πρέπει να διασφαλίσουν ότι το διακριτικό έχει το πεδίο παρατηρησιμότητας.

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

Για έναν παράγοντα που έχει δημιουργηθεί με το Agent 365 CLI και χρησιμοποιεί έναν AI συνεργάτη και το πακέτο Microsoft Agent 365 Observability Hosting Library, χρησιμοποιήστε το AgenticTokenCache να χειριστείτε αυτόματα την προσωρινή αποθήκευση διακριτικών. Καταχωρίστε το διακριτικό μία φορά ανά παράγοντα και μισθωτή κατά τη διάρκεια ενός διαχειριστή δραστηριότητας και περάστε το cache.get_observability_token ως το token_resolver στη διαμόρφωση παρατηρησιμότητας σας.

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

Αυτο-οργανοποίηση

Η αυτόματη οργανοποίηση παρακολουθεί αυτόματα τα υπάρχοντα σήματα τηλεμετρίας των πλαισίων παραγόντων (SDK) για ίχνη και τα προωθεί στην υπηρεσία παρατηρησιμότητας του Agent 365. Αυτή η δυνατότητα εξαλείφει την ανάγκη των προγραμματιστών να γράφουν κώδικα παρακολούθησης με μη αυτόματο τρόπο, απλοποιεί τη ρύθμιση και διασφαλίζει συνεπή παρακολούθηση απόδοσης.

Σημαντικό

Η αυτόματη οργανοποίηση συμπληρώνει μόνο τυπικά χαρακτηριστικά OTel. Πρέπει να προσθέσετε χαρακτηριστικά ειδικά για τη Microsoft μέσω BaggageBuilder. Για να δείτε ποια χαρακτηριστικά λείπουν, επαληθεύστε την έξοδο των καλύψεων της κονσόλας σας σε σχέση με τα αρχεία καταγραφής αποθήκευσης για το διαφορετικό σύνολο.

Πολλά SDK και πλατφόρμες υποστηρίζουν αυτόματη οργανοποίηση:

Πλατφόρμα Υποστηριζόμενα SDK / Πλαίσια
.NET Semantic Kernel, OpenAI, Agent Framework
Python Semantic Kernel, OpenAI, Agent Framework, LangChain
Node.js OpenAI, LangChain

Σημείωμα

Η υποστήριξη για αυτόματη ενόργανη παρακολούθηση διαφέρει ανάλογα με την πλατφόρμα και την υλοποίηση του SDK.

Σημασιολογικός πυρήνας

Η αυτόματη ενόργανη παρακολούθηση απαιτεί τη χρήση του baggage builder. Ορίστε το αναγνωριστικό παράγοντα και το αναγνωριστικό μισθωτή χρησιμοποιώντας το BaggageBuilder.

Εγκατάσταση πακέτου.

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

Διαμορφώστε την παρατηρησιμότητα.

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

OpenAI

Η αυτόματη ενόργανη παρακολούθηση απαιτεί τη χρήση του baggage builder. Ορίστε το αναγνωριστικό παράγοντα και το αναγνωριστικό μισθωτή χρησιμοποιώντας το BaggageBuilder.

Εγκατάσταση πακέτου.

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

Διαμορφώστε την παρατηρησιμότητα.

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

Agent Framework

Η αυτόματη ενόργανη παρακολούθηση απαιτεί τη χρήση του baggage builder. Ορίστε το αναγνωριστικό παράγοντα και το αναγνωριστικό μισθωτή χρησιμοποιώντας το BaggageBuilder.

Εγκατάσταση πακέτου.

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

Διαμορφώστε την παρατηρησιμότητα.

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

Πλαίσιο LangChain

Η αυτο-οργανοποίηση απαιτεί τη χρήση του δημιουργού αποσκευών. Ορίστε το αναγνωριστικό παράγοντα και το αναγνωριστικό μισθωτή χρησιμοποιώντας το BaggageBuilder.

Εγκατάσταση πακέτου.

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

Διαμορφώστε την παρατηρησιμότητα.

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

Χειροκίνητη καταγραφή

Χρησιμοποιήστε το SDK παρατηρησιμότητας του Agent 365 για να κατανοήσετε την εσωτερική λειτουργία του παράγοντα. Το SDK παρέχει εμβέλειες που μπορείτε να ξεκινήσετε: InvokeAgentScope, ExecuteToolScope, InferenceScopeκαι OutputScope.

Επίκληση παράγοντα

Χρησιμοποιήστε αυτό το πεδίο στην αρχή της διαδικασίας του παράγοντα. Χρησιμοποιώντας το πεδίο κλήση παράγοντα, μπορείτε να καταγράψετε ιδιότητες όπως τον τρέχοντα παράγοντα που καλείται, τα δεδομένα χρήστη του παράγοντα και άλλα.

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

Εκτέλεση εργαλείου

Τα παρακάτω παραδείγματα δείχνουν πώς μπορείτε να προσθέσετε παρακολούθηση παρατηρησιμότητας στην εκτέλεση του εργαλείου του παράγοντά σας. Αυτή η παρακολούθηση καταγράφει τηλεμετρία για σκοπούς παρακολούθησης και ελεγκτικούς.

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)

Συμπερασματική λογική

Τα παρακάτω παραδείγματα δείχνουν πώς να οργανώσετε κλήσεις πρόβλεψης (inference) μοντέλου AI με παρακολούθηση παρατηρησιμότητας, ώστε να καταγράψετε τη χρήση διακριτικών, τα στοιχεία του μοντέλου και τα μεταδεδομένα της απόκρισης.

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)

Έξοδος

Χρησιμοποιήστε αυτό το scope για ασύγχρονα σενάρια όπου InvokeAgentScope, ExecuteToolScope ή InferenceScope δεν μπορούν να καταγράψουν δεδομένα εξόδου συγχρονισμένα. Ξεκινήστε OutputScope μια θυγατρική κάλυψη για να καταγράψετε τα τελικά μηνύματα εξόδου μόλις ολοκληρωθεί το γονικό πεδίο.

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

Τοπική επικύρωση

Για να επαληθεύσετε ότι έχετε ενσωματωθεί με επιτυχία στο SDK παρατηρησιμότητας, εξετάστε τα αρχεία καταγραφής της κονσόλας που δημιουργεί ο παράγοντας σας και τα αρχεία καταγραφής από το SDK παρατηρησιμότητας.

Ορίστε τη μεταβλητή περιβάλλοντος ENABLE_A365_OBSERVABILITY_EXPORTER σε false. Αυτή η ρύθμιση εξάγει καλύψεις (ίχνη) στην κονσόλα.

Για να διερευνήσετε αποτυχίες εξαγωγής, ενεργοποιήστε λεπτομερή καταγραφή ορίζοντας τη μεταβλητή περιβάλλοντος ENABLE_A365_OBSERVABILITY_EXPORTER σε true και ρυθμίζοντας την καταγραφή εντοπισμού σφαλμάτων κατά την εκκίνηση της εφαρμογής σας:

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)

Βασικά μηνύματα καταγραφής:

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.

Προβολή εξαγόμενων καταγραφών

Για να προβάλετε την τηλεμετρία παράγοντα στο Microsoft Purview ή το Microsoft Defender, βεβαιωθείτε ότι πληρούνται οι ακόλουθες απαιτήσεις:

Επικύρωση για δημοσίευση στο Store

Σημαντικό

Για επιτυχή επικύρωση στο Store, ο παράγοντας σας πρέπει να υλοποιήσει τα InvokeAgentScope, InferenceScope και ExecuteToolScope scopes. Αυτά τα τρία πεδία απαιτούνται για τη δημοσίευση.

Πριν τη δημοσίευση, χρησιμοποιήστε τα αρχεία καταγραφής κονσόλας για να επαληθεύσετε την ενοποίηση παρατηρησιμότητας του παράγοντας εφαρμόζοντας τα απαιτούμενα invoke agent, execute tool, inference και output πεδία. Στη συνέχεια, συγκρίνετε τα αρχεία καταγραφής του παράγοντα σας με τις παρακάτω λίστες χαρακτηριστικών για να επαληθεύσετε ότι υπάρχουν όλα τα απαιτούμενα χαρακτηριστικά. Καταγράψτε τα χαρακτηριστικά σε κάθε πεδίο ή χρησιμοποιώντας τον δημιουργό αποσκευών, και προσθέστε προαιρετικά χαρακτηριστικά κατά την κρίση σας.

Για περισσότερες πληροφορίες σχετικά με τις απαιτήσεις δημοσίευσης στο Store, ανατρέξτε στις οδηγίες επικύρωσης του Store.

InvokeAgentScope χαρακτηριστικά

Η ακόλουθη λίστα συνοψίζει τα απαιτούμενα και προαιρετικά χαρακτηριστικά τηλεμετρίας που καταγράφονται όταν ξεκινάτε ένα 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 χαρακτηριστικά

Η ακόλουθη λίστα συνοψίζει τα απαιτούμενα και προαιρετικά χαρακτηριστικά τηλεμετρίας που καταγράφονται όταν ξεκινάτε ένα 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 χαρακτηριστικά

Η ακόλουθη λίστα συνοψίζει τα απαιτούμενα και προαιρετικά χαρακτηριστικά τηλεμετρίας που καταγράφονται όταν ξεκινάτε ένα 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 χαρακτηριστικά

Η ακόλουθη λίστα συνοψίζει τα απαιτούμενα και προαιρετικά χαρακτηριστικά τηλεμετρίας που καταγράφονται όταν ξεκινάτε ένα OutputScope. Χρησιμοποιήστε αυτό το πεδίο για ασύγχρονα σενάρια όπου το γονικό πεδίο δεν μπορεί να καταγράψει δεδομένα εξόδου συγχρονισμένα.

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

Δοκιμάστε τον παράγοντα σας με παρατηρησιμότητα

Αφού εφαρμόσετε την παρατηρησιμότητα στον παράγοντα σας, δοκιμάστε τον για να βεβαιωθείτε ότι καταγράφει σωστά την τηλεμετρία. Ακολουθήστε τον οδηγό δοκιμών για να ρυθμίσετε το περιβάλλον σας. Στη συνέχεια, επικεντρωθείτε κυρίως στην ενότητα Προβολή αρχείων καταγραφής παρατηρησιμότητας για να επαληθεύσετε ότι η υλοποίηση παρατηρησιμότητας λειτουργεί όπως αναμένεται.

Επαλήθευση:

  • Μετάβαση σε: https://admin.cloud.microsoft/#/agents/all
  • Επιλέξτε τον παράγοντά σας > Δραστηριότητα
  • Βλέπετε συνεδρίες και κλήσεις εργαλείων

Αντιμετώπιση προβλημάτων

Αυτή η ενότητα περιγράφει κοινά προβλήματα κατά την υλοποίηση και τη χρήση της παρατηρησιμότητας.

Πρόβλημα Περιγραφή
Δεν εμφανίζονται δεδομένα παρατηρησιμότητας Δεν είναι ορατή καμία τηλεμετρία επειδή η εξαγωγή δεν είναι ενεργοποιημένη, η διαμόρφωση είναι λανθασμένη ή η επίλυση διακριτικού αποτυγχάνει.
Λείπει το αναγνωριστικό μισθωτή ή το αναγνωριστικό παράγοντα - τα span παραλείπονται Οι καλύψεις απορρίπτονται πριν από την εξαγωγή όταν λείπουν τα χαρακτηριστικά ταυτότητας που απαιτούνται για την κατάτμηση.
Αποτυχία επίλυσης διακριτικού - η εξαγωγή παραλείφθηκε ή δεν ήταν εξουσιοδοτημένη Τα αιτήματα εξαγωγής αποτυγχάνουν ή παραλείπονται όταν ο μηχανισμός επίλυσης δεν επιστρέφει διακριτικό ή συναντά μια εξαίρεση.
HTTP 401 Χωρίς εξουσιοδότηση Ο έλεγχος ταυτότητας είναι επιτυχής συντακτικά, αλλά το διακριτικό είναι άκυρο για εισαγωγή λόγω εμβέλειας, τύπου ή λήξης.
HTTP 403 Απαγορεύεται Η πρόσβαση δεν επιτρέπεται λόγω ελλείψεων στις άδειες χρήσης του μισθωτή ή έλλειψης δικαιωμάτων παρατηρησιμότητας.
HTTP 403 Απαγορεύεται - Αναντιστοιχία αναγνωριστικού παράγοντα Η αίτηση απορρίπτεται όταν η ταυτότητα του παράγοντα στη διεύθυνση URL δεν αντιστοιχεί με την ταυτότητα που αντιπροσωπεύεται από το διακριτικό.
Σφάλματα HTTP 429 ή 5xx - Παροδικά σφάλματα Ο προσωρινός περιορισμός ή τα σφάλματα από την πλευρά της υπηρεσίας διακόπτουν την εξαγωγή και ενδέχεται να απαιτούν προσαρμογή των επαναλήψεων.
Λήξη χρονικού ορίου εξαγωγής Οι δέσμες τηλεμετρίας υπερβαίνουν τα διαμορφωμένα χρονικά όρια λόγω καθυστέρησης δικτύου ή απόκρισης τερματικού σημείου.
Η εξαγωγή είναι επιτυχής, αλλά η τηλεμετρία δεν εμφανίζεται στο Defender ή στο Purview Η εισαγωγή ολοκληρώνεται, αλλά η ορατότητα στα επόμενα στάδια καθυστερεί ή εμποδίζεται από τα προαπαιτούμενα του προϊόντος.

Φιλοδώρημα

Ο Οδηγός αντιμετώπισης προβλημάτων του Agent 365 περιλαμβάνει συστάσεις αντιμετώπισης προβλημάτων υψηλού επιπέδου, βέλτιστες πρακτικές και συνδέσμους για περιεχόμενο αντιμετώπισης προβλημάτων για κάθε μέρος του κύκλου ζωής ανάπτυξης του Agent 365.

Δεν εμφανίζονται δεδομένα παρατηρησιμότητας

Συμπτώματα:

  • Ο παράγοντας εκτελείται
  • Δεν υπάρχει τηλεμετρία στο κέντρο διαχείρισης
  • Δεν είναι δυνατή η προβολή δραστηριότητας παράγοντα

Ριζική αιτία:

  • Η παρατηρησιμότητα δεν είναι ενεργοποιημένη
  • Σφάλματα ρύθμισης παραμέτρων
  • Προβλήματα με τον επιλυτή διακριτικών

Λύσεις: Δοκιμάστε τα παρακάτω βήματα για να επιλύσετε το πρόβλημα:

  • Βεβαιωθείτε ότι ο εξαγωγέας παρατηρησιμότητας είναι ενεργοποιημένος

    Πρέπει να ενεργοποιήσετε ρητά τον εξαγωγέα Agent 365. Όταν απενεργοποιηθεί, το SDK επιστρέφει σε έναν εξαγωγέα κονσόλας και η τηλεμετρία δεν αποστέλλεται στην υπηρεσία. Για λεπτομέρειες ρύθμισης παραμέτρων, δείτε Ρύθμιση παραμέτρων.

  • Ελέγξτε τη διαμόρφωση του προγράμματος επίλυσης διακριτικών

    Ο εξαγωγέας απαιτεί ένα έγκυρο πρόγραμμα επίλυσης διακριτικών που να επιστρέφει ένα διακριτικό φορέα για κάθε αίτημα εξαγωγής. Εάν το πρόγραμμα επίλυσης διακριτικών λείπει ή επιστρέφει null, η εξαγωγή παραλείπεται σιωπηλά. Βεβαιωθείτε ότι ο κώδικάς σας υλοποιεί σωστά τον μηχανισμό επίλυσης διακριτικών. Για λεπτομέρειες, δείτε τον Μηχανισμό επίλυσης διακριτικών.

  • Έλεγχος σφαλμάτων στα αρχεία καταγραφής

    Ενεργοποιήστε τη λεπτομερή καταγραφή και χρησιμοποιήστε την az webapp log tail εντολή για να αναζητήσετε σφάλματα που σχετίζονται με την παρατηρησιμότητα στα αρχεία καταγραφής. Για λεπτομέρειες σχετικά με τον τρόπο ενεργοποίησης της καταγραφής ανά πλατφόρμα, ανατρέξτε στην ενότητα Τοπική επικύρωση.

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

  • Επαλήθευση εξαγωγής τηλεμετρίας

    Επιβεβαιώστε ότι η τηλεμετρία δημιουργείται και εξάγεται όπως αναμένεται.

    • Προσθέστε έναν εξαγωγέα κονσόλας και ελέγξτε αν η τηλεμετρία παράγεται τοπικά. Για λεπτομέρειες σχετικά με τον τρόπο χρήσης του εξαγωγέα κονσόλας και την επαλήθευση του αποτελέσματος, ανατρέξτε στο θέμα Τοπική επαλήθευση.

Λείπει το αναγνωριστικό μισθωτή ή το αναγνωριστικό πράκτορα — τα spans παραλείπονται

Συμπτώματα: Το σύστημα απορρίπτει σιωπηλά spans και δεν τα εξάγει ποτέ. Ορισμένα SDK καταγράφουν τον αριθμό των παραλειφθέντων καλύψεων ή ένα μήνυμα όπως «Δεν βρέθηκαν καλύψεις με ταυτότητα μισθωτή/παράγοντα». Άλλα τα παραλείπουν χωρίς καταγραφή.

Επίλυση:

  • Πριν από την εξαγωγή, το SDK διαχωρίζει τις καλύψεις ανά ταυτότητα μισθωτή και παράγοντα. Το σύστημα απορρίπτει καλύψεις που στερούνται είτε αναγνωριστικού μισθωτή είτε αναγνωριστικού παράγοντα και δεν τα στέλνει ποτέ στην υπηρεσία.
  • Βεβαιωθείτε ότι BaggageBuilder έχει ρυθμιστεί με το αναγνωριστικό μισθωτή και το αναγνωριστικό παράγοντα πριν δημιουργήσετε spans. Αυτές οι τιμές διαδίδονται μέσω του περιβάλλοντος OpenTelemetry και συνδέονται με όλα τα spans που δημιουργούνται εντός του πεδίου αποσκευών. Για το API της συγκεκριμένης πλατφόρμας, ανατρέξτε στην ενότητα Χαρακτηριστικά αποσκευών.
  • Βεβαιωθείτε ότι η TurnContext δραστηριότητα έχει έγκυρο παραλήπτη με ταυτότητα παράγοντα, εάν χρησιμοποιείτε το ενδιάμεσο λογισμικό αποσκευών ή τον βοηθό περιβάλλοντος από το πακέτο φιλοξενίας για να συμπληρώσετε αυτά τα αναγνωριστικά.

Αποτυχία ανάλυσης διακριτικού — η εξαγωγή παραλείφθηκε ή δεν εγκρίθηκε

Συμπτώματα: Το πρόγραμμα επίλυσης διακριτικών επιστρέφει null ή εμφανίζει ένα σφάλμα. Ανάλογα με το SDK, η εξαγωγή είτε παραλείπεται εντελώς είτε το αίτημα αποστέλλεται χωρίς κεφαλίδα εξουσιοδότησης και αποτυγχάνει με HTTP 401.

Επίλυση:

  • Ο πρόγραμμα επίλυσης διακριτικών απαιτείται κατά την αρχικοποίηση. Εάν λείπει, ο εξαγωγέας εμφανίζει σφάλμα κατά την εκκίνηση. Βεβαιωθείτε ότι παρέχεται ένα πρόγραμμα επίλυσης διακριτικών και επιστρέφει ένα έγκυρο διακριτικό φορέα.
  • Βεβαιωθείτε ότι χρησιμοποιούνται τα σωστά tenant ID και ID παράγοντα για BaggageBuilder, επειδή αυτές οι τιμές περνούν στον token resolver.
  • Για παράγοντες που φιλοξενούνται στο Azure, βεβαιωθείτε ότι η διαχειριζόμενη ταυτότητα διαθέτει την απαιτούμενη άδεια API για το πεδίο παρατηρησιμότητας.

HTTP 401 Χωρίς εξουσιοδότηση

Συμπτώματα: Η εξαγωγή αποτυγχάνει με HTTP 401. Ο εξαγωγέας δεν επιχειρεί ξανά αυτό το σφάλμα.

Επίλυση:

  • Βεβαιωθείτε ότι το ακροατήριο του διακριτικού ταιριάζει με το πεδίο του τελικού σημείου παρατηρησιμότητας.
  • Ελέγξτε ότι ο επιλυτής διακριτικού δεν επιστρέφει διακριτικό πληρεξούσιου χρήστη, διακριτικό για εσφαλμένο κοινό ή διακριτικό που έχει λήξει.

HTTP 403 Απαγορεύεται

Συμπτώματα: Η εξαγωγή αποτυγχάνει με HTTP 403. Ο εξαγωγέας δεν επιχειρεί ξανά αυτό το σφάλμα.

Βασική αιτία: Ένα σφάλμα HTTP 403 μπορεί να έχει διαφορετικές αιτίες. Ελέγξτε τις παρακάτω λύσεις με τη σειρά.

Επίλυση:

  • Λείπει άδεια χρήσης — Βεβαιωθείτε ότι ο μισθωτής σας έχει εκχωρηθεί μία από τις ακόλουθες άδειες χρήσης στο Κέντρο διαχείρισης Microsoft 365:

    • Δοκιμή - Microsoft 365 E7
    • Microsoft 365 E7
    • Microsoft Agent 365 Frontier

  • Λείπει Agent365.Observability.OtelWriteάδεια — Εάν αναβαθμίσατε πρόσφατα τα πακέτα παρατηρησιμότητας, πρέπει να χορηγήσετε αυτήν την άδεια. Δείτε τη σημαντική σημείωση στην επόμενη ενότητα.

Σημαντικό

Οι υπάρχοντες παράγοντες που αναβαθμίζονται σε αυτές τις εκδόσεις πακέτων απαιτούν ένα επιπλέον βήμα

Αυτό το βήμα ισχύει μόνο εάν αναβαθμίζετε έναν υπάρχοντα παράγοντας. Οι εγκαταστάσεις νέων παράγοντες δεν απαιτούν αυτό το βήμα. Εάν αναβαθμίζετε στις ακόλουθες εκδόσεις πακέτων ή νεότερες, πρέπει να παραχωρήσετε τη νέα άδεια Agent365.Observability.OtelWrite στην ταυτότητά σας (Διαχειριζόμενη Ταυτότητα ή εγγραφή εφαρμογής). Χωρίς αυτήν την άδεια, η εξαγωγή τηλεμετρίας αποτυγχάνει με το HTTP 403.

Πλατφόρμα Ελάχιστη έκδοση που απαιτεί αυτό το βήμα
.NET 0.3-beta
Node.js 0.2.0-preview.1
Python 0.3.0

Παραχωρήστε την άδεια χρησιμοποιώντας μία από τις ακόλουθες επιλογές.

Επιλογή A — Agent 365 CLI (απαιτείται λογαριασμός καθολικού διαχειριστή· εκτελέστε από τον κατάλογο έργου του παράγοντας που περιέχει a365.config.json, ή χρησιμοποιήστε --agent-name)

a365 setup permissions bot

Ή χωρίς αρχείο ρυθμίσεων:

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

Αυτή η εντολή εκχωρεί όλα τα δικαιώματα που λείπουν στη δομή προγράμματος, συμπεριλαμβανομένων των πεδίων Παρατηρησιμότητας.

Επιλογή B — Entra Portal (χωρίς αρχεία ρυθμίσεων· απαιτείται δικαίωμα καθολικού διαχειριστή στην εγγραφή της εφαρμογής Blueprint)

  1. Μεταβείτε στην πύλη Entra>Εγγραφές εφαρμογών> επιλέξτε την εφαρμογή Blueprint.
  2. Μεταβείτε στα Δικαιώματα API>Προσθήκη δικαιώματος>API που χρησιμοποιεί ο οργανισμός σας> αναζητήστε 9b975845-388f-4429-889e-eab1ef63949c.
  3. Επιλέξτε Δικαιώματα με ανάθεση> επιλέξτε Agent365.Observability.OtelWrite>Προσθήκη δικαιωμάτων.
  4. Επαναλάβετε το βήμα 2–3, αυτή τη φορά επιλέξτε Δικαιώματα εφαρμογής>, επιλέξτε Agent365.Observability.OtelWrite>Προσθήκη δικαιωμάτων.
  5. Κάντε κλικ στην επιλογή Παροχή συγκατάθεσης διαχειριστή και επιβεβαιώστε.

Τόσο τα Agent365.Observability.OtelWrite (Δικαιώματα ανάθεσης) όσο και τα Agent365.Observability.OtelWrite (Δικαιώματα εφαρμογής) πρέπει να εμφανίζουν Granted κατάσταση.

HTTP 403 Απαγορεύεται — Αναντιστοιχία αναγνωριστικού παράγοντα

Συμπτώματα: Η εξαγωγή αποτυγχάνει με HTTP 403 και ένα μήνυμα διακομιστή παρόμοιο με το 403 Forbidden, καθώς και agent-ID-mismatch αποτυχίες κατά την κλήση των τελικών σημείων καταγραφών του Agent 365.

Βασική αιτία: Αυτό το σφάλμα εμφανίζεται όταν χρησιμοποιείτε το αναγνωριστικό πελάτη του blueprint αντί για το αναγνωριστικό πελάτη του παράγοντα κατά τη ρύθμιση των στοιχείων του παράγοντα. Το αναγνωριστικό του παράγοντα στη διεύθυνση εξαγωγής δεν αντιστοιχεί στην ταυτότητα που έχει εξουσιοδοτηθεί μέσω του διακριτικού, με αποτέλεσμα το τελικό σημείο ανιχνεύσεων να απορρίπτει το αίτημα.

Επίλυση:

  • Επαληθεύστε αν το αναγνωριστικό μισθωτή έχει προστεθεί στη λίστα επιτρεπομένων μισθωτών του Agent 365.
  • Ορίστε τα στοιχεία του παράγοντα με το αναγνωριστικό πελάτη παρουσίας παράγοντα (όχι το αναγνωριστικό πελάτη blueprint).
  • Επαληθεύστε τη διεύθυνση URL εξαγωγής που δημιουργείται – καταγράφεται εάν ενεργοποιήσετε τον καταγραφέα σας. Βεβαιώστε ότι το αναγνωριστικό παράγοντα στη διεύθυνση URL αντιστοιχεί στο αναγνωριστικό πελάτη παρουσίας παράγοντα.
  • Για να ενεργοποιήσετε την καταγραφή διαγνωστικών για κάθε SDK, δείτε την ενότητα Τοπική επικύρωση.

Σφάλματα HTTP 429 ή 5xx - Παροδικά σφάλματα

Συμπτώματα: Η εξαγωγή αποτυγχάνει με έναν προσωρινό κωδικό κατάστασης HTTP, όπως 429 ή 5xx.

Επίλυση:

  • Αυτά τα σφάλματα είναι συνήθως παροδικά και επιλύονται από μόνα τους. Τα SDKs Python και JavaScript επαναλαμβάνουν αυτόματα τις αιτήσεις όταν λαμβάνουν τους κωδικούς κατάστασης HTTP 408, 429 και 5xx, έως και τρεις φορές, με εκθετική αναμονή. Το .NET SDK δεν επιχειρεί ξανά αυτόματα.
  • Εάν τα σφάλματα επιμείνουν, ελέγξτε τον πίνακα υγείας της υπηρεσίας.
  • Εξετάστε το ενδεχόμενο να μειώσετε τη συχνότητα εξαγωγής αυξάνοντας την προγραμματισμένη καθυστέρηση μεταξύ των δεσμών ή αυξάνοντας το μέγιστο μέγεθος δέσμης εξαγωγής. Για επιλογές διαμόρφωσης ανά πλατφόρμα, ανατρέξτε στον Agent365ExporterOptions πίνακα στο Ρύθμιση παραμέτρων.

Λήξη χρονικού ορίου εξαγωγής

Συμπτώματα: Οι προσπάθειες εξαγωγής λήγουν λόγω χρονικού ορίου.

Επίλυση:

  • Ελέγξτε τη συνδεσιμότητα δικτύου με το τελικό σημείο παρατηρησιμότητας.
  • Οι προεπιλογές χρονικού ορίου διαφέρουν ανάλογα με την πλατφόρμα. Το προεπιλεγμένο χρονικό όριο αίτησης HTTP είναι 30 δευτερόλεπτα. Ορισμένα SDK έχουν επίσης ξεχωριστό συνολικό χρονικό όριο για τον εξαγωγέα που καλύπτει όλο τον κύκλο εξαγωγής, συμπεριλαμβανομένων των επαναλήψεων. Για τις ακριβείς ιδιότητες και τις προεπιλογές ανά πλατφόρμα, δείτε τον Agent365ExporterOptions πίνακα στην ενότητα Configuration.
  • Εάν τα χρονικά όρια παρουσιάζονται συχνά, αυξήστε τη σχετική τιμή χρονικού ορίου στις ρυθμίσεις του εξαγωγέα.

Η εξαγωγή είναι επιτυχής, αλλά η τηλεμετρία δεν εμφανίζεται στο Defender ή στο Purview

Συμπτώματα: Τα αρχεία καταγραφής εμφανίζουν μια επιτυχημένη εξαγωγή, αλλά η τηλεμετρία δεν είναι ορατή στο Microsoft Defender ή στο Microsoft Purview.

Επίλυση:

  • Βεβαιωθείτε ότι πληροίτε τις προϋποθέσεις για την προβολή των αρχείων καταγραφής που έχουν εξαχθεί. Για το Purview, ο έλεγχος πρέπει να είναι ενεργοποιημένος. Για το Defender, πρέπει να διαμορφώσετε το προηγμένο κυνήγι. Για περισσότερες πληροφορίες, δείτε Προβολή αρχείων καταγραφής που έχουν εξαχθεί.
  • Η τηλεμετρία μπορεί να χρειαστεί αρκετά λεπτά για να εμφανιστεί μετά από μια επιτυχημένη εξαγωγή. Περιμένετε να εμφανιστούν τα δεδομένα πριν προχωρήσετε σε περαιτέρω διερεύνηση.

Για να μάθετε περισσότερα σχετικά με τη δοκιμή της παρατηρησιμότητας, δείτε:

Σχετικό περιεχόμενο

  • Last updated on