Doğrudan OTel kullanarak aracı gözlemlenebilirliğini tümleştirme

Bu kılavuz, aracı telemetrisini Agent 365'e doğrudan OpenTelemetry (OTLP/HTTP+JSON) üzerinden gönderme konusunda başından sonuna kadar size yol gösterir. Başlamadan önce, modeli, kimlik doğrulama akışlarını ve verilerinizin nereye indiğini anlamak için Agent 365 gözlemlenebilirlik kavramlarını okuyun.

Önemli

Doğrudan OTel yolu istisna olup, varsayılan değildir. Bunu yalnızca zaten bir OpenTelemetry işlem hattına sahipseniz, çerçeveniz Agent 365 SDK'sını kullanamıyorsa veya aracınız SDK'nın henüz desteklemediği bir dilde yazılmışsa (örneğin Java) kullanın. Diğer herkes için önerilen yol, Agent 365, Microsoft Atölye, Azure İzleyici ve daha fazlası arasında birleşik bir gözlemlenebilirlik SDK'sı sağlayan Microsoft OpenTelemetry Distro'dur. Önceki Gözlemlenebilirlik SDK'sı değişiklikler olmadan çalışmaya devam eder ancak yeni tümleştirmeler için artık önerilmemektedir; mevcut SDK kullanıcıları için geçiş kılavuzu yakında sunulacaktır.

Ön koşullar

Herhangi bir telemetri akışından önce aşağıdaki yapılandırmaların yerinde olduğundan emin olun.

Kim	Ne
Kiracı yöneticisi	Agent 365'e kaydolun ve aracı uygulamanız için onay verin. Bkz. Agent 365'e Ekleme. Lisanslı bir kiracı olmadan, alım sessizce bırakılır - istek `200 OK` ile `partialSuccess: null` döndürür ancak veriler asla aşağı akışta görünmez.
Kiracı yöneticisi	Kiracıda en az bir kullanıcıya Microsoft 365 E7 veya Microsoft Agent 365 lisansı atayın. SKU'nun mevcut olması yeterli değildir. Bir kullanıcıya atanması, alımı sağlayan Defender arka uç iş akışını başlatır. Atanmış bir lisans olmadan, istekler `200 OK` ile `partialSuccess: null` döndürür ve veriler sessizce bırakılır.
Kiracı yöneticisi	Kiracı onayı verin. Bkz. Aracılara Microsoft 365 kaynaklarına erişim izni verme. Bunu yapmadığınızda, belirteçler rol/kapsam olmadan verilir ve istekler `403` döndürür.
Geliştirme ekibiniz	Uygulamanızı kaydedin (standart Microsoft Entra uygulaması veya şablon). Bkz. Agent 365 geliştirmeye başlayın.
Geliştirme ekibiniz	`Agent365.Observability.OtelWrite` öğesini API izinleri altına ekleyin (S2S için uygulama rolü, temsilci için kapsam). Şablonlar için bkz. Devralınabilir izinleri yapılandırma. İzni etkinleştirmek için Agent 365 onboarding ekibiyle koordinasyon sağlayın.

Kimlik doğrulama tarifleri

Dört tarifin tümü standart Microsoft Entra belirteç uç noktasını kullanır:

Alan	Değer
Belirteç uç noktası	`https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token`
Kaynak (`aud` döndürülen belirtecin içinde)	`9b975845-388f-4429-889e-eab1ef63949c` (ayrıca `api://9b975845-388f-4429-889e-eab1ef63949c` kabul eder)
S2S kapsamı	`9b975845-388f-4429-889e-eab1ef63949c/.default`
OBO kapsamı	`9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite`

Aşağıdaki tarifler açıklık için ham HTTP'yi gösterir. Üretimde, Microsoft.Identity.Web veya belirteç yenileme ve önbelleklemeyi işleyen başka bir MSAL kitaplığını tercih edin.

Hangi tarife ihtiyacım var?

