Microsoft OpenTelemetry Distro

Microsoft OpenTelemetry Distro, aracı ve aracı olmayan uygulamalardan izleri, ölçümleri ve günlükleri toplamak için tek bir ekleme deneyimi sağlayan birleşik bir gözlemlenebilirlik dağıtımıdır. Microsoft Agent 365, Microsoft Atölye, Azure İzleyici ve OpenTelemetry Protokolü (OTLP) ile uyumlu herhangi bir arka uç için gözlemlenebilirliği destekler. .NET, Node.js ve Python'u destekleyen distro, birden fazla gözlemlenebilirlik yığını arasında parçalanmış kurulumu tek bir içe aktarma ve bir yapılandırma çağrısı ile değiştirir.

Temel avantajlar

Microsoft OpenTelemetry Distro şu avantajları sağlar:

  • Tek paket, tek API: Birden fazla dışarı aktarıcı ve enstrümantasyon paketini tek bir bağımlılıkla değiştirin.
  • Çok arka uç desteği: Telemetriyi aynı anda Azure İzleyici, Datadog, Grafana veya New Relic gibi herhangi bir OpenTelemetry Protokolü (OTLP) ile uyumlu uç noktaya ve Microsoft Agent 365'e gönderin.
  • Yerleşik enstrümantasyonlar: Ek yapılandırma olmadan HTTP, veritabanları, Azure SDK, Azure İşlevleri ve daha fazlası için otomatik enstrümantasyon kullanın.
  • Standartlara dayalı: Endüstri standardı gözlemlenebilirlik çerçevesi olan OpenTelemetry üzerine kurulu.
  • Minimal ortak kod: Uygulama giriş noktanıza tek bir içe aktarma ve tek bir işlev çağrısı ekleyin.

Yükleme ve yapılandırma

Bu rehber, Microsoft OpenTelemetry Distro ile uygulamanıza gözlemlenebilirlik eklemeyi gösterir. Distro, yerleşik enstrümantasyonlarla izleri, ölçümleri ve günlükleri otomatik olarak toplar ve telemetriyi Azure İzleyici, herhangi bir OpenTelemetry Protokolü (OTLP) uç noktası veya Microsoft Agent 365'e aktarır.

Kitaplığı yükleme

Microsoft OpenTelemetry Distro ile başlamak için, dilinizin paket yöneticisini kullanarak geliştirme platformunuz için uygun kitaplığı yükleyin.

Ön Koşullar: Python 3.10 veya sonrası.

pip install microsoft-opentelemetry

Konfigürasyon

Agent 365 dışarıyı aktarıcı bağlantı dizesi kullanmaz. Uç noktasını kiracıya dayalı olarak otomatik olarak keşfeder. Agent 365'e dışarı aktarmayı etkinleştirmek için dışarıyı aktarıcı hedefini ayarlayın ve belirli bir aracı kimliği ve kiracı kimliği için bir erişim belirteci döndüren bir belirteç çözümleyicisi sağlayın.

İzlenebilirliği etkinleştirmek için use_microsoft_opentelemetry() öğesini çağırın.

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

Özel belirteç çözümlemesi için (varsayılan belirteç çözümleyicisi yerine), El ile belirteç çözümleyicisi bölümüne bakın.

İsteğe bağlı a365_* kwarg'larını use_microsoft_opentelemetry()'ye geçirerek dışarı aktarıcı davranışını özelleştirebilirsiniz.

Parametre Açıklama Varsayılan
a365_use_s2s_endpoint True olduğunda, hizmetten hizmete uç nokta yolunu kullanır. False
a365_max_queue_size Toplu işlemci için maksimum kuyruk boyutu. 2048
a365_scheduled_delay_ms Dışarı aktarma toplu işleri arasındaki gecikme (milisaniye cinsinden). 5000
a365_exporter_timeout_ms Dışarı aktarma işlemi için zaman aşımı (milisaniye cinsinden). 30000
a365_max_export_batch_size Dışarı aktarma işlemleri için maksimum toplu boyut. 512

