Microsoft OpenTelemetry Distro

Microsoft OpenTelemetry Distro एक एकीकृत अवलोकन वितरण है जो एजेंटिक और गैर-एजेंटिक अनुप्रयोगों से ट्रेस, मेट्रिक्स और लॉग एकत्र करने के लिए एक एकल ऑनबोर्डिंग अनुभव प्रदान करता है। यह Microsoft Agent 365, Microsoft Foundry, Azure Monitor, और किसी भी OpenTelemetry Protocol (OTLP)-संगत बैकएंड के लिए अवलोकन क्षमता का समर्थन करता है। डिस्ट्रो .NET, Node.js और Python का समर्थन करता है, और एक आयात और एक कॉन्फ़िगरेशन कॉल के साथ कई अवलोकन स्टैक में खंडित सेटअप को बदल देता है।

मुख्य लाभ

Microsoft OpenTelemetry डिस्ट्रो निम्नलिखित लाभ प्रदान करता है:

  • एक पैकेज, एक एपीआई: एक ही निर्भरता के साथ कई निर्यातक और इंस्ट्रूमेंटेशन पैकेजों को बदलें।
  • मल्टी-बैकएंड समर्थन: टेलीमेट्री को Azure मॉनिटर, किसी भी OpenTelemetry प्रोटोकॉल (OTLP)-संगत समापन बिंदु जैसे Datadog, Grafana, या New Relic, और Microsoft Agent 365 को एक ही समय में भेजें।
  • अंतर्निहित इंस्ट्रूमेंटेशन: बिना किसी अतिरिक्त कॉन्फ़िगरेशन के HTTP, डेटाबेस, Azure SDK, Azure फ़ंक्शंस और बहुत कुछ के लिए स्वचालित इंस्ट्रूमेंटेशन का उपयोग करें।
  • मानक-आधारित: 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 पर एक्सपोर्ट सक्षम करने के लिए, एक्सपोर्टर टार्गेट सेट करें और एक टोकन रिज़ॉल्वर प्रदान करें जो दिए गए एजेंट ID और टेनेंट ID के लिए एक्सेस टोकन लौटाए।

अवलोकन को सक्षम करने के लिए 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 का उपयोग करें, जो एक अनुरोध के सभी स्पैन में प्रवाहित होती है। SDK एक ऐसा SpanProcessor लागू करता है जो सभी गैर-खाली बैगेज प्रविष्टियों को नए प्रारंभ किए गए स्पैन में कॉपी करता है, मौजूदा विशेषताओं को अधिलेखित किए बिना।

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

TurnContext से BaggageBuilderको ऑटो-पॉप्युलेट करने के लिए, microsoft-opentelemetry पैकेज में populate हेल्पर का उपयोग करें। यह सहायक activity से caller, agent, tenant, channel और conversation के विवरण स्वतः प्राप्त करता है।

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

बैगेज middleware

यदि आपका एजेंट होस्टिंग इंटीग्रेशन पैकेज का उपयोग करता है, तो हर आने वाली रिक्वेस्ट के लिए बैगेज को स्वचालित रूप से भरने हेतु बैगेज मिडलवेयर पंजीकृत करें। इस चरण के बाद प्रत्येक गतिविधि हैंडलर में BaggageBuilder को मैन्युअल रूप से कॉल करने की आवश्यकता नहीं रहती है।

Python में, बैगेज मिडलवेयर को सीधे एडॉप्टर पर रजिस्टर करने के बजाय ObservabilityHostingManager.configure() के माध्यम से रजिस्टर करें।

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

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

मिडलवेयर async रिप्लाई (ContinueConversationइवेंट) के लिए बैगेज सेटअप को छोड़ देता है ताकि मूल अनुरोध द्वारा पहले से सेट किए गए बैगेज को ओवरराइट करने से बचा जा सके।

सत्यापित करें कि उत्पाद में डेटा प्रवाहित हो रहा है