Uygulama modelim	OAuth akışım	Şu konuma gidin:
Standart Microsoft Entra uygulama kaydı	S2S (istemci kimlik bilgileri)	S2S, Standart Microsoft Entra uygulaması
Standart Microsoft Entra uygulama kaydı	OBO (temsilci)	OBO, Standart Microsoft Entra uygulaması
Blueprint'ten türetilen aracı kimliği	S2S (istemci kimlik bilgileri)	S2S, Blueprint'ten türetilen aracı kimliği
Blueprint'ten türetilen aracı kimliği	OBO / AI takım arkadaşı	OBO, Blueprint'ten türetilen aracı kimliği

S2S, Standart Microsoft Entra uygulaması

Kiracının belirteç uç noktasına grant_type=client_credentials ile bir POST isteği gönderilir. Uygulamayı bir istemci parolası, sertifika (imzalı JWT onaylaması) ya da yönetilen kimlik veya federal kimlik bilgileriyle doğrulayın.

POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={your-app-id}
&scope=9b975845-388f-4429-889e-eab1ef63949c%2F.default
&client_secret={secret}
&grant_type=client_credentials

Döndürülen belirteç appid/azp = {your-app-id}, roles içeren Agent365.Observability.OtelWrite ve aud = 9b975845-... içerir. Bunu /observabilityService/.../traces yolu üzerinde kullanın.

Sertifika tabanlı kimlik doğrulaması için client_secret={secret} yerine client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={signed-jwt} yazın.

S2S, Blueprint'ten türetilen aracı kimliği

Aracı kimliklerinin kendi kimlik bilgileri yoktur. aracı kimliği blueprint'i kimlik bilgilerini (yönetilen kimlik FIC, sertifika veya istemci parolası) tutar ve belirteçleri iki aşamalı bir değişim aracılığıyla kendi adına alt aracı kimliklerine basarak hazırlar. Daha fazla bilgi için bkz. özerk uygulama OAuth akışı.

Blueprint doğruluğu yapar ve federal kimlik değişim belirteci alır T1:

{blueprint-credential} şemanın MSI belirteci, sertifika imzalı JWT veya gizli dizi değişim onayı (şema yapılandırmasına göre).

POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={blueprint-app-id}
&scope=api%3A%2F%2FAzureADTokenExchange%2F.default
&fmi_path={agent-identity-app-id}
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion={blueprint-credential}
&grant_type=client_credentials

Aracı kimliği T1 öğesini Agent 365 Gözlemlenebilirlik kaynak belirteci ile değiştirir:
```
POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={agent-identity-app-id}
&scope=9b975845-388f-4429-889e-eab1ef63949c%2F.default
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion={T1}
&grant_type=client_credentials
```
- Döndürülen belirtecin appid/azp = {agent-identity-app-id}, roles içeren Agent365.Observability.OtelWrite, ve aud = 9b975845-... vardır.
- Bu belirteci /observabilityService/.../traces rotasında kullanın.
- {agentId} URL'si aracı kimliği appId olup, şema appId değildir.

OBO, Standart Microsoft Entra uygulaması

Kullanıcının gelen belirteci Tc öğesini yukarı akış çağrıcıdan (Bearer veya PFAT) alıp değiştirin:

POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={your-app-id}
&scope=9b975845-388f-4429-889e-eab1ef63949c%2FAgent365.Observability.OtelWrite
&client_secret={secret}
&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion={Tc}
&requested_token_use=on_behalf_of

Sertifika kimlik doğrulaması için client_secret={secret} öğesini S2S ile aynı client_assertion_type + client_assertion çifti ile değiştirin.

Döndürülen belirtecin appid/azp = {your-app-id}, scp içeren Agent365.Observability.OtelWrite, ve aud = 9b975845-... vardır. Bunu /observability/.../traces rotasında kullanın. Yenileme belirteci de döndürülür; her çağrıda değişimi yeniden çalıştırmak yerine önbelleğe alıp yeniden kullanın.

