הפצת OpenTelemetry של Microsoft

הפצת OpenTelemetry של Microsoft היא הפצת תצפיות מאוחדת המספקת חוויית הטמעה יחידה לאיסוף עקבות, מדדים ויומני רישום מיישומים סוכניים ולא סוכניים. הוא תומך בתצפיות עבור Microsoft Agent 365, Microsoft Foundry, Azure Monitor וכל שרת אחורי תואם לפרוטוקול OpenTelemetry (OTLP). ההפצה תומכת ב-.NET, Node.js ו-Python, ומחליפה הגדרה מקוטעת על פני מספר ערימות תצפית עם ייבוא ​​אחד וקריאה אחת לקונפיגורציה.

היתרונות העיקריים

הפצת OpenTelemetry של Microsoft מספקת את היתרונות הבאים:

  • חבילה אחת, 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 (OTLP) או ל-Microsoft Agent 365.

התקנת הספרייה

כדי להתחיל עם הפצת OpenTelemetry של Microsoft, התקן את הספרייה המתאימה לפלטפורמת הפיתוח שלך באמצעות מנהל החבילות של השפה שלך.

דרישות קדם: 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_* קווארגס ל use_microsoft_opentelemetry().

פרמטר Description ברירת מחדל
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

כדי לאכלס אוטומטית את 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, רשום את ה-Baggage Middleware דרך 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, ודא שהדרישות הבאות מתקיימות:

מכשור אוטומטי

הפצת OpenTelemetry של Microsoft משלבת צינורות OpenTelemetry סטנדרטיים עם מכשור שנבחר על ידי Microsoft. ההפצה יכולה לאסוף טלמטריה של יישומים, טלמטריה של תשתית וטלמטריה של סוכן או בינה מלאכותית גנרטיבית, בהתאם לשפה ולתצורה.

קטגוריה מה זה מכסה
צינורות אותות עקבות, מדדים ויומני רישום.
זיהוי משאבים הקשר של שירות, מארח, ענן וזמן ריצה של Azure היכן שנתמך.
אינסטרומנטציה של תשתיות HTTP, ASP.NET Core, Azure SDK, לקוחות מסד נתונים ומסגרות רישום במידת הנתמכות.
מכשור בינה מלאכותית גנרטיבי OpenAI, Azure OpenAI, Semantic Kernel, LangChain, OpenAI Agents SDK Agent Framework היכן שקיימים תמיכה.
טווחי סוכן ידניים קריאה לסוכן, ביצוע כלי, הסקה וטלמטריית פלט, היכן שנתמכים
קריאה לסוכן, ביצוע כלי, הסקה וטלמטריית פלט, היכן שנתמכים Azure Monitor, Microsoft Agent 365, OTLP, פלט קונסולה, מעבדי span, מעבדי יומן וקוראי מדדים.

היקף מכשור

שפה מכשור יישום נפוץ מכשור סוכן מלאכותית נפוץ ומכשור בינה מלאכותית גנרטיבית
Python משאבי OpenTelemetry, מעבדים, קוראים, רישום, מדדים ומעקבים. Semantic Kernel, ערכת פיתוח תוכנה של OpenAI Agents, סוכן Agent Framework, LangChain, מטען של Microsoft Agent 365, והיקפי Microsoft Agent 365.
Node.js HTTP, Azure SDK, Azure Functions, MongoDB, MySQL, PostgreSQL, Redis, Bunyan ו-Winston. ערכת פיתוח תוכנה של OpenAI Agents, LangChain, מטען של Microsoft Agent 365, והיקפי Microsoft Agent 365.
NET. ASP.NET Core, HttpClient, SQL Client, Azure SDK, זיהוי משאבים, מדדים ויומני רישום. Semantic Kernel, OpenAI Azure OpenAI, Agent Framework, מטען של Microsoft Agent 365, והיקפי Microsoft Agent 365.

מכשור אוטומטי מאזין לאותות טלמטריה הנפלטים על ידי ספריות ומסגרות נתמכות. מכשור ידני משמש כאשר יישום צריך לתאר פעולות ספציפיות לסוכן, כגון קריאה, ביצוע כלי, הסקה או פלט אסינכרוני.

הוסף מקורות, מדי מכשיר, מעבדים או קוראים מותאמים אישית של OpenTelemetry כאשר היישום שלך פולט טלמטריה שאינה מכוסה על ידי המכשור המובנה.

חשוב

מכשור אוטומטי מאכלס רק תכונות סטנדרטיות של OpenTelemetry. זה לא כולל את כל התכונות ש-Agent 365 דורש. עליך להוסיף מאפיינים ספציפיים ל-Microsoft דרך BaggageBuilder. כדי לראות אילו מאפיינים נדרשים, ראה מאפייני אימות חנות.

ספריות מכשור מובנות