Bağlamı yayma

Dağıtılmış Agent 365 işlemleri genelinde gözlemlenebilirliği korumak için bağlamı yayın. Bağlamı aracılarınız ve hizmetleriniz arasında yayıldığında, izler, günlükler ve ölçümlerin tüm istek yaşam döngüsü genelinde doğru şekilde ilişkilendirilmesini sağlarsınız. Bu ilişkilendirme, eksiksiz ve etkili bir Microsoft Agent 365 izleme deneyimi için gereklidir.

Bagaj öznitelikleri

BaggageBuilder kullanarak bir istekteki tüm aralıklar arasında akan bağlamsal bilgileri ayarlayın. SDK, tüm boş olmayan bagaj girdilerini yeni başlatılan aralıklara kopyalayan bir SpanProcessor uygular ve mevcut özniteliklerin üzerine yazmaz.

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 öğesini TurnContext öğesinden otomatik olarak doldurmak için microsoft-opentelemetry paketindeki populate yardımcısını kullanın. Bu yardımcı, etkinlikten arayanı, aracıyı, kiracıyı, kanalı ve konuşma ayrıntılarını otomatik olarak ayıklar.

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

Bagaj ara yazılımı

Aracınız barındırma tümleştirme paketini kullanıyorsa, gelen her istek için bagajı otomatik olarak doldurmak üzere bagaj ara yazılımını kaydedin. Bu adım, her etkinlik işleyicisinde BaggageBuilder öğesini el ile çağırma gereksinimini ortadan kaldırır.

Python'da, bagaj ara yazılımını doğrudan bağdaştırıcıya değil ObservabilityHostingManager.configure() aracılığıyla kaydedin.

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

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

Ara yazılım, orijinal isteğin zaten ayarladığı bagajın üzerine yazılmasını önlemek için zaman uyumsuz yanıtlar (ContinueConversation olayları) için bagaj kurulumunu atlar.

Verilerin üretimde akış halinde olduğunu doğrulayın

Aracı telemetrisi verilerini Microsoft Purview veya Microsoft Defender'da görüntülemek için aşağıdaki gereksinimlerin karşılandığından emin olun:

Otomatik izleme

Microsoft OpenTelemetry Distro, standart OpenTelemetry işlem hatlarını Microsoft tarafından seçilen enstrümantasyonla birleştirir. Distro, dile ve yapılandırmaya bağlı olarak uygulama telemetrisi, altyapı telemetrisi ve aracı veya üretken AI telemetrisi toplayabilir.

Kategori Neleri kapsar
Sinyal ardışık düzenleri İzler, ölçümler ve günlükler.
Kaynak algılama Desteklenen hizmet, ana bilgisayar, bulut ve Azure çalışma zamanı bağlamı.
Altyapı izleme Desteklenen HTTP, ASP.NET Core, Azure SDK, veritabanı istemcileri ve günlüğe kaydetme çerçeveleri.
Üretici AI araçlandırması OpenAI, Azure OpenAI, Semantik Çekirdek, LangChain, OpenAI Aracılar SDK'sı ve desteklendiği durumlarda Agent Framework.
El ile aracı kapsamları Desteklenen aracı çağırma, araç yürütme, çıkarım ve çıkış telemetrisi.
Dışa aktarıcılar ve işlemciler Azure İzleyici, Microsoft Agent 365, OTLP, konsol çıkışı, span işlemcileri, günlük işlemcileri ve metrik okuyucuları.

İzleme kapsamı