OBO, Şemadan türetilmiş aracı kimliği (AI takım üyesi dahil)

Yetkisi olan akışının üç ana adımı vardır. Daha fazla bilgi için bkz. Aracı OAuth akışları: Yetkisi olan akış.

Kullanıcı belirteci Tc alıp. AI takım üyesi için bu belirteç aracının kendi kullanıcı hesabını temsil eder; aksi takdirde insan çağrıcıyı temsil eder.
Şema kimlik doğrular ve T1 alır; bu S2S şemadan türetilmiş aracı kimliği akışı ile aynıdır.

Aracı kimliği T1 ve Tc öğesini temsilci kaynak belirteci ile değiştirir:

POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={agent-identity-app-id}
&scope=9b975845-388f-4429-889e-eab1ef63949c%2FAgent365.Observability.OtelWrite
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion={T1}
&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion={Tc}
&requested_token_use=on_behalf_of

Döndürülen belirtecin appid/azp = {agent-identity-app-id}, scp içeren Agent365.Observability.OtelWrite, ve aracının kullanıcısını temsil eder. Bunu /observability/.../traces rotasında kullanın. {agentId} URL'si aracı kimliği appId olup, şema appId değildir. Yenileme belirteci de döndürülür; önbelleğe alın ve yeniden kullanın.

Döndürülen belirtecin gerekli talepleri

S2S yolu (/observabilityService/...) - yalnızca uygulama belirteci:

Talep	Gerekli değer
`aud`	`9b975845-388f-4429-889e-eab1ef63949c` (veya `api://9b975845-...`)
`roles`	`Agent365.Observability.OtelWrite` içermesi gerekir
`appid` (v1) veya `azp` (v2)	URL `{agentId}` ile eşleşmesi gerekir
`scp`	Bulunmaması gerekir

Temsilci yolu (/observability/...) - kullanıcı tarafından delege edilen belirteç (Bearer veya PFAT):

Talep	Gerekli değer
`aud`	`9b975845-388f-4429-889e-eab1ef63949c` (veya `api://9b975845-...`)
`scp`	`Agent365.Observability.OtelWrite` içermesi gerekir
`appid` / `azp`	URL `{agentId}` ile eşleşmesi gerekir

Temsilci yolu hem Bearer hem de MSAuth1.0 PFAT belirteçlerini kabul eder. Doğrudan çağıranlar Bearer kullanmalıdır. Hangisine sahip olduğunuzu bilmiyorsanız Bearer kullanın.

Uç Noktalar

İki yol vardır; hizmetinizin nasıl kimlik doğrulaması yaptığına göre seçin, kullanıcının ne yaptığına göre değil:

POST https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1   # S2S
POST https://agent365.svc.cloud.microsoft/observability/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1          # OBO

Başlıklar:

Authorization: Bearer <token>      # or MSAuth1.0 ... for delegated PFAT
Content-Type: application/json

URL parametreleri

{tenantId} - müşteri kiracısı GUID'i. Sunucu bunu yetkili olarak değerlendirir; span'larınız microsoft.tenant.id ayarlarsa ve uyumsuzsa, istek reddedilir.
{agentId} - çağıran uygulamanın appId (aynı zamanda OAuth client_id). Blueprint'ten türetilen kimlikler için bu, blueprint appId değil aracı kimliği appId'dir. appid / azp talebine eşit olmalıdır belirtecinizdeki.
api-version=1 - gereklidir.

İstek gövdesi kodlaması

Gövde standart OTLP/HTTP+JSON şeklidir: ExportTraceServiceRequest ile resourceSpans → scopeSpans → spans. Aşağıdaki ayrıntıları göz önünde bulundurun:

traceId (16 bayt) ve spanId (8 bayt) küçük harfli onaltılı dizeler olarak gönderilir.
startTimeUnixNano / endTimeUnixNano Unix dönem nanosaniyelerini tutan dizelerdir.
kind tamsayı OTLP sabit listesi değeridir (örneğin 1 için INTERNAL); status.code tamsayı sabit listesidir (örneğin 1 için OK, 2 için ERROR).
Tüm öznitelik değerleri stringValue olarak gönderilir.