Microsoft Purview या Microsoft Defender में एजेंट टेलीमेट्री देखने के लिए, सुनिश्चित करें कि निम्न आवश्यकताएँ पूरी की गई हैं:

स्वचालित इंस्ट्रूमेंटेशन

Microsoft OpenTelemetry Distro मानक OpenTelemetry पाइपलाइनों को Microsoft द्वारा तैयार इंस्ट्रूमेंटेशन के साथ संयोजित करता है। डिस्ट्रो एप्लिकेशन टेलीमेट्री, इंफ्रास्ट्रक्चर टेलीमेट्री, तथा एजेंट या जनरेटिव AI टेलीमेट्री भाषा और कॉन्फ़िगरेशन के आधार पर संग्रह कर सकता है।

श्रेणी इसमें क्या शामिल है
सिग्नल पाइपलाइन ट्रेस, मेट्रिक्स और लॉग।
संसाधन जाँच सेवा, होस्ट, क्लाउड और Azure रनटाइम संदर्भ जहां समर्थित है।
मूलभूत संरचना इंस्ट्रूमेंटेशन HTTP, ASP.NET Core, Azure SDK, डेटाबेस क्लाइंट्स और लॉगिंग फ्रेमवर्क्स (जहां समर्थित हैं)।
जनरेटिव AI इंस्ट्रूमेंटेशन OpenAI, Azure OpenAI, सिमेंटिक कर्नेल, LangChain, OpenAI एजेंट SDK और Agent Framework जहां समर्थित हैं।
मैनुअल एजेंट स्कोप एजेंट आह्वान, टूल निष्पादन, अनुमान, और आउटपुट टेलीमेट्री (जहां समर्थित है)।
निर्यातक और प्रोसेसर Azure मॉनिटर, Microsoft Agent 365, OTLP, कंसोल आउटपुट, स्पैन प्रोसेसर, लॉग प्रोसेसर और मीट्रिक रीडर।

इंस्ट्रूमेंटेशन की व्यापकता

भाषा सामान्य अनुप्रयोग इंस्ट्रूमेंटेशन सामान्य एजेंट और जनरेटिव AI इंस्ट्रूमेंटेशन
Python OpenTelemetry संसाधन, प्रोसेसर, पाठक, लॉगिंग, मेट्रिक्स और निशान। सिमेंटिक कर्नेल, OpenAI एजेंट SDK, Agent Framework, LangChain, Microsoft Agent 365 बैगेज और Microsoft Agent 365 स्कोप।
Node.js HTTP, Azure SDK, Azure Functions, MongoDB, MySQL, PostgreSQL, Redis, Bunyan, और विंस्टन। OpenAI एजेंट SDK, LangChain, Microsoft Agent 365 बैगेज और Microsoft Agent 365 स्कोप।
.NET ASP.NET Core, HttpClient, SQL क्लाइंट, Azure SDK, रिसोर्स डिटेक्शन, मेट्रिक्स और लॉग्स। सिमेंटिक कर्नेल, OpenAI और Azure OpenAI, Agent Framework, Microsoft Agent 365 बैगेज और Microsoft Agent 365 स्कोप।

स्वचालित इंस्ट्रूमेंटेशन समर्थित लाइब्रेरी और फ्रेमवर्क्स द्वारा उत्सर्जित टेलीमेट्री सिग्नल्स को सुनता है। मैनुअल इंस्ट्रूमेंटेशन का उपयोग तब किया जाता है जब किसी एप्लिकेशन को एजेंट-विशिष्ट संचालन का वर्णन करने की आवश्यकता होती है, जैसे कि आह्वान, उपकरण निष्पादन, अनुमान, या अतुल्यकालिक आउटपुट।

जब आपका अनुप्रयोग ऐसी टेलीमेट्री उत्पन्न करता है जो अंतर्निहित इंस्ट्रूमेंटेशन द्वारा कवर नहीं होती है, तब कस्टम OpenTelemetry स्रोत, मीटर, प्रोसेसर या रीडर जोड़ें।

