Microsoft OpenTelemetry Distro

Το Microsoft OpenTelemetry Distro είναι μια ενοποιημένη διανομή παρατηρησιμότητας που προσφέρει μια ενιαία εμπειρία αρχικής ρύθμισης για τη συλλογή ιχνηλατήσεων, μετρήσεων και αρχείων καταγραφής από εφαρμογές με ή χωρίς παράγοντα. Υποστηρίζει παρατηρησιμότητα για το Microsoft Agent 365, το Microsoft Foundry, το Azure Monitor και οποιοδήποτε backend συμβατό με το πρωτόκολλο OpenTelemetry (OTLP). Η διανομή υποστηρίζει .NET, Node.js και Python και αντικαθιστά την κατακερματισμένη ρύθμιση σε πολλαπλές στοίβες παρατηρησιμότητας με μία εισαγωγή και μία κλήση διαμόρφωσης.

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

Το Microsoft OpenTelemetry Distro παρέχει τα εξής οφέλη:

  • Ένα πακέτο, ένα API: Αντικαταστήστε πολλά πακέτα εξαγωγής και εργαλείων παρακολούθησης με μία μόνο εξάρτηση.
  • Υποστήριξη πολλαπλών backend: Αποστείλετε τηλεμετρία στο Azure Monitor, σε οποιοδήποτε συμβατό με το τελικό σημείο του OpenTelemetry Protocol (OTLP) όπως το Datadog, το Grafana ή το New Relic και το Microsoft Agent 365 ταυτόχρονα.
  • Ενσωματωμένες παρακολουθήσεις: Χρησιμοποιήστε αυτόματη παρακολούθηση για HTTP, βάσεις δεδομένων, Azure SDK, Azure Functions και πολλά άλλα χωρίς επιπλέον ρύθμιση παραμέτρων.
  • Βασισμένο σε πρότυπα: Βασιστείτε στο OpenTelemetry, το πρότυπο της βιομηχανίας για πλαίσιο παρατηρησιμότητας.
  • Ελάχιστο μόνιμο κείμενο: Προσθέστε μία εντολή εισαγωγής και μία κλήση συνάρτησης στο σημείο εισόδου της εφαρμογής σας.

Εγκατάσταση και ρύθμιση παραμέτρων

Αυτή η οδηγία σας δείχνει πώς να προσθέσετε παρατηρησιμότητα στην εφαρμογή σας με το Microsoft OpenTelemetry Distro. Το Distro συλλέγει αυτόματα ίχνη, μετρικές και καταγραφές με ενσωματωμένες παρακολουθήσεις και εξάγει την τηλεμετρία στο Azure Monitor, σε οποιοδήποτε τελικό σημείο OpenTelemetry Protocol (OTLP) ή στο Microsoft Agent 365.

Εγκαταστήστε τη βιβλιοθήκη

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

Προαπαιτούμενα: Python 3.10 ή νεότερη έκδοση.

pip install microsoft-opentelemetry

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

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

Καλέστε use_microsoft_opentelemetry() για να ενεργοποιήσετε την παρατηρησιμότητα.

from microsoft.opentelemetry import use_microsoft_opentelemetry
from microsoft.opentelemetry.a365.hosting.token_cache_helpers import AgenticTokenCache

token_cache = AgenticTokenCache()

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=lambda agent_id, tenant_id: (
        (t := asyncio.run(token_cache.get_observability_token(agent_id, tenant_id)))
        and t.token or None
    ),
)

Για προσαρμοσμένη επίλυση διακριτικών (αντί της προεπιλεγμένης επίλυσης διακριτικών), δείτε Μη αυτόματη επίλυση διακριτικών.

Μπορείτε να προσαρμόσετε τη συμπεριφορά του εξαγωγέα περνώντας προαιρετικά a365_* kwargs στο use_microsoft_opentelemetry().

Παράμετρος Περιγραφή Προεπιλογή
a365_use_s2s_endpoint Όταν True, χρησιμοποιείται η διαδρομή τερματικού σημείου υπηρεσία προς υπηρεσία. False
a365_max_queue_size Μέγιστη χωρητικότητα ουράς για τον επεξεργαστή παρτίδας. 2048
a365_scheduled_delay_ms Καθυστέρηση σε χιλιοστά του δευτερολέπτου μεταξύ των παρτίδων εξαγωγής. 5000
a365_exporter_timeout_ms Χρονικό όριο σε χιλιοστά του δευτερολέπτου για τη λειτουργία εξαγωγής. 30000
a365_max_export_batch_size Μέγιστο μέγεθος παρτίδας για εξαγωγικές εργασίες. 512