מכשור אוטומטי מאזין לטלמטריה הנפלטת על ידי מסגרות נתמכות ומעביר אותה דרך צינור OpenTelemetry של ההפצה. עבור תרחישי סוכן, הגדר מטען כגון מזהה דייר ומזהה סוכן לפני שהמסגרת המאומצת יוצרת טווחים.

מסגרת Python Node.js NET.
Semantic Kernel נתמך לא נתמך נתמך
ערכת פיתוח תוכנה של OpenAI וסוכני OpenAI נתמך נתמך נתמך
Agent Framework נתמך לא נתמך נתמך
LangChain נתמך נתמך לא מופיע

Semantic Kernel

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 פעולת הסקה של מודל בינה מלאכותית.
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

הגדר את ההפצה לשליחת טלמטריה לאספן מקומי או לנקודת קצה אחרת התואמת 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, עליך לספק מנגנון לאספקת אסימון אימות. פותר האסימון פועל לפי אצוות ייצוא באמצעות מזהה הסוכן ומזהה הדייר מהקשר המזוודות הפעיל. ההפצה תומכת בשתי גישות.

עצה

אם אתם בונים סוכן עם ה- Microsoft 365 Agent SDK, לִרְאוֹתהגדרת אימות תצפית עבור סוכן SDK לקבלת הוראות שלב אחר שלב להגדרת רכישת אסימוני OBO ו-S2S עבור סוכן ולא סוכן.

פותר אסימונים ידני

השתמש בפתרון ידני בעת רכישת אסימונים מחוץ לצינור של Agent Framework, בעת בניית אפליקציות שאינן של Agent Framework, או בעת שימוש באימות שירות-לשירות (S2S) (זרימת אישורי לקוח). סוכן יכולים ליצור אסימון בעצמם, לדוגמה באמצעות ספריית האימות של Microsoft ‏(MSAL) או כל אסימון אחר שיטת הרכישה, אך עליהם לוודא שלאסימון יש את טווח התצפית הנכון (api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite).

הערה

עבור אימות שירות-לשירות (S2S), עליך להשתמש בגישת פתרון אסימונים ידנית זו. מטמון אסימון סוכן תומך רק בזרימות אימות מטעם (OBO).

הדוגמאות הבאות מראות את תבנית פתרון אסימון OBO (מטעם) - הסוכן מקבל אסימון משתמש דרך מטפל האימות האג'נטי ומחליף אותו באסימון עם טווח תצפית. עבור דוגמאות S2S (שירות לשירות) והשוואה בין אימות OBO לאימות S2S, ראה הגדרת אימות של ניראות עבור ערכת פיתוח התוכנה של סוכן.