महत्त्वपूर्ण

स्वचालित इंस्ट्रूमेंटेशन केवल मानक OpenTelemetry विशेषताओं को सेट करता है। इसमें वे सभी विशेषताएँ शामिल नहीं हैं जो Agent 365 के लिए आवश्यक हैं। आपको Microsoft-विशिष्ट विशेषताएँ BaggageBuilder के माध्यम से जोड़नी होंगी। कौन सी विशेषताओं की आवश्यकता है, यह देखने के लिए स्टोर सत्यापन विशेषताएँ देखें।

अंतर्निहित इंस्ट्रूमेंटेशन लाइब्रेरी

ऑटो-इंस्ट्रूमेंटेशन समर्थित फ्रेमवर्क द्वारा उत्सर्जित टेलीमेट्री को सुनता है और उसे डिस्ट्रो की OpenTelemetry पाइपलाइन के माध्यम से अग्रेषित करता है। एजेंट परिदृश्य में, स्पैन बनाने से पहले उपकरणित फ्रेमवर्क द्वारा टैनेंट आईडी और एजेंट आईडी जैसे बैगेज सेट करें।

रूपरेखा Python Node.js .NET
सिमेंटिक कर्नेल समर्थित समर्थित नहीं समर्थित
OpenAI और OpenAI एजेंट 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

नोट

LangChain फ़्रेमवर्क के लिए ऑटो-इंस्ट्रूमेंटेशन भी LangGraph और डीप एजेंट्स का समर्थन करता है. एक ही इंस्ट्रुमेंटेशन स्वचालित रूप से इनमें से किसी भी फ़्रेमवर्क के साथ बनाए गए एजेंट्स के लिए टैलीमेट्री को कैप्चर करता है.

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

मैनुअल इंस्ट्रूमेंटेशन

जब automatic instrumentation एजेंट ऑपरेशन का पर्याप्त विवरण नहीं देती है, तब manual instrumentation का उपयोग करें। मैन्युअल स्कोप्स किसी एप्लिकेशन को विभिन्न भाषाओं में सामान्य एजेंट गतिविधियों को एक समान तरीके से वर्णित करने की सुविधा देते हैं।

कार्यक्षेत्र उपयोग के लिए
InvokeAgentScope एजेंट आमंत्रण की शुरुआत और समापन।
ExecuteToolScope किसी एजेंट द्वारा किया गया टूल कॉल।
InferenceScope एक एआई मॉडल इनफेरेंस ऑपरेशन।
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.

आपको HTTP अनुरोधों, OpenAI या Azure OpenAI कॉल, एजेंट इनवोकेशन स्कोप, टूल निष्पादन स्कोप, या इंफरेंस स्कोप जैसे अपेक्षित स्रोतों से स्पैन के स्थानीय आउटपुट की समीक्षा करनी चाहिए। गंतव्य-विशिष्ट सत्यापन उस गंतव्य के लिए उत्पाद दस्तावेज़ीकरण में आता है।

प्रमाणीकरण म्यानुअल रूप से सेट अप करें

जब आप Agent 365 एक्सपोर्टर का उपयोग करते हैं, तो आपको प्रमाणीकरण टोकन प्रदान करने के लिए एक तंत्र उपलब्ध कराना होगा। टोकन रिज़ॉल्वर प्रत्येक निर्यात बैच में सक्रिय बैगेज संदर्भ से एजेंट ID और टैनेंट ID का उपयोग करके काम करता है। डिस्ट्रो दो दृष्टिकोणों का समर्थन करता है।

टिप

यदि आप Microsoft 365 एजेंट SDK के साथ एजेंट बना रहे हैं, तो Observability Authentication Setup for Agent SDK देखें, जिसमें agentic और non-agentic एजेंटों के लिए OBO और S2S टोकन अधिग्रहण को कॉन्फ़िगर करने के चरण-दर-चरण निर्देश दिए गए हैं।