Language Yaygın uygulama araçlandırması Yaygın aracı ve üretici AI araçlandırması
Python OpenTelemetry kaynakları, işlemcileri, okuyucuları, günlüğe kaydetme, metrikler ve izler. Semantik Çekirdek, OpenAI Aracılar SDK'sı, Agent Framework, LangChain, Microsoft Agent 365 bagajı ve Microsoft Agent 365 kapsamları.
Node.js HTTP, Azure SDK, Azure İşlevleri, MongoDB, MySQL, PostgreSQL, Redis, Bunyan ve Winston. OpenAI Aracılar SDK'sı, LangChain, Microsoft Agent 365 bagajı ve Microsoft Agent 365 kapsamları.
.NET ASP.NET Core, HttpClient, SQL Client, Azure SDK, kaynak algılaması, metrikler ve günlükler. Semantik Çekirdek, OpenAI ve Azure OpenAI, Agent Framework, Microsoft Agent 365 bagajı ve Microsoft Agent 365 kapsamları.

Otomatik araçlandırma, desteklenen kitaplık ve çerçeveler tarafından yayılan telemetri sinyallerini dinler. Manuel enstrümantasyon, bir uygulamanın aracı'ya özel işlemleri (çağırma, araç yürütme, çıkarım veya zaman uyumsuz çıktı gibi) tanımlaması gerektiğinde kullanılır.

Uygulamanız yerleşik enstrümantasyonlar tarafından kapsanmayan telemetri yayınladığında özel OpenTelemetry kaynakları, ölçerler, işlemciler veya okuyucular ekleyin.

Önemli

Otomatik enstrümantasyon yalnızca standart OpenTelemetry özniteliklerini doldurur. Agent 365'in gerektirdiği tüm öznitelikleri içermez. Microsoft'a özel öznitelikleri BaggageBuilder aracılığıyla eklemeniz gerekir. Hangi özniteliklerin gerekli olduğunu görmek için bkz. Depo doğrulama öznitelikleri.

Yerleşik enstrümantasyon kitaplıkları

Oto-enstrümantasyon, desteklenen çerçeveler tarafından yayımlanan telemetriyi dinler ve Distro'nun OpenTelemetry ardışık düzeni aracılığıyla iletir. Aracı senaryoları için, enstrümante edilmiş çerçeve alanları oluşturmadan önce kiracı kimliği ve aracı kimliği gibi bagaj ayarlayın.

Çerçeve Python Node.js .NET
Semantik Çekirdek Desteklenir Desteklenmez Desteklenir
OpenAI ve OpenAI Aracılar SDK'sı Desteklenir Desteklenir Desteklenir
Agent Framework Desteklenir Desteklenmez Desteklenir
LangChain Desteklenir Desteklenir Listede yok

Semantik Çekirdek

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

Manuel izleme

Otomatik izleme, aracı işlemini yeterli ayrıntıyla tanımlamadığında manuel izleme kullanın. Manuel kapsamlar, bir uygulamanın yaygın aracı etkinliklerini diller arasında tutarlı bir şekilde tanımlamasına olanak tanır.

Kapsam Kullanılacağı senaryo
InvokeAgentScope Bir aracı çağrısının başlangıcı ve tamamlanması.
ExecuteToolScope Bir aracı tarafından yapılan araç çağrısı.
InferenceScope Bir AI modeli çıkarım işlemi.
OutputScope Kaynak kapsamı zaten tamamlandıktan sonra kaydedilmesi gereken çıktı.

İlgili telemetri verilerinin ilişkilendirilebilmesi için, bir istekteki kapsamlar arasında aynı istek ve aracı kimlik değerlerini yeniden kullanın.

Aracı çağırma

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."])

Araç yürütme

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)

Çıkarım

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

Çıktı

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

Ürün belgeleri, bu kapsamlar için ürüne özgü doğrulama gereksinimlerini tanımlamalıdır.

Yerel doğrulama

Yerel doğrulama, uygulamanın ürüne özgü bir hedef doğrulanmadan önce telemetri ürettiğini onaylar. İzlemeler, ölçümler ve günlüklerin oluşturulduğunu kontrol etmek için konsol çıkışını veya yerel bir OTLP uç noktasını kullanın.

Yerel OTLP uç noktası ile doğrulama yapın