Yanıt yapısı

Başarılı bir çağrı 200 OK döndürür:

{ "partialSuccess": null }

Bazı yayılımlar başına-yayılım filtresi tarafından reddedildiyse:

{
  "partialSuccess": {
    "rejectedSpans": 2,
    "errorMessage": "Dropped 2 non-A365 span(s) ..."
  }
}

Alan adları kablo üzerinde camelCase'tir. Her zaman partialSuccess kontrol edin: tüm yayılımlarınız reddedilen bir 200, yüzleşmeniz gereken gerçek bir sonuçtur. Sınırlar ve bırakma koşulları veri aşağı akışta görünmesine rağmen 200'ün partialSuccess: null ile döndüğü sessiz bırakma durumlarını listeler.

Mümkün olan en küçük istek

En basit uçtan uca test, tek bir invoke_agent yayılımı gönderir. Bu yayılım, Microsoft Defender'a inen en küçük gövdedir.

1. Adım Bir Bearer jetonu alın. S2S için, 9b975845-388f-4429-889e-eab1ef63949c/.default kapsamı ile istemci kimlik bilgilerini kullanın (tam tarif için Kimlik Doğrulama tarifleri bölümüne bakın).

2. Adım Tek bir aralığı POST edin:

TOKEN="$(./get-token.sh)"
TENANT_ID="<customer-tenant-guid>"
AGENT_ID="<your-agent-app-id>"

curl -i -X POST \
  "https://agent365.svc.cloud.microsoft/observabilityService/tenants/${TENANT_ID}/otlp/agents/${AGENT_ID}/traces?api-version=1" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  --data @- <<EOF
{
  "resourceSpans": [{
    "scopeSpans": [{
      "scope": { "name": "my-instrumentation", "version": "1.0.0" },
      "spans": [{
        "traceId": "0102030405060708090a0b0c0d0e0f10",
        "spanId":  "1111111111111111",
        "parentSpanId": "",
        "name": "invoke_agent",
        "kind": 1,
        "startTimeUnixNano": "1736175600000000000",
        "endTimeUnixNano":   "1736175601500000000",
        "status": { "code": 1 },
        "attributes": [
          { "key": "gen_ai.operation.name", "value": { "stringValue": "invoke_agent" } },
          { "key": "gen_ai.agent.id",       "value": { "stringValue": "${AGENT_ID}" } },
          { "key": "gen_ai.agent.name",     "value": { "stringValue": "MyAgent" } },
          { "key": "microsoft.a365.agent.blueprint.id", "value": { "stringValue": "${AGENT_ID}" } },
          { "key": "gen_ai.conversation.id","value": { "stringValue": "conv-001" } },
          { "key": "microsoft.channel.name","value": { "stringValue": "web" } },
          { "key": "user.id",               "value": { "stringValue": "<entra-user-objectid>" } },
          { "key": "client.address",        "value": { "stringValue": "10.1.2.80" } },
          { "key": "server.address",        "value": { "stringValue": "myagent.example.com" } },
          { "key": "server.port",           "value": { "stringValue": "443" } },
          { "key": "gen_ai.input.messages", "value": { "stringValue": "[{\"role\":\"user\",\"content\":\"hi\"}]" } },
          { "key": "gen_ai.output.messages","value": { "stringValue": "[{\"role\":\"assistant\",\"content\":\"hello\"}]" } }
        ]
      }]
    }]
  }]
}
EOF

3. Adım Bu gövde ile 200 OK döndürmesini bekleyin:

{ "partialSuccess": null }

4. Adım. Verilerin gerçekten ulaştığını doğrulayın. 200 OK, alım kanıtı değildir; Alım Doğrulaması doğrulama akışını açıklar. Kaydedilmiş bir gövde dosyasını POST etmek için --data @- <<EOF ... EOF yerine --data @./otlp-request.json kullanın.