Μεταδώστε το πλαίσιο

Για να διατηρήσετε την παρατηρησιμότητα σε κατανεμημένες λειτουργίες του Agent 365, διαδώστε το πλαίσιο. Όταν διαδίδετε το πλαίσιο μέσω των παραγόντων και των υπηρεσιών σας, διασφαλίζετε ότι τα ίχνη, τα αρχεία καταγραφής και οι μετρήσεις συσχετίζονται σωστά σε ολόκληρο τον κύκλο ζωής του αιτήματος. Αυτή η συσχέτιση απαιτείται για μια ολοκληρωμένη και αποτελεσματική εμπειρία παρακολούθησης του Microsoft Agent 365.

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

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

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

from microsoft.opentelemetry.a365.core import BaggageBuilder
from microsoft.opentelemetry.a365.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 σε κάθε χειριστή δραστηριότητας.

Στην Python, καταχωρήστε το ενδιάμεσο λογισμικό αποσκευών μέσω ObservabilityHostingManager.configure() αντί απευθείας στον προσαρμογέα.

from microsoft.opentelemetry.a365.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

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

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

Επικύρωση ροής δεδομένων στο προϊόν

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

Αυτόματη παρακολούθηση

Το Microsoft OpenTelemetry Distro συνδυάζει τυπικές διοχετεύσεις OpenTelemetry με παρακολούθηση που επιμελείται η Microsoft. Το Distro μπορεί να συλλέξει τηλεμετρία εφαρμογών, τηλεμετρία υποδομής και τηλεμετρία παραγόντων ή παραγωγικού AI ανάλογα με τη γλώσσα και τη διαμόρφωση.

Κατηγορία Τι καλύπτει
Διοχετεύσεις σημάτων Ίχνη, μετρήσεις και αρχεία καταγραφής.
Ανίχνευση πόρων Η υπηρεσία, ο κεντρικός υπολογιστής, το cloud και το περιβάλλον χρόνου εκτέλεσης Azure όπου υποστηρίζονται.
Παρακολούθηση υποδομής HTTP, ASP.NET Core, Azure SDK, πελάτες βάσεων δεδομένων και πλαίσια καταγραφής όπου υποστηρίζονται.
Παρακολούθηση παραγωγικού AI OpenAI, Azure OpenAI, Semantic Kernel, LangChain, OpenAI Agents SDK και Agent Framework όπου υποστηρίζονται.
Εμβέλεια μη αυτόματου παράγοντα Όπου υποστηρίζεται η κλήση παράγοντα, η εκτέλεση εργαλείου, η εξαγωγή συμπερασμάτων και η τηλεμετρία εξόδου.
Εξαγωγείς και επεξεργαστές Azure Monitor, Microsoft Agent 365, OTLP, έξοδος στην κονσόλα, επεξεργαστές span, επεξεργαστές καταγραφών και αναγνώστες μετρικών.

Κάλυψη οργάνων

Γλώσσα Παρακολούθηση κοινής εφαρμογής Παρακολούθηση κοινού παράγοντα και παραγωγικού AI
Python Πόροι, επεξεργαστές, αναγνώστες, καταγραφές, μετρήσεις και ίχνη OpenTelemetry. Πεδία Semantic Kernel, OpenAI Agents SDK, Agent Framework, LangChain, Microsoft Agent 365 baggage και Microsoft Agent 365.
Node.js HTTP, Azure SDK, Azure Functions, MongoDB, MySQL, PostgreSQL, Redis, Bunyan και Winston. Πεδία OpenAI Agents SDK, LangChain, Microsoft Agent 365 baggage και Microsoft Agent 365.
.NET ASP.NET Core, HttpClient, SQL Client, Azure SDK, εντοπισμός πόρων, μετρήσεις και αρχεία καταγραφής. Πεδία Kernel, OpenAI και Azure OpenAI, Agent Framework, Microsoft Agent 365 baggage και Microsoft Agent 365.

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

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