Dağıtımı, telemetriyi yerel bir toplayıcıya veya başka bir OTLP uyumlu uç noktaya göndermek için yapılandırın.

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

Yerel çıkış ile doğrulama yapın

Telemetriyi uzak bir hedefe göndermeden önce enstrümantasyonu doğrulamak istediğinizde yerel çıkışı kullanın.

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 istekleri, OpenAI veya Azure OpenAI çağrıları, aracı çağırma kapsamları, araç yürütme kapsamları veya çıkarım kapsamları gibi beklenen kaynaklardan yayınlar için yerel çıkışı gözden geçirin. Hedefe özgü doğrulama, söz konusu hedef için ürün belgesinde yer almalıdır.

Kimlik doğrulamayı el ile ayarlama

Agent 365 dışarı aktarıcısını kullandığınızda, bir kimlik doğrulama belirteci sağlamak için bir mekanizma sunmalısınız. Belirteç çözümleyicisi, etkin bagaj bağlamından aracı kimliği ve kiracı kimliği kullanarak dışarı aktarma toplu işinin başına ait olarak çalışır. Distro iki yaklaşımı destekler.

İpucu

Microsoft 365 Aracıları SDK'sı ile aracılar oluşturuyorsanız, OBO ve S2S belirteç edinimini hem agentic hem de non-agentic aracılar için yapılandırma hakkında adım adım yönergeler için Agent SDK için Gözlemlenebilirlik Kimlik Doğrulaması Kurulumu konusunu inceleyin.

El ile belirteç çözümleyicisi

Agent Framework ardışık düzeninin dışında belirteç edindiğinizde, Agent Framework olmayan uygulamalar oluşturduğunuzda veya hizmet-hizmet (S2S) kimlik doğrulaması (istemci kimlik bilgileri akışı) kullandığınızda el ile çözümleyici kullanın. Aracılar, örneğin Microsoft Kimlik Doğrulama Kitaplığı (MSAL) veya diğer belirteç edinme yöntemini kullanarak kendileri bir belirteç oluşturabilir, ancak belirtecin doğru gözlemlenebilirlik kapsamına sahip olduğundan emin olması gerekir (api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite).

Not

Hizmet-hizmet (S2S) kimlik doğrulaması için bu el ile belirteç çözümleyici yaklaşımını kullanmanız gerekir. aracı belirteç önbelleği yalnızca adına (OBO) kimlik doğrulama akışlarını destekler.

Aşağıdaki örnekler OBO (adına) belirteç çözümleyici desenini gösterir — aracı, aracı kimlik doğrulama işleyicisi aracılığıyla bir kullanıcı belirteci edinir ve bunu gözlemlenebilirlik kapsamlı bir belirteçle değiştirir. S2S (hizmet-hizmet) örnekleri ve OBO ve S2S kimlik doğrulamasının karşılaştırması için bkz. Aracı SDK'sı için Gözlemlenebilirlik Kimlik Doğrulama Kurulumu.

Çözümleyici eşzamanlı olmalıdır. Zaman uyumsuz etkinlik işleyicinizde (veya MSAL aracılığıyla) belirteci edinin ve çözümleyici için önbelleğe alın.

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 uygulamalarıyla aracı temelli belirteç önbelleği

Adına (OBO) kimlik doğrulaması kullanan Agent Framework uygulamaları için, özel bir TokenResolver ayarlamadığınızda, dağıtım otomatik olarak IExporterTokenCache<AgenticTokenStruct> öğesini DI aracılığıyla kaydeder. Aracınız çalışma zamanında kimlik bilgilerini sağlamak için RegisterObservability() çağırır ve önbellek belirteci edinme ve yenilemeyi işler.

Not

Bu yaklaşım yalnızca adına (OBO) kimlik doğrulama akışlarını destekler. Hizmet-hizmet (S2S) kimlik doğrulaması için el ile belirteç çözümleyicisini kullanın.

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

Doğrulama özniteliklerini depolayın