Aracı çalıştırma örneği

Microsoft Teams'deki bir kullanıcı "Seattle'da hava nasıl?" sorusunu soruyor. Aracınız bir GetWeather işlevini çağırır, bir LLM'den yanıtı biçimlendirmesini ister ve yanıtını gönderir. Bu tek çalıştırma dört aralığa sahiptir:

graph TD
    A["<b>invoke_agent</b> · spanId=A · parentSpanId=∅<br/><i>root - the run itself</i>"]
    B["<b>chat</b> · spanId=B · parentSpanId=A<br/><i>LLM picks the tool / formats reply</i>"]
    C["<b>execute_tool</b> · spanId=C · parentSpanId=A<br/><i>the GetWeather call</i>"]
    D["<b>output_messages</b> · spanId=D · parentSpanId=A<br/><i>final reply emitted to the user</i>"]
    A --> B
    A --> C
    A --> D

her aralığında ayarlanan çalıştırma genelinde öznitelikler:

Öznitelik	Örnek değer
`traceId`	`0102030405060708090a0b0c0d0e0f10`
`gen_ai.conversation.id`	`19:abc@thread.tacv2`
`microsoft.session.id`	`session-1234`
`microsoft.channel.name`	`msteams`
`gen_ai.agent.id`	`<AGENT_APP_ID>`
`gen_ai.agent.name`	`WeatherBot`
`microsoft.a365.agent.blueprint.id`	`<BLUEPRINT_APP_ID>`
`user.id`	`<entra-user-objectid>`
`client.address`	`10.1.2.80`
`server.address`	`weatherbot.example.com`
`server.port`	`443`

Önemli

Bu çalıştırma genelinde öznitelikler otomatik olarak yayılmaz. gen_ai.conversation.id, microsoft.channel.name ve microsoft.session.id özniteliklerini her aralığa kendiniz ayarlamanız gerekir.

Aralık A: `invoke_agent` (kök)

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "1111111111111111",
  "parentSpanId": "",
  "name": "invoke_agent",
  "kind": 1,
  "startTimeUnixNano": "1736175600000000000",
  "endTimeUnixNano":   "1736175601500000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",   "value": { "stringValue": "invoke_agent" } },
    { "key": "gen_ai.execution.type",   "value": { "stringValue": "HumanToAgent" } },
    { "key": "gen_ai.input.messages",   "value": { "stringValue": "[{\"role\":\"user\",\"content\":\"What's the weather in Seattle?\"}]" } },
    { "key": "gen_ai.output.messages",  "value": { "stringValue": "[{\"role\":\"assistant\",\"content\":\"It's 65F and partly cloudy in Seattle.\"}]" } },
    { "key": "user.email",              "value": { "stringValue": "alice@contoso.com" } }
    /* plus all the run-wide attributes listed above */
  ]
}

Aralık B: `chat` (LLM çağrısı)

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "2222222222222222",
  "parentSpanId": "1111111111111111",
  "name": "chat",
  "kind": 1,
  "startTimeUnixNano": "1736175600200000000",
  "endTimeUnixNano":   "1736175600900000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",      "value": { "stringValue": "chat" } },
    { "key": "gen_ai.request.model",       "value": { "stringValue": "gpt-4o" } },
    { "key": "gen_ai.provider.name",       "value": { "stringValue": "openai" } },
    { "key": "gen_ai.usage.input_tokens",  "value": { "stringValue": "42" } },
    { "key": "gen_ai.usage.output_tokens", "value": { "stringValue": "23" } }
    /* plus all the run-wide attributes */
  ]
}