Σημαντικό

Τα αυτόματα όργανα συμπληρώνουν μόνο τυπικά χαρακτηριστικά OpenTelemetry. Δεν περιλαμβάνει όλα τα χαρακτηριστικά που απαιτεί το Agent 365. Πρέπει να προσθέσετε χαρακτηριστικά ειδικά για τη Microsoft μέσω BaggageBuilder. Για να δείτε ποια χαρακτηριστικά απαιτούνται, δείτε Αποθήκευση χαρακτηριστικών επαλήθευσης.

Ενσωματωμένες βιβλιοθήκες παρακολούθησης

Η αυτόματη παρακολούθηση παρακολουθεί την τηλεμετρία που παράγεται από υποστηριζόμενα πλαίσια και την προωθεί μέσω της διοχέτευσης OpenTelemetry του Distro. Για σενάρια παράγοντα, ορίστε αποσκευές όπως αναγνωριστικό μισθωτή και αναγνωριστικό παράγοντα πριν το πλαίσιο παρακολούθησης δημιουργήσει span.

Υποδομή Python Node.js .NET
Σημασιολογικός πυρήνας Υποστηρίζεται Δεν υποστηρίζεται Υποστηρίζεται
OpenAI και OpenAI Agents SDK Υποστηρίζεται Υποστηρίζεται Υποστηρίζεται
Agent Framework Υποστηρίζεται Δεν υποστηρίζεται Υποστηρίζεται
LangChain Υποστηρίζεται Υποστηρίζεται Δεν περιλαμβάνεται στη λίστα

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

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "semantic_kernel": {"enabled": True},
    },
)

OpenAI

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "openai_agents": {"enabled": True},
    },
)

Agent Framework

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "agent_framework": {"enabled": True},
    },
)

LangChain

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "langchain": {"enabled": True},
    },
)

Μη αυτόματη παρακολούθηση

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

Εμβέλεια Χρήση για
InvokeAgentScope Η έναρξη και η ολοκλήρωση μιας επίκλησης παράγοντα.
ExecuteToolScope Μια κλήση εργαλείου που έγινε από έναν παράγοντα.
InferenceScope Μια λειτουργία εξαγωγής συμπερασματικής λογικής μοντέλου AI.
OutputScope Έξοδος που πρέπει να καταγραφεί αφού έχει ήδη ολοκληρωθεί το αρχικό πεδίο εφαρμογής.

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

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

from microsoft.opentelemetry.a365.core import (
    AgentDetails,
    Channel,
    InvokeAgentScope,
    InvokeAgentScopeDetails,
    Request,
    ServiceEndpoint,
)

agent_details = AgentDetails(
    agent_id="agent-456",
    agent_name="Email Assistant",
    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",
)

request = Request(
    content="Please help me organize my emails",
    session_id="session-42",
    conversation_id="conv-xyz",
    channel=Channel(name="msteams"),
)

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

with InvokeAgentScope.start(
    request=request,
    scope_details=scope_details,
    agent_details=agent_details,
) as scope:
    scope.record_input_messages(["Please help me organize my emails"])

    # Run the agent invocation.

    invoke_scope.record_output_messages(["I found 15 urgent emails."])

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

from microsoft.opentelemetry.a365.core import (
    ExecuteToolScope,
    ServiceEndpoint,
    ToolCallDetails,
    ToolType,
)

tool_details = ToolCallDetails(
    tool_name="email-search",
    arguments={"query": "from:manager@contoso.com"},
    tool_call_id="tool-call-456",
    description="Search emails by criteria",
    tool_type=ToolType.FUNCTION.value,
    endpoint=ServiceEndpoint(
        hostname="tools.contoso.com",
        port=8080,
        protocol="https",
    ),
)

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

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

from microsoft.opentelemetry.a365.core import (
    InferenceCallDetails,
    InferenceOperationType,
    InferenceScope,
)

inference_details = InferenceCallDetails(
    operationName=InferenceOperationType.CHAT,
    model="gpt-4o-mini",
    providerName="azure-openai",
)

with InferenceScope.start(
    request=request,
    details=inference_details,
    agent_details=agent_details,
) as scope:
    scope.record_input_messages(["Summarize the following emails for me."])
    response = call_llm()
    scope.record_output_messages([response.text])
    scope.record_input_tokens(response.usage.input_tokens)
    scope.record_output_tokens(response.usage.output_tokens)
    scope.record_finish_reasons(["stop"])