Başarılı depo doğrulaması için aracınız InvokeAgentScope, InferenceScope ve ExecuteToolScope uygulamalıdır. Her kapsam, kurallı şemada bir yayılma işlemine karşılık gelir:

SDK kapsamı Span işlemi Evrensel başvuru kodu
InvokeAgentScope invoke_agent IA
ExecuteToolScope execute_tool ET
InferenceScope chat CH
OutputScope output_messages OM

Kapsamlı gerekli ve isteğe bağlı öznitelik listeleri (öznitelik semantiği, değer seçme rehberi ve Microsoft Defender gelişmiş avcılıkta sorgulanabilen öznitelikler dahil) için bkz. Agent 365 gözlemlenebilirlik öznitelik başvurusu. Uygulanan sütunu her özniteliğin hangi kapsama ait olduğunu tanımlar ve Gerekli sütunu zorunlu (M) öznitelikleri isteğe bağlı (O) özniteliklerden ayırır.

Aracınızı gözlemlenebilirlikle test edin

Gözlemlenebilirliği uyguladıktan sonra, telemetrinin yakalandığını doğrulayın:

  1. https://admin.cloud.microsoft/#/agents/all öğesine gidin.
  2. Aracınızı seçin ve ardından Etkinlik seçeneğini seçin.
  3. Oturumların ve araç çağrılarının göründüğünü doğrulayın.

Örnek uygulamalar ve gelişmiş yapılandırma

Çalışan örnekler ve gelişmiş yapılandırma seçenekleri için, her bir dil için GitHub depolarına bakın:

Sorun giderme

Bu bölüm, Microsoft OpenTelemetry Distro'nun Agent 365 ile uygulanması ve kullanılması sırasında karşılaşılan yaygın sorunları açıklamaktadır.

Sorun Açıklama
Gözlemlenebilirlik verileri görünmüyor Agent 365 dışarı aktarma özelliği etkinleştirilmediğinden, kurulum tamamlanmadığından veya belirteç çözümü başarısız olduğundan hiçbir telemetri görünmüyor.
Kiracı kimliği veya aracı kimliği eksik - yayılmalar atlandı Gerekli kiracı veya aracı kimlik öznitelikleri eksik olduğunda yayılmalar dışarı aktarılmadan önce filtrelenir.
Belirteç çözümü başarısızlığı - dışarı aktarma atlandı veya yetkisiz Belirteç çözümleyici hiçbir belirteç döndürmediğinde veya belirteç alımı sırasında hata oluştuğunda dışarı aktarma atlanır veya reddedilir.
HTTP 401 Yetkisiz İstekler hizmete ulaşır ancak belirteç geçersiz, süresi dolmuş veya yanlış hedef kitle için olduğundan kimlik doğrulaması başarısız olur.
HTTP 403 Yasak Eksik kiracı lisanslaması veya eksik gözlemlenebilirlik yazma izinleri nedeniyle yetkilendirme başarısız olur.
HTTP 403 Yasak - Aracı Kimliği uyuşmazlığı Hizmet, istekteki aracı kimliği belirteçle yetkilendirilmiş aracı kimliğiyle eşleşmediğinde dışa aktarımı reddeder.
HTTP 429 veya 5xx hataları - Geçici hatalar Geçici azaltma veya arka uç kararsızlığı dışa aktarımını kesintiye uğratır ve yeniden denemeler veya toplu işlem ayarlaması gerektirebilir.
Dışa aktarma zaman aşımı Dışa aktarım işlemleri ağ gecikmeleri veya uç nokta yanıt gecikmesi nedeniyle zaman aşımı sınırlarını aşar.
Dışa aktarım başarılı olur ancak telemetri Defender veya Purview'da görünmez Veri alımı başarılı olur ancak görünürlük aşağı akış önkoşulları ve şema gereksinimleri tarafından geciktirilir veya engellenir.

İpucu