मैन्युअल टोकन रिज़ॉल्वर

मैन्युअल रिज़ॉल्वर का उपयोग तब करें जब आप टोकन Agent Framework पाइपलाइन के बाहर प्राप्त करते हैं, जब आप गैर-Agent Framework ऐप्स बना रहे हैं, या जब आप सेवा-से-सेवा (S2S) प्रमाणीकरण (क्लाइंट क्रेडेंशियल्स फ्लो) का उपयोग करते हैं। एजेंट स्वयं टोकन जनरेट कर सकते हैं, उदाहरण के लिए Microsoft Authentication Library (MSAL) या किसी अन्य टोकन अधिग्रहण विधि का उपयोग करके, लेकिन उन्हें यह सुनिश्चित करना होगा कि टोकन में सही observability स्कोप (api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite) हो।

नोट

सर्विस-टू-सर्विस (S2S) ऑथेंटिकेशन के लिए, आपको इस मैन्युअल टोकन रिज़ॉल्वर का उपयोग करना अनिवार्य है। एजेंटिक टोकन कैश केवल की ओर से (OBO) ऑथ फ्लो का समर्थन करता है।

निम्नलिखित उदाहरण OBO (की ओर से) टोकन रिज़ॉल्वर पैटर्न दिखाते हैं — एजेंट agentic प्रमाणीकरण हैंडलर के माध्यम से एक उपयोगकर्ता टोकन प्राप्त करता है और उसे ऑब्जर्वेबिलिटी स्कोप वाले टोकन में बदलता है। S2S (सेवा-से-सेवा) उदाहरण और OBO बनाम S2S प्रमाणीकरण की तुलना के लिए, एजेंट SDK के लिए ऑब्जर्वेबिलिटी प्रमाणीकरण सेटअप देखें।

रिज़ॉल्वर को सिंक्रॉनस होना चाहिए। अपने असिंक्रोनस गतिविधि हैंडलर (या MSAL के माध्यम से) में टोकन प्राप्त करें और उसे रिज़ॉल्वर के लिए कैश करें।

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

Agent Framework ऐप्स के लिए Agentic token cache

Agent Framework ऐप्स के लिए जो ऑन-बिहाफ-ऑफ (OBO) ऑथेंटिकेशन का उपयोग करते हैं, यदि आप कोई कस्टम TokenResolver सेट नहीं करते हैं, तो डिस्ट्रो IExporterTokenCache<AgenticTokenStruct> को DI के माध्यम से स्वचालित रूप से पंजीकृत करता है। आपका एजेंट क्रेडेंशियल्स की आपूर्ति करने के लिए रनटाइम पर कॉल करता RegisterObservability() है, और कैश टोकन अधिग्रहण और ताज़ा करने का काम संभालता है।

नोट