Έξοδος

from microsoft.opentelemetry.a365.core import OutputScope, Response, SpanDetails

# Capture this before exiting the originating InvokeAgentScope context.
parent_context = invoke_scope.get_span_context()
response = Response(
    messages=["Here is your organized inbox."],
)

with OutputScope.start(
    request=request,
    response=response,
    agent_details=agent_details,
    user_details=None,
    span_details=SpanDetails(parent_context=parent_context),
) as scope:
    pass

Η τεκμηρίωση του προϊόντος θα πρέπει να καθορίζει τυχόν απαιτήσεις επικύρωσης για το συγκεκριμένο προϊόν για τα εν λόγω πεδία.

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

Η τοπική επικύρωση επιβεβαιώνει ότι η εφαρμογή παράγει τηλεμετρία πριν από την επικύρωση ενός προορισμού για συγκεκριμένο προϊόν. Χρησιμοποιήστε την έξοδο της κονσόλας ή ένα τοπικό τελικό σημείο OTLP για να επαληθεύσετε ότι δημιουργούνται ίχνη, μετρήσεις και αρχεία καταγραφής.

Επικύρωση με τοπικό τελικό σημείο OTLP

Ρυθμίστε το Distro ώστε να αποστέλλει τηλεμετρία σε έναν τοπικό συλλέκτη ή σε άλλο τελικό σημείο που υποστηρίζει OTLP.

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

Επικύρωση με τοπική έξοδο

Χρησιμοποιήστε την τοπική έξοδο όταν θέλετε να επιβεβαιώσετε τη σωστή παρακολούθηση πριν στείλετε δεδομένα τηλεμετρίας σε απομακρυσμένο προορισμό.

export ENABLE_A365_OBSERVABILITY_EXPORTER=false

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "local-validation-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
)

# Run instrumented application code.

Ελέγξτε την τοπική έξοδο για span από αναμενόμενες πηγές, όπως αιτήματα HTTP, κλήσεις OpenAI ή Azure OpenAI, πεδία εκτέλεσης παράγοντα, πεδία εκτέλεσης εργαλείων ή πεδία συμπερασμάτων. Η επικύρωση για συγκεκριμένο προορισμό ανήκει στην τεκμηρίωση του προϊόντος για αυτόν τον προορισμό.

Μη αυτόματη ρύθμιση ελέγχου ταυτότητας

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

Φιλοδώρημα

Εάν αναπτύσσετε παράγοντες με το SDK παραγόντων Microsoft 365, ανατρέξτε στη Ρύθμιση ελέγχου ταυτότητας παρατηρησιμότητας για το Agent SDK για οδηγίες βήμα προς βήμα σχετικά με τη ρύθμιση παραμέτρων της απόκτησης διακριτικών OBO και S2S τόσο για παράγοντες με παραγοντική λειτουργία όσο και για παράγοντες χωρίς παραγοντική λειτουργία.

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

Χρησιμοποιήστε έναν μηχανισμό χειροκίνητης επίλυσης όταν αποκτάτε διακριτικά εκτός της διοχέτευσης του Agent Framework, όταν δημιουργείτε εφαρμογές που δεν βασίζονται στο Agent Framework ή όταν χρησιμοποιείτε έλεγχο ταυτότητα υπηρεσίας προς υπηρεσία (S2S) με ροή διαπιστευτηρίων πελάτη. Οι παράγοντες μπορούν να δημιουργήσουν ένα διακριτικό οι ίδιοι, για παράδειγμα χρησιμοποιώντας τη Βιβλιοθήκη ελέγχου ταυτότητας της Microsoft (MSAL) ή οποιαδήποτε άλλη μέθοδο απόκτησης διακριτικού, αλλά πρέπει να διασφαλίσουν ότι το διακριτικό έχει το σωστό εύρος παρατηρησιμότητας (api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite).

Σημείωμα

Για τον έλεγχο ταυτότητας μεταξύ υπηρεσιών (S2S), πρέπει να χρησιμοποιήσετε αυτήν την προσέγγιση μη αυτόματης επίλυσης διακριτικών. Η παραγοντική cache διακριτικών υποστηρίζει μόνο ροές ελέγχου ταυτότητας εκ μέρους (OBO).