Agent 365 Sorun Giderme Kılavuzu yüksek seviyeli sorun giderme önerileri, en iyi uygulamalar ve Agent 365 geliştirme yaşam döngüsünün her aşamasına yönelik sorun giderme içeriğine bağlantılar sunar.

Gözlemlenebilirlik verileri görünmüyor

Belirtiler:

  • Aracı çalışıyor
  • Yönetim merkezinde telemetri yok
  • Aracı etkinliğini göremiyorsunuz

Temel neden:

  • Agent 365 dışa aktarımı etkin değil
  • Yapılandırma hataları
  • Belirteç çözümleyici sorunları

Çözümler: Sorunu çözmek için aşağıdaki adımları deneyin:

  • Agent 365 dışa aktarmanın etkinleştirildiğini doğrulayın

    Agent 365 dışa aktarıcısını açıkça etkinleştirmeniz gerekir. Bunu ayarlamadığınızda, dağıtım bir konsol dışa aktarıcısına geri dönebilir veya hiçbir şey dışa aktarmayabilir. Bunu kodda etkinleştirin:

    from microsoft.opentelemetry import use_microsoft_opentelemetry

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

    Veya ortam değişkenini ayarlayın:

    export ENABLE_A365_OBSERVABILITY_EXPORTER=true

    Not

    ENABLE_A365_OBSERVABILITY_EXPORTER, yalnızca enable_a365=True kodda ayarlandığında yürürlüğe giren ikincil bir geçiştir. Bunu a365_enable_observability_exporter kwarg aracılığıyla da kontrol edebilirsiniz.

  • Belirteç çözümleyici yapılandırmasını kontrol edin

    Dışa aktarıcı, her dışa aktarma isteği için bir Bearer belirteci döndüren geçerli bir belirteç çözümleyici gerektirir. Belirteç çözümleyici eksikse veya null döndürürse, dışa aktarma sessizce atlanır.

  • Konsol dışa aktarmanı etkinleştirin ve telemetryi yerel olarak kontrol edin

    Telemetrinin Agent 365 uç noktasına ulaşmadan önce oluşturulduğunu doğrulamak için bir konsol dışa aktarıcısı ekleyin:

    use_microsoft_opentelemetry(enable_a365=True, enable_console=True)

  • Ayrıntılı günlüğü etkinleştirin

    import logging

logging.basicConfig(level=logging.DEBUG)

  • Dışa aktarma hataları için günlükleri denetleyin

    az webapp log tail komutunu kullanarak gözlemlenebilirlik ile ilgili hataları bulmak için günlükleri arayın:

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

Kiracı kimliği veya aracı kimliği eksik — yayılımlar atlandı

Belirtiler: Sistem yayılımları sessizce bırakır ve bunları hiçbir zaman dışa aktarmaz. Bazı platformlar atlanan yayılımların sayısını veya No spans with tenant/agent identity found gibi bir iletiyi günlüğe kaydeder. Diğerleri bunları günlüğe kaydetmeden bırakır.

Çözüm:

  • Dışa aktarmadan önce dağıtım, yayılımları kiracı ve aracı kimliğine göre böler. Kiracı kimliği veya aracı kimliğinden birini eksik olan yayılımlar bırakılır ve hiçbir zaman hizmete gönderilmez.
  • BaggageBuilder öğesinin yayılımlar oluşturmadan önce kiracı kimliği ve aracı kimliği ile ayarlandığından emin olun. Bu değerler OpenTelemetry bağlamı aracılığıyla yayılır ve bagaj kapsamı içinde oluşturulan tüm yayılımlara eklenir. Platform'a özgü API için bkz. Bagaj öznitelikleri.
  • Barındırma tümleştirme paketinden bagaj ara yazılımı veya bağlam yardımcı etkinliğini kullanıyorsanız, TurnContext etkinliğinin aracı kimliğine sahip geçerli bir alıcısı olduğunu doğrulayın.

Belirteç çözümleme başarısızlığı — dışa aktarma atlandı veya yetkisiz