הפותר חייב להיות סינכרוני. קבל את ה-token במטפל הפעילות האסינכרוני שלך (או דרך 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

עבור אפליקציות Agent Framework המשתמשות באימות מטעם (OBO), ההפצה נרשמת אוטומטית IExporterTokenCache<AgenticTokenStruct> דרך DI כאשר אינך מגדיר התאמה אישית TokenResolver. הסוכן שלך מתקשר 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. כל היקף מתאים לפעולת span בסכימה הקנונית:

טווח SDK פעולת Span קוד ייחוס אוניברסלי
InvokeAgentScope invoke_agent IA
ExecuteToolScope execute_tool ET
InferenceScope chat CH
OutputScope output_messages OM

לקבלת רשימות התכונות הנדרשות והאופציונליות המלאות לפי היקף - כולל סמנטיקה לכל תכונה, הנחיות לבחירת ערכים ואילו תכונות ניתנות לשאילתה באמצעות ציד מתקדם של Microsoft Defender - ראה תכונת צפייה של Agent 365 reference. ה חל על העמודה מזהה לאיזה טווח שייך כל מאפיין, וה נדרש עמודה מבדילה בין חובה (M) מאופציונלי (O) תכונות.

בדוק את הסוכן שלך עם יכולת צפייה

לאחר יישום יכולת התצפית, ודא כי טלמטריה נקלטת:

  1. עבור אל https://admin.cloud.microsoft/#/agents/all.
  2. בחר את הסוכן שלך, ולאחר מכן בחר פעילות.
  3. ודא שמופיעות הפעלות וקריאות לכלי.

יישומים לדוגמה ותצורה מתקדמת

לדוגמאות עבודה ואפשרויות תצורה מתקדמות, עיינו במאגרי GitHub עבור כל שפה:

‏‫פתרון בעיות

סעיף זה מתאר בעיות נפוצות בעת יישום ושימוש בהפצת Microsoft OpenTelemetry עם Agent 365.

בעיה Description
נתוני צפייה אינם מופיעים לא ניתן לראות טלמטריה מכיוון שייצוא של Agent 365 אינו מופעל, ההגדרה אינה שלמה או שפתרון האסימון נכשל.
חסר מזהה דייר או מזהה סוכן - טווחי זמן שדילגו עליהם טווחי טווח מסוננים לפני הייצוא כאשר מאפייני זהות נדרשים של דייר או סוכן חסרים.
כשל בפתרון אסימון - ייצוא דילג או לא מורשה הייצוא מדלג או נדחה כאשר פותר האסימון לא מחזיר אסימון או שגיאות במהלך רכישת האסימון.
HTTP 401 לא מורשה בקשות מגיעות לשירות אך האימות נכשל מכיוון שהאסימון אינו חוקי, פג תוקפו או מיועד לקהל היעד הלא נכון.
HTTP 403 אסור ההרשאה נכשלת עקב רישוי דייר חסר או הרשאות כתיבה חסרות לתצפית.
HTTP 403 אסור - אי התאמה במזהה הסוכן השירות דוחה ייצוא כאשר מזהה הסוכן בבקשה אינו תואם לזהות הסוכן המורשה על ידי האסימון.
שגיאות HTTP 429 או 5xx - שגיאות חולפות ויסות זמני או חוסר יציבות של הקצה האחורי משבשים את הייצוא וייתכן שידרשו ניסיונות חוזרים או כוונון אצווה.
פסק זמן לייצוא פעולות הייצוא חורגות ממגבלות הזמן הקצוב עקב עיכובים ברשת או השהיית תגובה של נקודות קצה.
הייצוא הצליח אך הטלמטריה לא מופיעה ב-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 .

  • בדוק את הגדרות פותר האסימונים

    היצואן דורש פתרון אסימון תקף שמחזיר אסימון Bearer עבור כל בקשת ייצוא. אם פותר האסימונים חסר או מחזיר 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. אחרים משליכים אותם בלי רישום.

פתרון:

  • לפני הייצוא, מחיצות ההפצה מחולקות לפי זהות דייר וסוכן. טווחי זמן חסרים מזהה דייר או מזהה סוכן נמחקים ולא נשלחים לשירות.
  • Ensure BaggageBuilder מוגדרת עם מזהה הדייר ומזהה הסוכן לפני יצירת ה-spans. ערכים אלה מתפשטים דרך ההקשר של OpenTelemetry ומחוברים לכל הטווחים שנוצרו בתוך טווח המטען. ל-API הספציפי לפלטפורמה, ראו מאפייני מטען.
  • אם אתה משתמש ב-כְּבוּדָה תוכנה ביניים או הפוך את עוזר ההקשר מחבילת האינטגרציה של האחסון, וודא שלפעילות TurnContext יש נמען תקף עם זהות סוכן.

כשל בפתרון אסימון - ייצוא דילג או לא מורשה

תסמינים: פותר האסימונים מחזיר null או זורק שגיאה. בהתאם לפלטפורמה, הייצוא מדלג לחלוטין או נכשל עם HTTP 401.

פתרון:

  • נדרש פותר האסימון. אם הוא חסר, הייצואן יציג שגיאה בעת ההפעלה. ודא שסופק פתרון אסימון ומחזיר אסימון Bearer תקף.
  • ודא שמזהה הדייר ומזהה הסוכן הנכונים מועברים ל-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. עבור אל פורטל אנטר>רישומי אפליקציות> select your Blueprint app.
    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 Forbiddenagent-ID-mismatch שקוראים לסוכן Agent 365 אחרי נקודות קצה.

סיבת שורש: שגיאה זו מתרחשת כאשר משתמשים במזהה לקוח ה-Blueprint במקום במזהה לקוח של מופע הסוכן בעת הגדרת פרטי הסוכן. מזהה הסוכן בכתובת ה-URL של הייצוא אינו תואם לזהות שאושרה על ידי האסימון, ולכן נקודת הקצה של המעקב דוחה את הבקשה.

פתרון:

  • ודא אם מזהה הדייר נוסף לרשימת הדיירים המורשים ב-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.

פתרון:

  • ודא שאתה עומד בדרישות המוקדמות לצפייה ביומני רישום מיוצאים:
  • אכלוס הטלמטריה יכול להימשך מספר דקות לאחר ייצוא מוצלח. המתן לפני שתעשה חקירה נוספת.
  • ודאו שהספנים מכילים מאפיינים תקפים microsoft.tenant.id ו-gen_ai.agent.id. תכונות זהות חסרות גורמות להשמטת טווחים בצד השרת גם אם ייצוא ה-HTTP מחזיר 200.

תוכן קשור

  • מושגי תצפית של Agent 365 - זרימת נתונים, מודלים של זהות, אימות, היקפים ומגבלות החלים על כל נתיב אינטגרציה.
  • התייחסות למאפיין תצפית של Agent 365 - סכמת תכונות טווח קנונית שכל טווח שנבלע על ידי Agent 365 חייב להתאים אליה.
  • Last updated on