Span C: `execute_tool`

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "3333333333333333",
  "parentSpanId": "1111111111111111",
  "name": "execute_tool",
  "kind": 1,
  "startTimeUnixNano": "1736175600950000000",
  "endTimeUnixNano":   "1736175601200000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",      "value": { "stringValue": "execute_tool" } },
    { "key": "gen_ai.tool.name",           "value": { "stringValue": "GetWeather" } },
    { "key": "gen_ai.tool.type",           "value": { "stringValue": "function" } },
    { "key": "gen_ai.tool.call.id",        "value": { "stringValue": "call-001" } },
    { "key": "gen_ai.tool.call.arguments", "value": { "stringValue": "{\"location\":\"Seattle\"}" } },
    { "key": "gen_ai.tool.call.result",    "value": { "stringValue": "{\"tempF\":65,\"condition\":\"partly cloudy\"}" } }
    /* plus all the run-wide attributes */
  ]
}

Span D: `output_messages`

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "4444444444444444",
  "parentSpanId": "1111111111111111",
  "name": "output_messages",
  "kind": 1,
  "startTimeUnixNano": "1736175601400000000",
  "endTimeUnixNano":   "1736175601500000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",  "value": { "stringValue": "output_messages" } },
    { "key": "gen_ai.output.messages", "value": { "stringValue": "[{\"role\":\"assistant\",\"content\":\"It's 65F and partly cloudy in Seattle.\"}]" } }
    /* plus all the run-wide attributes */
  ]
}

Telemetri gönderme

OTel SDK kullanma

Çoğu iş ortağı, el ile yazılan HTTP yerine bir OTel SDK aracılığıyla izleri gönderir. SDK, toplu işleme, yeniden deneme ve OTLP/HTTP+JSON kodlamasını sizin için yönetir. Authorization başlığını ayarlayın ve aktarıcı uç noktasını ekleyin.

Aktarıcı uç noktası, sorgu dizesini de içeren rota URL'sidir:

https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1

(Devredilen rota için /observabilityService/... yerine /observability/... kullanın.)

Python

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1",
    headers={"Authorization": f"Bearer {token}"},
)

Paket: opentelemetry-exporter-otlp-proto-http.

Node.js / TypeScript

import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";

const exporter = new OTLPTraceExporter({
  url: "https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1",
  headers: { Authorization: `Bearer ${token}` },
});

Paket: @opentelemetry/exporter-trace-otlp-http.

.NET

using OpenTelemetry.Exporter;

services.AddOpenTelemetry().WithTracing(b => b
    .AddOtlpExporter(o =>
    {
        o.Endpoint = new Uri("https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1");
        o.Headers = $"Authorization=Bearer {token}";
        o.Protocol = OtlpExportProtocol.HttpJson;
    }));

Paket: OpenTelemetry.Exporter.OpenTelemetryProtocol.

El ile HTTP

Bir OTel SDK kullanamıyor veya kullanmak istemiyorsanız, OTLP/HTTP+JSON isteğini kendiniz oluşturun ve POST yapın. Gövde şekli, OpenTelemetry OTLP/HTTP+JSON belirtimi tarafından tanımlanır:

{
  "resourceSpans": [{
    "resource":  { "attributes": [ ... ] },          // optional
    "scopeSpans": [{
      "scope":  { "name": "<your-instrumentation>", "version": "1.0.0" },
      "spans":  [ <span>, <span>, ... ]
    }]
  }]
}

Her <span>, gerekli alanları traceId, spanId, name, kind, startTimeUnixNano, endTimeUnixNano, attributes ve (kök olmayan yayılımlar için) parentSpanId olan bir nesnedir. Kodlama kuralları için Uç Noktalar ve İstek gövdesi kodlaması bölümüne bakın (dize kodlamalı saatler, onaltılık traceId / spanId, tamsayı kind / status.code, tüm öznitelik değerleri stringValue olarak).

Her yayılıma ayarlanacak özniteliklerin kümesi, İleti Sözleşmeleri bölümünde tanımlanır. Tam öznitelik listesi için Öznitelik başvurusu bölümüne bakın. Başlıkta Bearer belirteci ve gövdede satır içi içerik bulunan uçtan uca çalışan bir örnek için Aracı çalıştırma örneği bölümüne başvurun.