Belirtiler: Belirteç çözümleyici null döndürür veya bir hata oluşturur. Platforma bağlı olarak, dışa aktarma işlemi tamamen atlanır veya HTTP 401 hatası ile başarısız olur.

Çözüm:

  • Belirteç çözümleyici gereklidir. Eksikse, dışa aktarıcı başlangıçta bir hata oluşturur. Belirteç çözümleyicisinin sağlandığını ve geçerli bir Bearer belirteci döndürdüğünü doğrulayın.
  • Doğru kiracı kimliği ve aracı kimliğinin BaggageBuilder öğesine geçildiğinden emin olun, çünkü bu değerler belirteç çözümleyicisine iletilir.
  • Azure'da barındırılan aracılar için, Yönetilen Kimliğin gözlemlenebilirlik kapsamı için gerekli API izinlerine sahip olduğunu doğrulayın.
  • .NET uygulamaları Agent Framework barındırma paketi kullanıyorsa, belirteç değişimi bağımlılık enjeksiyonu aracılığıyla otomatik olarak işlenir. Belirteçler eksikse, Microsoft.Agents.A365.Observability.Hosting öğesinin yüklendiğini ve kaydedildiğini doğrulayın.

HTTP 401 Yetkisiz

Belirtiler: Dışa aktarma işlemi HTTP 401 hatası ile başarısız olur. Dışa aktarıcı bu hatayı yeniden denenmez.

Çözüm:

  • Belirteç izleyicisinin gözlemlenebilirlik uç noktası kapsamı ile eşleştiğini doğrulayın.
  • Belirteç çözümleyicisinin temsilci kullanıcı belirteci, yanlış izleyici için bir belirteç veya süresi dolmuş bir belirteç döndürmediğini kontrol edin.

HTTP 403 Yasak

Belirtiler: Dışa aktarma işlemi HTTP 403 hatası ile başarısız olur. Dışa aktarıcı bu hatayı yeniden denenmez.

Temel neden: HTTP 403 hatası farklı nedenlere sahip olabilir. Sırasıyla aşağıdaki çözümleri kontrol edin.

Çözüm:

  • Eksik lisans — Kiracınızda Microsoft 365 yönetim merkezi içinde aşağıdaki lisanslardan birinin atandığını doğrulayın:

    • Test - Microsoft 365 E7
    • Microsoft 365 E7
    • Microsoft Agent 365 Frontier

  • Agent365.Observability.OtelWrite izni eksik — İzni kimliğinize (Yönetilen Kimlik veya uygulama kaydı) verin. Bunu yapmazsanız telemetri dışa aktarması HTTP 403 hatasıyla başarısız olur.

İzni ver

Aşağıdaki seçeneklerden birini kullanın:

  • Agent 365 CLI

    Bir Global Administrator hesabı gerektirir; aracı proje dizininden a365.config.json içeren dizinde çalıştırın ya da --agent-name kullanın.

    a365 setup permissions bot

    Alternatif olarak, yapılandırma dosyası olmadan:

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

  • Entra Portalı

    Yapılandırma dosyası gerekli değildir; Blueprint uygulama kaydına Global Administrator erişimi gerektirir.

    1. Entra portalına>Uygulama kayıtlarına> gidin ve Blueprint uygulamanızı seçin.
    2. API izinleri>İzin ekle>Kuruluşumun kullandığı API'ler> öğesine gidin ve 9b975845-388f-4429-889e-eab1ef63949c arayın.
    3. Temsilci izinleri> seçin, Agent365.Observability.OtelWrite> işaretleyin ve İzin ekle öğesine tıklayın.
    4. 2–3. adımları yineleyin, bu sefer Uygulama izinleri> seçin, Agent365.Observability.OtelWrite> işaretleyin ve İzin ekle öğesine tıklayın.
    5. Yönetici onayı ver öğesine tıklayın ve onaylayın.

    Hem Agent365.Observability.OtelWrite (Temsilci) hem de Agent365.Observability.OtelWrite (Uygulama) Granted durumunu göster.