यह तरीका केवल ऑन-बिहाफ-ऑफ (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 लागू करना होगा। प्रत्येक दायरा विहित स्कीमा में एक स्पैन ऑपरेशन से मेल खाता है:

SDK कार्यक्षेत्र स्पैन ऑपरेशन यूनिवर्सल संदर्भ कोड
InvokeAgentScope invoke_agent IA
ExecuteToolScope execute_tool ET
InferenceScope chat CH
OutputScope output_messages OM

पूर्ण प्रति-स्कोप आवश्यक और वैकल्पिक विशेषता सूचियों के लिए—जिसमें प्रति-विशेषता शब्दार्थ, मान चुनने का मार्गदर्शन, और कौन सी विशेषताएँ Microsoft Defender उन्नत शिकार के माध्यम से क्वेरी की जा सकती हैं शामिल हैं—Agent 365 observability attribute reference देखें। Applies to कॉलम यह पहचानता है कि प्रत्येक गुण किस स्कोप से संबंधित है, और Required कॉलम अनिवार्य (M) और वैकल्पिक (O) गुणों के बीच अंतर करता है।

अवलोकन क्षमता के साथ अपने एजेंट का परीक्षण करें

अवलोकन को लागू करने के बाद, सत्यापित करें कि टेलीमेट्री कैप्चर की जा रही है:

  1. https://admin.cloud.microsoft/#/agents/all पर जाएँ.
  2. अपने एजेंट का चयन करें, और फिर Activity का चयन करें।
  3. सत्यापित करें कि सत्र और टूल कॉल दिखाई देते हैं।

नमूना अनुप्रयोग और उन्नत कॉन्फ़िगरेशन

कार्यशील नमूने और उन्नत कॉन्फ़िगरेशन विकल्पों के लिए, प्रत्येक भाषा के लिए GitHub रिपॉजिटरी देखें:

प्रोग्रामिंग संदर्भ

निम्न प्रोग्रामिंग संदर्भ का उपयोग करते हुए Microsoft OpenTelemetry डिस्ट्रो टाइप की समीक्षा करें:

समस्‍या निवारण

इस अनुभाग में Agent 365 के साथ Microsoft OpenTelemetry Distro को लागू करने और उपयोग करने में आने वाली सामान्य समस्याओं का वर्णन किया गया है।

समस्या विवरण
अवलोकन क्षमता डेटा दिखाई नहीं देता है कोई टेलीमेट्री दिखाई नहीं देती क्योंकि Agent 365 निर्यात सक्षम नहीं है, सेटअप अपूर्ण है, या टोकन समाधान विफल हो जाता है।
लापता टैनेंट ID या एजेंट ID - स्पैन छोड़ दिए गए आवश्यक टैनेंट या एजेंट पहचान ऐट्रिब्यूट्स अनुपस्थित होने पर स्पैन निर्यात से पहले फ़िल्टर किए जाते हैं।
टोकन रिज़ॉल्यूशन विफलता - निर्यात नहीं किया गया या अनधिकृत निर्यात को छोड़ दिया जाता है या अस्वीकार कर दिया जाता है जब टोकन रेज़ॉल्वर टोकन नहीं देता या टोकन प्राप्त करते समय त्रुटि लौटाता है।
HTTP 401 अनधिकृत अनुरोध सेवा तक पहुंचते हैं लेकिन प्रमाणीकरण विफल हो जाता है क्योंकि टोकन अमान्य है, समाप्त हो चुका है, या गलत ऑडियंस के लिए है।
HTTP 403 निषिद्ध टेनेंट लाइसेंसिंग या ऑब्ज़र्वेबिलिटी लिखने की अनुमति के अभाव में अधिकार प्रदान विफल हो जाता है।
HTTP 403 निषिद्ध - एजेंट ID बेमेल सेवा उस समय निर्यात को अस्वीकार कर देती है जब अनुरोध में एजेंट आईडी टोकन-अधिकृत एजेंट पहचान से मेल नहीं खाती है।
HTTP 429 या 5xx त्रुटियाँ - अस्थायी त्रुटियाँ अस्थायी थ्रॉटलिंग या बैकएंड अस्थिरता निर्यात को बाधित करती है और पुनः प्रयास या बैच ट्यूनिंग की आवश्यकता हो सकती है।
निर्यात टाइमआउट नेटवर्क विलंब या समापन बिंदु की प्रतिक्रिया में विलंबता के कारण निर्यात ऑपरेशन टाइमआउट सीमा पार कर जाता है।
निर्यात सफल होता है, लेकिन टेलीमेट्री डिफेंडर या पर्व्यू में दिखाई नहीं देती है डेटा अंतर्ग्रहण सफल होता है, लेकिन दृश्यता में देरी होती है या डाउनस्ट्रीम पूर्वापेक्षाओं और स्कीमा आवश्यकताओं द्वारा अवरुद्ध किया जाता है।

टिप

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 कीवर्ड आर्ग्युमेंट के माध्यम से भी नियंत्रित कर सकते हैं.

  • टोकन रिज़ॉल्वर कॉन्फ़िगरेशन की जाँच करें

    निर्यातक को प्रत्येक निर्यात अनुरोध के लिए धारक टोकन लौटाने वाले एक मान्य टोकन समाधानकर्ता की ज़रूरत होती है. यदि टोकन समाधानकर्ता उपलब्ध नहीं है या 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"

अनुपलब्ध टैनेंट आईडी या एजेंट आईडी — स्पैन छोड़ दिए गए

लक्षण: सिस्टम चुपचाप स्पैन छोड़ देता है और उन्हें कभी निर्यात नहीं करता है। कुछ प्लेटफ़ॉर्म छोड़े गए स्पैन की संख्या या No spans with tenant/agent identity found जैसा कोई संदेश लॉग करते हैं। अन्य लोग उन्हें बिना लॉग किए छोड़ देते हैं।

समाधान:

  • निर्यात से पहले, distro स्पैन को टैनेंट और एजेंट पहचान के अनुसार विभाजित करता है। जिन स्पैन में टैनेंट ID या एजेंट ID में से कोई भी एक नहीं होता, उन्हें हटा दिया जाता है और वे कभी भी सेवा में नहीं भेजे जाते हैं.
  • स्पैन बनाने से पहले BaggageBuilder को टैनेंट ID और एजेंट ID के साथ कॉन्फ़िगर करें. ये मान OpenTelemetry संदर्भ के माध्यम से प्रसारित होते हैं और बैगेज स्कोप के भीतर बनाए गए सभी स्पैन से जुड़ते हैं। प्लैटफ़ॉर्म-विशिष्ट API के लिए, बैगेज विशेषताएँ देखें।
  • यदि आप होस्टिंग इंटीग्रेशन पैकेज से बैगेज मिडलवेयर या टर्न कॉन्टेक्स्ट हेल्पर का उपयोग कर रहे हैं, तो यह सुनिश्चित करें कि TurnContextगतिविधि के पास एजेंट पहचान वाला वैध प्राप्तकर्ता है।

टोकन रिज़ॉल्यूशन विफलता — निर्यात छोड़ दिया गया या अनधिकृत

लक्षण: टोकन रिज़ॉल्वर एक त्रुटि लौटाता null है या फेंकता है। प्लेटफ़ॉर्म के आधार पर, निर्यात या तो पूरी तरह से छोड़ दिया जाता है या HTTP 401 के साथ विफल हो जाता है।

समाधान:

  • टोकन रिज़ॉल्वर की आवश्यकता है। यदि यह अनुपलब्ध है, तो निर्यातक स्टार्टअप के समय त्रुटि उत्पन्न करता है। सत्यापित करें कि टोकन रिज़ॉल्वर उपलब्ध है और एक वैध बियरर टोकन लौटाता है।
  • सुनिश्चित करें कि सही टेनेंट ID और एजेंट ID BaggageBuilder को पास किए गए हैं, क्योंकि ये मान टोकन रिज़ॉल्वर को अग्रेषित किए जाते हैं।
  • Azure-होस्ट किए गए एजेंटों के लिए, सत्यापित करें कि प्रबंधित पहचान के पास ऑब्ज़रवेबिलिटी स्कोप के लिए आवश्यक API अनुमति है।
  • Agent Framework होस्टिंग पैकेज का उपयोग करने वाले .NET ऐप्स के लिए, टोकन एक्सचेंज DI के माध्यम से स्वचालित रूप से प्रबंधित किया जाता है। यदि टोकन अनुपलब्ध हैं, तो पुष्टि करें कि Microsoft.Agents.A365.Observability.Hosting स्थापित और पंजीकृत है।

HTTP 401 अनधिकृत

लक्षण: HTTP 401 के साथ निर्यात विफल रहता है। एक्सपोर्टर इस त्रुटि का पुनः प्रयास नहीं करता है।

समाधान:

  • सत्यापित करें कि टोकन ऑडियंस ऑब्ज़र्वेबिलिटी एंडपॉइंट स्कोप के अनुरूप है।
  • जांचें कि टोकन रिज़ॉल्वर प्रतिनिधि उपयोगकर्ता टोकन, गलत ऑडियंस के लिए टोकन या समाप्त हो चुके टोकन नहीं दे रहा है।

HTTP 403 निषिद्ध

लक्षण: HTTP 403 के साथ निर्यात विफल रहता है। एक्सपोर्टर इस त्रुटि का पुनः प्रयास नहीं करता है।

मूल कारण: HTTP 403 त्रुटि के विभिन्न कारण हो सकते हैं। क्रम में निम्नलिखित समाधानों की जाँच करें।

समाधान:

अनुमति दें

इनमें से किसी भी विकल्प का उपयोग करें:

  • Agent 365 CLI

    ग्लोबल एडमिनिस्ट्रेटर खाते की आवश्यकता है; उस एजेंट प्रोजेक्ट निर्देशिका से चलाएं जिसमें a365.config.json मौजूद है, या --agent-name का प्रयोग करें।

    a365 setup permissions bot

    या, कॉन्फ़िगरेशन फ़ाइल के बिना:

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

  • एंट्रा पोर्टल

    किसी कॉन्फ़िगरेशन फ़ाइल की आवश्यकता नहीं है; ब्लूप्रिंट ऐप पंजीकरण के लिए वैश्विक व्यवस्थापक पहुंच आवश्यक है।

    1. एंट्रा पोर्टल>ऐप पंजीकरण> पर जाएं, अपना ब्लूप्रिंट ऐप चुनें।
    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 365 traces एंडपॉइंट्स को कॉल करने में agent-ID-mismatch विफलताएँ होती हैं।

Root cause: यह त्रुटि तब होती है जब एजेंट विवरण सेट करते समय ब्लूप्रिंट क्लाइंट ID का उपयोग किया जाता है, जबकि एजेंट इंस्टेंस ClientId का उपयोग किया जाना चाहिए। निर्यात URL में एजेंट आईडी टोकन द्वारा अधिकृत पहचान से मेल नहीं खाती है, इसलिए ट्रेस एंडपॉइंट अनुरोध को अस्वीकार कर देता है।

समाधान:

  • सत्यापित करें कि टेनेंट ID Agent 365 अनुमत टेनेंट सूची में जोड़ा गया है।
  • एजेंट इंस्टेंस ClientId (ब्लूप्रिंट क्लाइंट ID नहीं) के साथ एजेंट विवरण सेट करें।
  • जनरेट किए गए निर्यात URL को सत्यापित करें - यदि आप अपने लॉगर को सक्षम करते हैं तो यह लॉग होता है। पुष्टि करें कि URL में एजेंट ID एजेंट इंस्टेंस क्लाइंट आईडी से मेल खाता है।
  • प्रत्येक 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_*विकल्पों की पूरी सूची के लिए।

निर्यात सफल होता है, लेकिन टेलीमेट्री डिफेंडर या पर्व्यू में दिखाई नहीं देती है

लक्षण: लॉग दिखाते हैं कि एक्सपोर्ट सफल रहा (HTTP 200), लेकिन टेलीमेट्री Microsoft Defender या Microsoft Purview में दिखाई नहीं देती है।

समाधान:

  • सत्यापित करें कि आपने निर्यातित लॉग देखने के लिए आवश्यक पूर्वापेक्षाएँ पूरी की हैं:
  • सफल निर्यात के बाद टेलीमेट्री को आबाद होने में कई मिनट लग सकते हैं। जांच जारी रखने से पहले प्रतीक्षा करें।
  • सुनिश्चित करें कि स्पैन में वैध microsoft.tenant.id और gen_ai.agent.id विशेषताएँ हैं। पहचान विशेषताओं के अभाव में स्पैन सर्वर-साइड अस्वीकृत कर दिए जाते हैं, भले ही HTTP निर्यात 200 लौटाए।

संबंधित सामग्री

  • पिछली बार को अपडेट किया गया