Τα παρακάτω παραδείγματα δείχνουν το μοτίβο διαχειριστή διακριτικών OBO (on-behalf-of) — ο παράγοντας αποκτά ένα διακριτικό χρήστη μέσω του χειριστή ελέγχου ταυτότητας του παράγοντα και το ανταλλάσσει με ένα διακριτικό με εμβέλεια παρατηρησιμότητας. Για παραδείγματα S2S (service-to-service) και μια σύγκριση του ελέγχου ταυτότητας OBO με τον έλεγχο ταυτότητας S2S, δείτε τη Ρύθμιση ελέγχου ταυτότητας παρατηρησιμότητας για το SDK φορέα.

Ο μηχανισμός επίλυσης πρέπει να είναι σύγχρονος. Αποκτήστε το διακριτικό στο πρόγραμμα χειρισμού ασύγχρονης δραστηριότητας (ή μέσω MSAL) και αποθηκεύστε το στη μνήμη cache για τον μηχανισμό επίλυσης.

from microsoft.opentelemetry import use_microsoft_opentelemetry
from microsoft.opentelemetry.a365.runtime import get_observability_authentication_scope

_cached_token: str | None = None

def my_token_resolver(agent_id: str, tenant_id: str) -> str | None:
    return _cached_token

use_microsoft_opentelemetry(enable_a365=True, a365_token_resolver=my_token_resolver)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    global _cached_token
    _cached_token = await AGENT_APP.auth.exchange_token(
        context,
        scopes=get_observability_authentication_scope(),
        auth_handler_id="AGENTIC",
    )

Cache παραγοντικού διακριτικού για εφαρμογές Agent Framework

Για εφαρμογές Agent Framework που χρησιμοποιούν έλεγχο ταυτότητας εκ μέρους (OBO), η διανομή καταχωρεί αυτόματα το IExporterTokenCache<AgenticTokenStruct> μέσω DI όταν δεν ορίζετε προσαρμοσμένο TokenResolver. Ο παράγοντας σας καλεί το RegisterObservability() κατά το χρόνο εκτέλεσης για να παρέχει διαπιστευτήρια, και η cache χειρίζεται την απόκτηση και την ανανέωση διακριτικών.

Σημείωμα

Αυτή η προσέγγιση υποστηρίζει μόνο ροές ελέγχου ταυτότητας εκ μέρους (OBO). Για έλεγχο ταυτότητας από υπηρεσία σε υπηρεσία (S2S), χρησιμοποιήστε τη μη αυτόματη επίλυση διακριτικών.

from microsoft.opentelemetry import use_microsoft_opentelemetry
from microsoft.opentelemetry.a365.hosting.token_cache_helpers import AgenticTokenCache, AgenticTokenStruct
from microsoft.opentelemetry.a365.runtime import get_observability_authentication_scope

token_cache = AgenticTokenCache()

_cached_tokens: dict[tuple[str, str], str | None] = {}

# Keep the sync resolver side-effect free; refresh the cache in the async request handler.
def sync_token_resolver(agent_id: str, tenant_id: str) -> str | None:
    return _cached_tokens.get((agent_id, tenant_id))

use_microsoft_opentelemetry(enable_a365=True, a365_token_resolver=sync_token_resolver)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    agent_id = context.activity.recipient.id
    tenant_id = context.activity.recipient.tenant_id
    token_cache.register_observability(
        agent_id=agent_id,
        tenant_id=tenant_id,
        token_generator=AgenticTokenStruct(
            authorization=AGENT_APP.auth,
            turn_context=context,
        ),
        observability_scopes=get_observability_authentication_scope(),
    )
    _cached_tokens[(agent_id, tenant_id)] = await token_cache.get_observability_token(
        agent_id, tenant_id,
    )

Χαρακτηριστικά επικύρωσης χώρου αποθήκευσης

Για επιτυχή επικύρωση αποθήκευσης, ο παράγοντας σας πρέπει να εφαρμόσει InvokeAgentScope, InferenceScope και ExecuteToolScope. Κάθε πεδίο αντιστοιχεί σε μια λειτουργία span στο κανονικό σχήμα:

SDK πεδίου Λειτουργία span Καθολικός κωδικός αναφοράς
InvokeAgentScope invoke_agent IA
ExecuteToolScope execute_tool ET
InferenceScope chat CH
OutputScope output_messages OM

Για τις πλήρεις λίστες απαιτούμενων και προαιρετικών χαρακτηριστικών ανά πεδίο — συμπεριλαμβανομένης της σημασιολογίας κάθε χαρακτηριστικού, οδηγίες επιλογής τιμών και πληροφορίες για το ποια χαρακτηριστικά μπορούν να αναζητηθούν μέσω του προηγμένου εντοπισμού του Microsoft Defender — δείτε Αναφορά χαρακτηριστικών παρατηρησιμότητας Agent 365. Η στήλη Εφαρμογή σε δείχνει σε ποιο πεδίο ανήκει κάθε χαρακτηριστικό, ενώ η στήλη Απαιτείται ξεχωρίζει τα υποχρεωτικά (M) από τα προαιρετικά (O) χαρακτηριστικά.

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

Μετά την ενσωμάτωση της παρατηρησιμότητας, βεβαιωθείτε ότι καταγράφεται η τηλεμετρία:

  1. Μετάβαση στο https://admin.cloud.microsoft/#/agents/all.
  2. Επιλέξτε τον παράγοντα σας και, στη συνέχεια, επιλέξτε Δραστηριότητα.
  3. Ελέγξτε ότι εμφανίζονται οι συνεδρίες και οι κλήσεις των εργαλείων.

Δείγματα εφαρμογών και προηγμένες ρυθμίσεις παραμέτρων

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

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

Αυτή η ενότητα περιγράφει συνηθισμένα προβλήματα κατά την εφαρμογή και χρήση του Microsoft OpenTelemetry Distro με το Agent 365.

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

Φιλοδώρημα

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

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

Συμπτώματα:

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

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

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

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

  • Επαληθεύστε ότι η εξαγωγή Agent 365 είναι ενεργοποιημένη

    Πρέπει να ενεργοποιήσετε ρητά τον εξαγωγέα Agent 365. Όταν δεν το ορίσετε, η διανομή μπορεί να καταφύγει σε έναν εξαγωγέα κονσόλας ή να μην εξάγει τίποτα. Ενεργοποιήστε το στον κώδικα:

    from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_enable_observability_exporter=True,
    a365_token_resolver=my_token_resolver,
)

    Η ρυθμίστε τη μεταβλητή περιβάλλοντος:

    export ENABLE_A365_OBSERVABILITY_EXPORTER=true

    Σημείωμα

    Το ENABLE_A365_OBSERVABILITY_EXPORTER είναι μια δευτερεύουσα εναλλαγή που τίθεται σε ισχύ μόνο όταν enable_a365=True έχει οριστεί στον κώδικα. Μπορείτε επίσης να το ελέγξετε μέσω του a365_enable_observability_exporter kwarg.

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

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

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

    Προσθέστε έναν εξαγωγέα κονσόλας για να επαληθεύσετε ότι η τηλεμετρία δημιουργείται πριν φτάσει στο τελικό σημείο του Agent 365:

    use_microsoft_opentelemetry(enable_a365=True, enable_console=True)

  • Εναλλαγή λεπτομερούς σύνδεσης

    import logging

logging.basicConfig(level=logging.DEBUG)

  • Ελέγξτε τα αρχεία καταγραφής για σφάλματα εξαγωγής

    Χρησιμοποιήστε την az webapp log tail εντολή για να αναζητήσετε στα αρχεία καταγραφής σφάλματα που σχετίζονται με την παρατηρησιμότητα:

    az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"

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

Συμπτώματα: Το σύστημα απορρίπτει σιωπηλά spans και δεν τα εξάγει ποτέ. Ορισμένες πλατφόρμες καταγράφουν έναν αριθμό παραλειφθέντων spans ή ένα μήνυμα όπως το No spans with tenant/agent identity found. Άλλοι τα απορρίπτουν χωρίς καταγραφή.

Επίλυση:

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

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

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