HTTP 403 Yasak — Aracı Kimliği uyuşmazlığı

Belirtiler: HTTP 403 hatası ile dışa aktarma başarısız olur ve 403 Forbidden ile agent-ID-mismatch hatasına benzer bir sunucu iletisi gösterilir. Agent 365 izlemeleri uç noktalarını çağırırken bu hata oluşur.

Temel neden: Bu hata, aracı ayrıntılarını ayarlarken aracı örneği istemci kimliği yerine şema istemci kimliği kullandığınızda oluşur. Dışa aktarma URL'sindeki aracı kimliği belirteç tarafından yetkilendirilen kimlikle eşleşmediğinden, izlemeleri uç noktası isteği reddeder.

Çözüm:

  • Kiracı kimliğinin Agent 365 izin verilen kiracı listesine eklenip eklenmediğini doğrulayın.
  • Aracı ayrıntılarını aracı örneği istemci kimliği ile ayarlayın (şema istemci kimliği değil).
  • Oluşturulan dışa aktarma URL'sini doğrulayın - logger'ınızı etkinleştirirseniz günlüğe kaydedilir. URL'deki aracı kimliğinin aracı örneği istemci kimliğiyle eşleştiğini doğrulayın.
  • SDK başına tanılama günlüğünü etkinleştirmek için Yerel doğrulama bölümüne bakın.

HTTP 429 veya 5xx hataları - Geçici hatalar

Belirtiler: Dışa aktarma, 429 veya 5xx gibi geçici bir HTTP durum koduyla başarısız olur.

Çözüm:

  • Bu hatalar genellikle geçicidir ve kendi kendilerine çözülür. Python ve JavaScript dağıtımları HTTP 408, 429 ve 5xx durum kodlarında otomatik olarak yeniden denemeyi yapar. .NET dağıtımı otomatik olarak yeniden denemez.
  • Hatalar devam ederse, hizmet sağlığı panosunu kontrol edin.
  • Toplu işler arasında zamanlanan gecikmeyi artırarak veya en fazla dışa aktarma toplu iş boyutunu artırarak dışa aktarma sıklığını azaltmayı düşünün. Python ve JavaScript için, exporterOptions veya a365_* parametrelerini kullanın. Bu parametreler GitHub depoları içinde belgelenmiştir. .NET için o.Agent365.Exporter.ScheduledDelayMilliseconds ve o.Agent365.Exporter.MaxExportBatchSize kullanın.

Dışa aktarma zaman aşımı

Belirtiler: Dışa aktarma denemeleri zaman aşımına uğrar.

Çözüm:

  • Gözlemlenebilirlik uç noktasına ağ bağlantısını kontrol edin.

  • Varsayılan HTTP istek zaman aşımı tüm platformlarda 30 saniyedir. Zaman aşımları sık sık meydana gelirse, dışa aktarıcı seçeneklerinizde zaman aşımı değerini artırın:

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

    Tüm Python deposu seçeneklerinin tam listesi için bkz. a365_*.

Dışa aktarma başarılı olur ancak telemetri, Defender veya Purview'da görünmez

Belirtiler: Günlükler başarılı bir dışa aktarmayı (HTTP 200) gösterir, ancak telemetri Microsoft Defender veya Microsoft Purview'da görünmez.

Çözüm:

  • Dışa aktarılan günlükleri görüntülemeye yönelik ön koşulları karşıladığınızı doğrulayın:
  • Telemetri, başarılı bir dışa aktarmanın ardından doldurulması birkaç dakika sürebilir. Daha fazla araştırma yapmadan önce bekleyin.
  • Aralıkların geçerli microsoft.tenant.id ve gen_ai.agent.id öznitelikleri içerdiğini doğrulayın. Eksik kimlik öznitelikleri, HTTP dışa aktarması 200 döndürse bile aralıkların sunucu tarafında bırakılmasına neden olur.

İlgili içerik

  • Last updated on