Bir çalıştırmanın tüm aralıklarını tek bir POST gövdesinde (tercih edilen - bir istek, bir iz) veya birden çok POST'ta gönderebilirsiniz. Sunucu, çalıştırmayı traceId + parentSpanId + gen_ai.conversation.id öğelerinden yeniden oluşturur; bu nedenle her aralık her iki şekilde ilişkilendirilmek için yeterli bilgi taşır.

İleti Sözleşmeleri

Bu bölüm, hangi aralıkları yayabiliyorsunuz ve her birinin hangi öznitelikleri içerdiğini tanımlar. Tam öznitelik-öznitelik belirtimi için Öznitelik başvurusu bölümüne bakın.

İşlem türleri

Gönderdiğiniz her aralık, gen_ai.operation.name öğesinin şu dört değerden birine (büyük-küçük harfe duyarsız) ayarlanmış olması gerekir. Eksik veya tanınmayan değeri olan herhangi bir aralık sessizce bırakılır ve partialSuccess.rejectedSpans içinde sayılır.

`gen_ai.operation.name`	Anlamı	En Çok Aranan Sürpriz Sorunlar
`invoke_agent`	Bir aracının çağrılması. Bir aracı çalıştırmasının "kökü".	Çalıştırmanın Microsoft Defender aracı-etkinlik görünümlerinde veya Microsoft 365 yönetim merkezinde görünmesi için gereklidir. Bu olmadan, telemetri yalnızca Microsoft Defender gelişmiş avcılık (`CloudAppEvents`) hizmetinde yer alır.
`execute_tool`	Bir aracı tarafından gerçekleştirilen bir araç / işlev çağrısı.	--
`chat`	Bir LLM çıkarım çağrısı.	Sabit `chat` kullanın, `inference` KULLANMAYIN.
`output_messages`	Son yayımlanan çıkış iletisi.	--

Span hiyerarşisi ve çalıştırma gruplandırması

Agent 365, standart OTLP span grafiğinden (traceId, spanId, parentSpanId) ve Öznitelik başvurusundan alınan çalıştırma genelindeki özniteliklerden bir çalıştırmayı yeniden oluşturur.

Altı Kural:

Her kök olmayan span üzerinde parentSpanId ayarlayın. Bunu olmadan, çalıştırmanın ağaç yapısı yeniden oluşturulamaz.
Bir çalıştırmadaki her span genelinde aynı traceId öğesini yeniden kullanın.
Her span üzerinde aynı değerle gen_ai.conversation.id ayarlayın. Bu, "bu çalıştırmadaki tüm spanlar" için birincil birleştirme anahtarıdır. Otomatik olarak yayılmaz.
Her span üzerinde aynı değerle microsoft.channel.name ayarlayın. Kanal/konuşma eksik olan araç spanları, yalnızca üst öğe aynı OTLP isteğinde bulunuyorsa bunları üst öğeden invoke_agentdevralabilir, bu nedenle her span üzerinde bunları kendiniz ayarlayın.
Mantıksal bir oturumunuz olduğunda her span üzerinde microsoft.session.id ayarlayın.
Alt aracının ayrı bir istekte bulunduğu aracıdan aracıya çağrılar için aynı gen_ai.conversation.id öğesini yeniden kullanın ve arayan aracı bağlamını yakalamak için microsoft.a365.caller.agent.* özniteliklerini (Öznitelik başvurusuna bakın) kullanın.

Aracı çalıştırması örneğindeki dört span ağacı, kanonik şeklidir.

Yaygın çalıştırma şekilleri