Επίλυση:

  • Απαιτείται πρόγραμμα επίλυσης διακριτικών. Εάν λείπει, ο εξαγωγέας εμφανίζει σφάλμα κατά την εκκίνηση. Βεβαιωθείτε ότι παρέχεται ένα πρόγραμμα επίλυσης διακριτικών και επιστρέφει ένα έγκυρο διακριτικό φορέα.
  • Βεβαιωθείτε ότι έχουν μεταβιβαστεί ο σωστός κωδικός μισθωτή και ο σωστός κωδικός παράγοντα στο BaggageBuilder, καθώς αυτές οι τιμές προωθούνται στον μηχανισμό επίλυσης διακριτικού.
  • Για παράγοντες που φιλοξενούνται στο Azure, βεβαιωθείτε ότι η διαχειριζόμενη ταυτότητα διαθέτει την απαιτούμενη άδεια API για το πεδίο παρατηρησιμότητας.
  • Για εφαρμογές .NET που χρησιμοποιούν το πακέτο φιλοξενίας Agent Framework, η ανταλλαγή διακριτικών γίνεται αυτόματα μέσω DI. Εάν λείπουν τα διακριτικά, επιβεβαιώστε ότι το Microsoft.Agents.A365.Observability.Hosting έχει εγκατασταθεί και καταχωρηθεί.

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 δικαίωμα — Εκχωρήστε το δικαίωμα στην ταυτότητά σας (Διαχειριζόμενη ταυτότητα ή εγγραφή εφαρμογής). Χωρίς αυτό, η εξαγωγή τηλεμετρίας επιστρέφει HTTP 403.

Χορηγήστε την άδεια

Χρησιμοποιήστε μία από αυτές τις επιλογές:

  • Agent 365 CLI

    Απαιτείται λογαριασμός καθολικού διαχειριστή· εκτελέστε από τον κατάλογο έργου του παράγοντα που περιέχει a365.config.json, ή χρησιμοποιήστε --agent-name.

    a365 setup permissions bot

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

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

  • Πύλη Entra

    Δεν απαιτούνται αρχεία ρυθμίσεων· απαιτείται πρόσβαση καθολικού διαχειριστή στην εγγραφή εφαρμογής 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.

Επίλυση:

  • Αυτά τα σφάλματα είναι συνήθως παροδικά και επιλύονται από μόνα τους. Οι διανομές Python και JavaScript εκτελούν αυτόματα επαναλήψεις σε κωδικούς κατάστασης HTTP 408, 429 και 5xx. Η διανομή .NET δεν επαναπροσπαθεί αυτόματα.
  • Εάν τα σφάλματα επιμείνουν, ελέγξτε τον πίνακα υγείας της υπηρεσίας.
  • Εξετάστε το ενδεχόμενο να μειώσετε τη συχνότητα εξαγωγής αυξάνοντας το προγραμματισμένο διάστημα καθυστέρησης μεταξύ των παρτίδων ή το μέγιστο μέγεθος παρτίδας εξαγωγής. Για Python και JavaScript, χρησιμοποιήστε τις αντίστοιχες παραμέτρους exporterOptions ή a365_* όπως τεκμηριώνονται στα αποθετήρια GitHub. Για .NET, χρησιμοποιήστε o.Agent365.Exporter.ScheduledDelayMilliseconds και o.Agent365.Exporter.MaxExportBatchSize.

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

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

Επίλυση:

  • Ελέγξτε τη συνδεσιμότητα δικτύου με το τελικό σημείο παρατηρησιμότητας.

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

    use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=my_token_resolver,
    # No direct timeout kwarg — set via environment variable or exporterOptions if supported
)

    Δείτε το αποθετήριο Python για την πλήρη λίστα επιλογών a365_*.

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

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

Επίλυση:

  • Βεβαιωθείτε ότι πληροίτε τις προϋποθέσεις για την προβολή των εξαγόμενων αρχείων καταγραφής:
  • Η τηλεμετρία μπορεί να χρειαστεί αρκετά λεπτά για να εμφανιστεί μετά από μια επιτυχημένη εξαγωγή. Περιμένετε πριν ερευνήσετε περαιτέρω.
  • Βεβαιωθείτε ότι τα spans περιέχουν έγκυρα χαρακτηριστικά microsoft.tenant.id και gen_ai.agent.id. Η απουσία χαρακτηριστικών ταυτότητας προκαλεί την απόρριψη των spans στον διακομιστή, ακόμη και αν η εξαγωγή HTTP επιστρέφει κωδικό 200.

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

  • Last updated on