Şekil	Yayımlanacak spanlar	Notlar
Tek aracılı sohbet botu (araçlar yok, LLM span yok)	Yalnızca bir `invoke_agent`	Çalışma genelindeki öznitelikleri artı `gen_ai.input.messages` ve `gen_ai.output.messages` ayarlayın. Mümkün olan en küçük istek ile aynı.
Araçları olan aracı (en yaygın)	`invoke_agent` kökü + `chat`, `execute_tool`, `output_messages` alt öğeleri	Tüm alt öğeler kökün `traceId` öğesini paylaşır ve `parentSpanId = root.spanId` ayarlayın. Tümü aynı çalışma genelindeki öznitelikleri taşır. Tam bir örnek için Aracı çalışma örneğine bakın.
Aracıdan Aracıya	Her aracı kendi `invoke_agent` değerini yayar.	Her iki aracı arasında aynı `gen_ai.conversation.id` yeniden kullanın. Hedefin `invoke_agent` üzerinde, `gen_ai.execution.type = "Agent2Agent"` ve `microsoft.a365.caller.agent.*` öznitelikleri ayarlayın (çağıran aracının `appId`, adı, şema `appId`, kullanıcı kimliği ve e-postası). Çağıran aracının Entra kaydı yoksa, bunun yerine `microsoft.a365.caller.agent.platform.id` ve `gen_ai.caller.agent.type` kullanın.

Katılım Kontrol Listesi

Üretime geçmeden önce bu denetim listesini gözden geçirin.

Kategori	Denetle
Kimlik Doğrulama	Entra uygulamanız (veya şemanız) kaydedilmiştir ve bunun için belirteç oluşturabilirsiniz.
Kimlik Doğrulama	Uygulamanıza `Agent365.Observability.OtelWrite` verilmiştir (S2S için uygulama rolü, yetkilendirilmiş için kapsam).
Kimlik Doğrulama	Her aracının kendi Entra appId değeri `{agentId}` olarak URL'de yer alır. Blueprint'ten türetilen kimlikler için bu appId, blueprint appId'si değil aracı kimliği appId'sidir. Aracının Entra kaydı yoksa, Değerleri Seçme bölümüne bakın.
Kimlik Doğrulama	Kiracı yöneticisi `Agent365.Observability.OtelWrite` için onay vermiştir. Onay olmadan, belirteçler rol/kapsam olmadan verilir ve istekler `403` ile reddedilir.
Lisanslama	Müşteri kiracısında en az bir kullanıcının Microsoft 365 E7 veya Microsoft Agent 365 lisansı atanmış olması gerekir (kiracıda SKU'nun bulunması değil, atama gereklidir). Atanan lisans olmadan, alım sessizce bırakılır. Ön koşullara bakın.
Span'ler	Her aralık çalışma çapında temel öğeleri ayarlar (Aralık hiyerarşisi ve çalışma gruplandırması).
Span'ler	`invoke_agent` aralıkları `gen_ai.input.messages` ve `gen_ai.output.messages` ayarlar.
Span'ler	`execute_tool` aralıkları `gen_ai.tool.name`, `gen_ai.tool.type`, `gen_ai.tool.call.id`, `gen_ai.tool.call.arguments`, `gen_ai.tool.call.result` ayarlar.
Span'ler	`chat` aralıkları `gen_ai.request.model` ve `gen_ai.provider.name` (ve ideal olarak `gen_ai.usage.input_tokens` / `gen_ai.usage.output_tokens` - dize kodlamalı) ayarlar.
Span'ler	Kök olmayan tüm aralıklar `parentSpanId` ayarlar; bir çalışmadaki tüm aralıklar aynı `traceId` paylaşır.
Yük	İstek gövdesi ≤ 1 MB'dir.
Doğrulama	Her yanıt için `partialSuccess` öğesini ayrıştırır ve reddetmeleri günlüğe kaydedersiniz.
Doğrulama	Alımı doğrulama iş akışını ilk çalıştırmalarınızda yaptınız.

Sonraki adımlar

Öznitelik başvurusu - Öznitelik başına belirtim ve değer seçme kılavuzu.
Sorun giderme - Alımı doğrulama, yaygın sorunlar ve hata yanıtları.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-07-30