Microsoft OpenTelemetry Distro

Microsoft OpenTelemetry Distro は、エージェントアプリケーションと非エージェントアプリケーションからトレース、メトリック、ログを収集するための単一のオンボードエクスペリエンスを提供する、統合された可観測性ディストリビューションです。 Microsoft Agent 365、Microsoft Foundry、Azure Monitor、および OpenTelemetry Protocol (OTLP) 互換バックエンドの可観測性がサポートされています。ディストリビューションは、.NET、Node.js、およびPythonをサポートし、複数の可観測スタック全体の断片化されたセットアップを 1 つのインポートと 1 つの構成呼び出しに置き換えます。

主な利点

Microsoft OpenTelemetry Distro には、次の利点があります。

1 つのパッケージ、1 つの API: 複数のエクスポーターパッケージとインストルメンテーションパッケージを 1 つの依存関係に置き換えます。
Multi-backend support: Azure Monitor、Datadog、Grafana、New Relic などの OpenTelemetry Protocol (OTLP) と互換性のあるエンドポイント、および Microsoft Agent 365 に同時にテレメトリを送信します。
組み込みインストルメンテーション: 追加の構成なしで、HTTP、データベース、Azure SDK、Azure Functionsなどの自動インストルメンテーションを使用します。
標準ベース: 業界標準の可観測フレームワークである OpenTelemetry に基づいて構築されます。
最小定型文: 1 つのインポートと 1 つの関数呼び出しをアプリケーションエントリポイントに追加します。

インストールとコンフィギュレーション

このガイダンスでは、Microsoft OpenTelemetry Distro を使用してアプリケーションに可観測性を追加する方法について説明します。 Distro は、組み込みのインストルメンテーションを使用してトレース、メトリック、ログを自動的に収集し、テレメトリを Azure Monitor、任意の OpenTelemetry Protocol (OTLP) エンドポイント、または Microsoft Agent 365 にエクスポートします。

ライブラリをインストールする

Microsoft OpenTelemetry Distro の使用を開始するには、言語のパッケージマネージャーを使用して、開発プラットフォームに適したライブラリをインストールします。

Prerequisites: Python 3.10 以降。

pip install microsoft-opentelemetry

前提条件: Node.js 18 以降。 ESM アプリには、Node.js 20.6.0 以降が必要です。

npm install @microsoft/opentelemetry

Important

インストルメンテーションでライブラリを読み込む前にパッチを適用できるように、できるだけ早くアプリケーションエントリポイントで useMicrosoftOpenTelemetry() を呼び出します。

ESM アプリの場合は、インストルメント化されたモジュールをインポートする前にインストルメンテーションフックを登録します。起動時に --import フラグを使用します。

node --import @microsoft/opentelemetry/loader ./dist/index.js

Microsoft.OpenTelemetry NuGet パッケージをインストールします。この 1 つのパッケージには、Agent 365 監視ランタイム、ホスティング統合、サポートされている AI フレームワークの自動インストルメンテーション、標準の OpenTelemetry ライブラリが含まれています。

<PackageReference Include="Microsoft.OpenTelemetry" />

または、.NET CLI を使用します。

dotnet add package Microsoft.OpenTelemetry

Note

パッケージがパブリック NuGet フィードで使用できない場合は、プロジェクトルートに nuget.config ファイルを追加します。フィードの構成については、.NET リポジトリ README を参照してください。

コンフィギュレーション

エージェント 365 エクスポーターは接続文字列を使用しません。テナントに基づいてエンドポイントが自動的に検出されます。エージェント 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()に渡すことで、エクスポーターの動作をカスタマイズできます。

Parameter	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`

トークンキャッシュを自動的に処理するには、ObservabilityManagerでAgenticTokenCacheInstanceを使用します。

import { useMicrosoftOpenTelemetry, AgenticTokenCacheInstance } from '@microsoft/opentelemetry';
import { resourceFromAttributes } from '@opentelemetry/resources';

useMicrosoftOpenTelemetry({
  resource: resourceFromAttributes({
    'service.name': 'Default Token Cache Sample',
    'service.version': '1.0.0',
  }),
  azureMonitor: {
    enabled: Boolean(process.env.APPLICATIONINSIGHTS_CONNECTION_STRING),
  },
  instrumentationOptions: {
    http: { enabled: false },
  },
  a365: {
    enabled: process.env.ENABLE_A365_OBSERVABILITY_EXPORTER !== 'false',
    tokenResolver: (agentId, tenantId) =>
      AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId) ?? '',
  },
});

(既定のトークンリゾルバーではなく) カスタムトークン解決については、「手動トークンリゾルバー」を参照してください。

a365 オブジェクトにオプションのプロパティを設定することで、エクスポーターの動作をカスタマイズできます。

財産	Description	デフォルト
`useS2SEndpoint`	`true`場合は、サービス間エンドポイントパスを使用します。	`false`
`maxQueueSize`	バッチプロセッサの最大キューサイズ。	`2048`
`scheduledDelayMilliseconds`	エクスポートバッチ間の遅延 (ミリ秒単位)。	`5000`
`exporterTimeoutMilliseconds`	エクスポート操作全体のタイムアウト (ミリ秒単位)。	`90000`
`httpRequestTimeoutMilliseconds`	バックエンドへの個々の HTTP 要求のタイムアウト (ミリ秒)。	`30000`
`maxExportBatchSize`	エクスポート操作の最大バッチサイズ。	`512`

完全な構成オプションと環境変数については、 JavaScript リポジトリ README を参照してください。

Program.csで、UseMicrosoftOpenTelemetry()を呼び出して監視を有効にします。 ExportTargetは、テレメトリが送信される場所を列挙コントロールにフラグ付けします。ターゲットと|を組み合わせます (たとえば、ExportTarget.Console | ExportTarget.Agent365)。

自動 (DI) トークンキャッシュ (Agent Framework アプリに推奨):

TokenResolverを設定しない場合、ディストリビューションは DI 経由でIExporterTokenCache<AgenticTokenStruct>を自動的に登録します。エージェントは実行時に RegisterObservability() を呼び出して資格情報を提供し、キャッシュはトークンの取得と更新を処理します。

// Program.cs — no TokenResolver needed
builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365;
    // TokenResolver is auto-registered via the agentic token cache in DI, with required imports in the next code snippet.
});

using Microsoft.Agents.A365.Observability.Hosting.Caching;
using Microsoft.Agents.A365.Observability.Runtime.Common;

// In your agent class
public class MyAgent : AgentApplication
{
    private readonly IExporterTokenCache<AgenticTokenStruct> _agentTokenCache;

    public MyAgent(AgentApplicationOptions options,
        IExporterTokenCache<AgenticTokenStruct> agentTokenCache) : base(options)
    {
        _agentTokenCache = agentTokenCache;
    }

    protected async Task MessageActivityAsync(
        ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        _agentTokenCache.RegisterObservability(
            turnContext.Activity.Recipient.AgenticAppId,
            turnContext.Activity.Recipient.TenantId,
            new AgenticTokenStruct(
                userAuthorization: UserAuthorization,
                turnContext: turnContext,
                authHandlerName: "AGENTIC"),
            EnvironmentUtils.GetObservabilityAuthenticationScope());
    }
}

(既定のトークンリゾルバーではなく) カスタムトークン解決については、「手動トークンリゾルバー」を参照してください。

o.Agent365.Exporterにオプションのプロパティを設定することで、エクスポーターの動作をカスタマイズできます。

財産	Description	デフォルト
`UseS2SEndpoint`	`true`場合は、サービス間エンドポイントパスを使用します。	`false`
`MaxQueueSize`	バッチプロセッサの最大キューサイズ。	`2048`
`ScheduledDelayMilliseconds`	エクスポートバッチ間の遅延 (ミリ秒単位)。	`5000`
`ExporterTimeoutMilliseconds`	エクスポート操作のタイムアウト (ミリ秒単位)。	`30000`
`MaxExportBatchSize`	エクスポート操作の最大バッチサイズ。	`512`

Note

ENABLE_A365_OBSERVABILITY_EXPORTER は、Pythonと JavaScript の概念です。 .NETでは、Agent 365 エクスポーターは、ExportTarget.Agent365 を介してコード内で完全に制御されます。

コンテキストの伝達

分散エージェント 365 操作全体で可観測性を維持するには、コンテキストを伝達する必要があります。エージェントとサービスを介してコンテキストを伝達する場合は、要求ライフサイクル全体にわたってトレース、ログ、メトリックが適切に関連付けられていることを確認します。この相関関係は、エージェント 365 の監視エクスペリエンスを完全かつ効果的にMicrosoftするために必要です。

バゲッジ属性

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

import { BaggageBuilder, InvokeAgentScope, ExecuteToolScope } from '@microsoft/opentelemetry';

// Create and apply baggage context
const baggageScope = new BaggageBuilder()
  // Core identifiers
  .tenantId('tenant-123')
  .agentId('agent-456')
  .conversationId('conv-789')
  .build();

// Execute operations within the baggage context
baggageScope.run(() => {
  // All spans created within this context will inherit the baggage values

  // Invoke another agent
  const agentScope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
  // ... agent logic

  // Execute tools
  const toolScope = ExecuteToolScope.start(request, toolDetails, agentDetails);
  // ... tool logic
});

BaggageBuilderからTurnContextを自動的に設定するには、fromTurnContext パッケージの@microsoft/opentelemetry ヘルパーを使用します。このヘルパーは、アクティビティから呼び出し元、エージェント、テナント、チャネル、会話の詳細を自動的に抽出します。

import { BaggageBuilder, BaggageBuilderUtils } from '@microsoft/opentelemetry';

const baggageScope = BaggageBuilderUtils.fromTurnContext(new BaggageBuilder(), context)
  .invokeAgentServer(context.activity.serviceUrl, 3978)
  .build();

baggageScope.run(() => {
  // Baggage is auto-populated from the TurnContext activity
});

using Microsoft.Agents.A365.Observability.Runtime.Common;

using var baggageScope = new BaggageBuilder()
    .TenantId("tenant-123")
    .AgentId("agent-456")
    .ConversationId("conv-789")
    .Build();
// Any spans started in this context will receive them as attributes.

BaggageBuilder から ITurnContext を自動設定するには、FromTurnContext パッケージの Microsoft.Agents.A365.Observability.Hosting 拡張メソッドを使用します。このメソッドは、アクティビティから呼び出し元、エージェント、テナント、チャネル、および会話の詳細を自動的に抽出します。

using Microsoft.Agents.A365.Observability.Runtime.Common;
using Microsoft.Agents.A365.Observability.Hosting.Extensions;

using var baggageScope = new BaggageBuilder()
    .FromTurnContext(turnContext)
    .Build();

手荷物ミドルウェア

エージェントがホスティング統合パッケージを使用している場合は、手荷物ミドルウェアを登録して、すべての着信要求に対して自動的に手荷物を設定します。この手順により、各アクティビティハンドラーで BaggageBuilder を手動で呼び出す必要がなくなります。

Pythonでは、アダプターに直接ではなく、ObservabilityHostingManager.configure() 経由で手荷物ミドルウェアを登録します。

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

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

ミドルウェアは、非同期応答 (ContinueConversation イベント) の手荷物設定をスキップして、元の要求が既に設定した手荷物を上書きしないようにします。

アダプターに BaggageMiddleware を登録します。すべての着信 TurnContext から呼び出し元、エージェント、テナント、チャネル、および会話の詳細が自動的に抽出され、要求が手荷物スコープにラップされます。

import { BaggageMiddleware } from '@microsoft/opentelemetry';

// Option 1: Register middleware directly on the adapter
adapter.use(new BaggageMiddleware());

または、 ObservabilityHostingManager を使用して、手荷物ミドルウェアとその他のホスティング機能を構成します。

import { ObservabilityHostingManager } from '@microsoft/opentelemetry';

const manager = new ObservabilityHostingManager();
manager.configure(adapter, { enableBaggage: true });

アダプターに BaggageTurnMiddleware を登録します。すべての着信 ITurnContext から呼び出し元、エージェント、テナント、チャネル、および会話の詳細が自動的に抽出され、要求が手荷物スコープにラップされます。

using Microsoft.Agents.A365.Observability.Hosting.Middleware;

adapter.Use(new BaggageTurnMiddleware());

HTTP レベルの手荷物 (たとえば、Bot Framework パイプラインの実行前にテナント ID とエージェント ID を設定する) が必要な場合は、ObservabilityBaggageMiddleware 拡張メソッドを使用して、ASP.NET Core パイプラインに UseObservabilityRequestContext を登録します。 HTTP コンテキストからテナント ID とエージェント ID を抽出するリゾルバー関数を指定する必要があります。

using Microsoft.Agents.A365.Observability.Hosting.Middleware;

app.UseObservabilityRequestContext((httpContext) =>
{
    // Extract tenant and agent IDs from your request context
    var tenantId = GetTenantIdFromContext(httpContext);
    var agentId = GetAgentIdFromContext(httpContext);
    return (tenantId, agentId);
});

製品でデータが流れているかどうかを検証する

Microsoft PurviewまたはMicrosoft Defenderでエージェントテレメトリを表示するには、次の要件が満たされていることを確認します。

Microsoft Purview: 組織の監査を有効にする必要があります。手順については、「監査のオンとオフを切り替える」を参照してください。
Microsoft Defender: CloudAppEvents テーブルにアクセスするために、高度なハンティングを設定する必要があります。詳細については、高度なハンティングスキーマの CloudAppEvents テーブルを参照してください。

自動インストルメンテーション

Microsoft OpenTelemetry Distro は、標準の OpenTelemetry パイプラインとMicrosoftキュレーションされたインストルメンテーションを組み合わせています。 Distro では、言語と構成に応じて、アプリケーションテレメトリ、インフラストラクチャテレメトリ、エージェントまたは生成 AI テレメトリを収集できます。

カテゴリ	内容
シグナルパイプライン	トレース、メトリック、およびログ。
リソース検出	サポートされているサービス、ホスト、クラウド、Azureランタイムコンテキスト。
インフラストラクチャのインストルメンテーション	サポートされている HTTP、ASP.NET Core、Azure SDK、データベースクライアント、およびログ記録フレームワーク。
生成 AI インストルメンテーション	OpenAI、Azure OpenAI、Semantic Kernel、LangChain、OpenAI Agents SDK、およびエージェントフレームワーク (サポートされている場合)。
エージェントのスコープ（手動）	エージェントの呼び出し、ツールの実行、推論、および出力テレメトリ (サポートされている場合)。
エクスポーターとプロセッサ	Azure Monitor、Microsoft Agent 365、OTLP、コンソール出力、スパンプロセッサ、ログプロセッサ、メトリックリーダー。

インストルメントカバレッジ

Language	一般的なアプリケーションインストルメンテーション	一般的なエージェントと生成型 AI インストルメンテーション
Python	OpenTelemetry リソース、プロセッサ、リーダー、ログ、メトリック、トレース。	Semantic Kernel、OpenAI Agents SDK、Agent Framework、LangChain、Microsoft Agent 365 Baggage、Microsoft Agent 365 Scopes。
Node.js	HTTP、Azure SDK、Azure Functions、MongoDB、MySQL、PostgreSQL、Redis、Bunyan、Winston。	OpenAI Agents SDK、LangChain、Microsoft Agent 365 の手荷物、Microsoft Agent 365 のスコープ。
.NET	ASP.NET Core、HttpClient、SQL クライアント、Azure SDK、リソース検出、メトリック、ログ。	Semantic Kernel、OpenAI、Azure OpenAI、Agent Framework、Microsoft Agent 365 のバゲージ、Microsoft Agent 365 のスコープ。

自動インストルメンテーションは、サポートされているライブラリとフレームワークによって出力されたテレメトリ信号をリッスンします。手動インストルメンテーションは、呼び出し、ツールの実行、推論、非同期出力などのエージェント固有の操作をアプリケーションで記述する必要がある場合に使用されます。

組み込みのインストルメンテーションでカバーされていないテレメトリをアプリケーションが出力するときに、カスタムの OpenTelemetry ソース、メーター、プロセッサ、またはリーダーを追加します。

組み込みのインストルメンテーションライブラリ

自動インストルメンテーションは、サポートされているフレームワークによって出力されたテレメトリをリッスンし、Distro の OpenTelemetry パイプラインを介して転送します。エージェントのシナリオでは、インストルメント化されたフレームワークがスパンを作成する前に、テナント ID やエージェント ID などの手荷物を設定します。

フレームワーク	Python	Node.js	.NET
セマンティックカーネル	サポートされている	サポートしていません	サポートされている
OpenAI および OpenAI Agents SDK	サポートされている	サポートされている	サポートされている
エージェントフレームワーク	サポートされている	サポートしていません	サポートされている
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},
    },
)

Semantic Kernelインストルメンテーションは既定で有効になっています。これを無効にするには、インストルメンテーションオプションを明示的に設定します。

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Instrumentation.EnableSemanticKernelInstrumentation = false;
});

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

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";

const tokenResolver = (agentId, tenantId) => {
  return "your-token";
};

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver,
  },
  instrumentationOptions: {
    openaiAgents: { enabled: true },
  },
});

OpenAI および Azure OpenAI インストルメンテーションは、既定で有効になっています。これを無効にするには、インストルメンテーションオプションを明示的に設定します。

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Instrumentation.EnableOpenAIInstrumentation = false;
});

エージェントフレームワーク

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

Agent Framework インストルメンテーションは既定で有効になっています。これを無効にするには、インストルメンテーションオプションを明示的に設定します。

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Instrumentation.EnableAgentFrameworkInstrumentation = false;
});

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

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";

const tokenResolver = (agentId, tenantId) => {
  return "your-token";
};

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver,
  },
  instrumentationOptions: {
    langchain: { enabled: true },
  },
});

手動インストルメンテーション

自動インストルメンテーションでエージェント操作が十分に詳細に記述されていない場合は、手動インストルメンテーションを使用します。手動スコープを使用すると、アプリケーションは言語間で一貫した方法で一般的なエージェントアクティビティを記述できます。

Scope	使用対象
`InvokeAgentScope`	エージェント呼び出しの開始と完了。
`ExecuteToolScope`	エージェントによって行われたツール呼び出し。
`InferenceScope`	AI モデルの推論操作。
`OutputScope`	元のスコープが完了した後に必ず記録する必要がある出力。

関連するテレメトリを関連付けることができるように、要求内のスコープ間で同じ要求とエージェント ID 値を再利用します。

エージェント呼び出し

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

import { InvokeAgentScope } from "@microsoft/opentelemetry";
import type {
  AgentDetails,
  A365Request,
  InvokeAgentScopeDetails,
} from "@microsoft/opentelemetry";

const agentDetails: AgentDetails = {
  agentId: "agent-456",
  agentName: "Email Assistant",
  agentDescription: "An AI agent powered by Azure OpenAI",
  agentAUID: "auid-123",
  agentEmail: "agent@contoso.com",
  agentBlueprintId: "blueprint-789",
  tenantId: "tenant-123",
};

const request: A365Request = {
  content: "Please help me organize my emails",
  sessionId: "session-42",
  conversationId: "conv-xyz",
  channel: { name: "msteams" },
};

const scopeDetails: InvokeAgentScopeDetails = {
  endpoint: { host: "myagent.contoso.com", port: 443 },
};

const invokeScope = InvokeAgentScope.start(request, scopeDetails, agentDetails);

try {
  await invokeScope.withActiveSpanAsync(async () => {
    invokeScope.recordInputMessages(["Please help me organize my emails"]);

    // Run the agent invocation.

    invokeScope.recordOutputMessages(["I found 15 urgent emails."]);
  });
} catch (error) {
  invokeScope.recordError(error as Error);
  throw error;
} finally {
  invokeScope.dispose();
}

using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

var agentDetails = new AgentDetails(
    agentId: "agent-456",
    agentName: "Email Assistant",
    agentDescription: "An AI agent powered by Azure OpenAI",
    agenticUserId: "auid-123",
    agenticUserEmail: "agent@contoso.com",
    agentBlueprintId: "blueprint-789",
    tenantId: "tenant-123");

var request = new Request(
    content: "Please help me organize my emails",
    sessionId: "session-42",
    conversationId: "conv-xyz",
    channel: new Channel(name: "msteams"));

var scopeDetails = new InvokeAgentScopeDetails(
    endpoint: new Uri("https://myagent.contoso.com"));

using var invokeScope = InvokeAgentScope.Start(
    request: request,
    scopeDetails: scopeDetails,
    agentDetails: agentDetails);

invokeScope.RecordInputMessages(new[] { "Please help me organize my emails" });

// Run the agent invocation.

invokeScope.RecordOutputMessages(new[] { "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)

import { ExecuteToolScope } from "@microsoft/opentelemetry";
import type { ToolCallDetails } from "@microsoft/opentelemetry";

const toolDetails: ToolCallDetails = {
  toolName: "email-search",
  arguments: JSON.stringify({ query: "from:manager@contoso.com" }),
  toolCallId: "tool-call-456",
  description: "Search emails by criteria",
  toolType: "function",
  endpoint: {
    host: "tools.contoso.com",
    port: 8080,
    protocol: "https",
  },
};

const scope = ExecuteToolScope.start(request, toolDetails, agentDetails);

try {
  await invokeScope.withActiveSpanAsync(async () => {
    const result = await searchEmails(toolDetails.arguments);
    scope.recordResponse(JSON.stringify(result));
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

var toolDetails = new ToolCallDetails(
    toolName: "email-search",
    arguments: "{\"query\": \"from:manager@contoso.com\"}",
    toolCallId: "tool-call-456",
    description: "Search emails by criteria",
    toolType: "function",
    endpoint: new Uri("https://tools.contoso.com:8080"));

using var scope = ExecuteToolScope.Start(
    request: request,
    details: toolDetails,
    agentDetails: agentDetails);

// Execute the tool.

scope.RecordResponse("{\"count\": 15}");

推論

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

import { InferenceOperationType, InferenceScope } from "@microsoft/opentelemetry";
import type { InferenceDetails } from "@microsoft/opentelemetry";

const inferenceDetails: InferenceDetails = {
  operationName: InferenceOperationType.CHAT,
  model: "gpt-4o-mini",
  providerName: "azure-openai",
};

const scope = InferenceScope.start(request, inferenceDetails, agentDetails);

try {
  await invokeScope.withActiveSpanAsync(async () => {
    scope.recordInputMessages(["Summarize the following emails for me."]);
    const response = await callLLM();
    scope.recordOutputMessages([response.text]);
    scope.recordInputTokens(response.usage.inputTokens);
    scope.recordOutputTokens(response.usage.outputTokens);
    scope.recordFinishReasons(["stop"]);
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

var inferenceDetails = new InferenceCallDetails(
    operationName: InferenceOperationType.Chat,
    model: "gpt-4o-mini",
    providerName: "Azure OpenAI");

using var scope = InferenceScope.Start(
    request: request,
    details: inferenceDetails,
    agentDetails: agentDetails);

scope.RecordInputMessages(new[] { "Summarize the following emails for me." });

// Call the model.

scope.RecordOutputMessages(new[] { "Here is your email summary." });
scope.RecordInputTokens(145);
scope.RecordOutputTokens(82);
scope.RecordFinishReasons(new[] { "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

import { OutputScope } from "@microsoft/opentelemetry";
import type { A365SpanDetails, OutputResponse } from "@microsoft/opentelemetry";

// Capture this before disposing the originating InvokeAgentScope.
const parentContext = invokeScope.getSpanContext();
const response: OutputResponse = {
  messages: ["Here is your organized inbox."],
};

const scope = OutputScope.start(
  request,
  response,
  agentDetails,
  undefined,
  { parentContext } as A365SpanDetails
);

scope.dispose();

// Capture this before disposing the originating InvokeAgentScope.
var parentContext = invokeScope.GetActivityContext();
var response = new Response(new[] { "Here is your organized inbox." });

using var scope = OutputScope.Start(
    request: request,
    response: response,
    agentDetails: agentDetails,
    spanDetails: new SpanDetails(parentContext: parentContext));

製品ドキュメントでは、これらのスコープの製品固有の検証要件を定義する必要があります。

ローカル検証

ローカル検証では、製品固有の宛先が検証される前に、アプリケーションによってテレメトリが生成されることを確認します。コンソール出力またはローカル OTLP エンドポイントを使用して、トレース、メトリック、およびログが作成されていることを確認します。

ローカル OTLP エンドポイントを使用して検証する

ローカルコレクターまたは別の OTLP 互換エンドポイントにテレメトリを送信するように Distro を構成します。

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";

useMicrosoftOpenTelemetry();

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Otlp;
    o.OtlpEndpoint = new Uri("http://localhost:4317");
});

ローカル出力を使用して検証する

リモートの宛先にテレメトリを送信する前にインストルメンテーションを確認する場合は、ローカル出力を使用します。

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.

export ENABLE_A365_OBSERVABILITY_EXPORTER=false

import {
  useMicrosoftOpenTelemetry,
  shutdownMicrosoftOpenTelemetry,
} from "@microsoft/opentelemetry";

const tokenResolver = (agentId, tenantId) => {
  return "local-validation-token";
};

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver,
  },
});

// Run instrumented application code.

await shutdownMicrosoftOpenTelemetry();

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Console;
});

HTTP 要求、OpenAI または Azure OpenAI 呼び出し、エージェント呼び出しスコープ、ツール実行スコープ、推論スコープなど、予想されるソースからのスパンのローカル出力を確認します。宛先固有の検証は、その宛先の製品ドキュメントに属しています。

認証を手動で設定する

エージェント 365 エクスポーターを使用する場合は、認証トークンを提供するメカニズムを提供する必要があります。トークンリゾルバーは、アクティブな手荷物コンテキストのエージェント ID とテナント ID を使用して、エクスポートバッチごとに機能します。ディストリビューションでは、3 つの方法がサポートされています。

手動トークンリゾルバー

Agent Framework パイプラインの外部でトークンを取得する場合、またはエージェントフレームワーク以外のアプリをビルドする場合は、手動リゾルバーを使用します。

リゾルバーは同期である必要があります。非同期アクティビティハンドラーでトークンを取得し、リゾルバー用にキャッシュします。

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

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";
import { TurnState, AgentApplication, TurnContext, MemoryStorage } from '@microsoft/agents-hosting';
import { ActivityTypes } from '@microsoft/agents-activity';

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver: (agentId: string, tenantId: string, authScopes?: string[]) =>
      myTokenService.getToken(agentId, tenantId),
  },
});


export class A365Agent extends AgentApplication<TurnState> {
  isApplicationInstalled: boolean = true;
  termsAndConditionsAccepted: boolean = true;
  agentName = 'A365 Agent';
  authHandlerName = 'agentic';
 
  constructor() {
    const useAgenticAuth = process.env.USE_AGENTIC_AUTH === 'true';

    super({
      storage: new MemoryStorage(),
      ...(useAgenticAuth && {
        authorization: {
          agentic: {
            type: 'agentic',
          }
        }
      })
    });

    this.onActivity(ActivityTypes.Message, async (context: TurnContext, state: TurnState) => {
      await this.handleAgentMessageActivity(context, state);
    });
  }

  async handleAgentMessageActivity(turnContext: TurnContext, _state: TurnState): Promise<void> {
    if (process.env.USE_AGENTIC_AUTH !== 'true') {
      console.log('[A365Agent] Authorization not configured, skipping observability token preload');
      return;
    }

    const agentId = turnContext?.activity?.recipient?.agenticAppId ?? '';
    const tenantId = turnContext?.activity?.recipient?.tenantId ?? '';

    // Acquire auth token via OBO exchange
    const authToken = await this.authorization.exchangeToken(turnContext, 'agentic', {
      scopes: ['api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite']
    });

    // Cache the token so it can be returned by the token resolver
    myTokenService.set(agentId, tenantId, authToken?.token || '');
  }
}

using Microsoft.OpenTelemetry;

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365;
    o.Agent365.Exporter.TokenResolver = async (agentId, tenantId) =>
    {
        return await MyTokenService.GetTokenAsync(agentId, tenantId);
    };
});

TokenResolver明示的に設定すると、自動 DI トークンキャッシュは登録されません。リゾルバーが代わりに使用されます。

エージェントフレームワークアプリでのエージェンティックトークンキャッシュ

Agent Framework アプリの場合、カスタム IExporterTokenCache<AgenticTokenStruct>を設定しない場合、ディストリビューションは DI 経由でTokenResolverを自動的に登録します。エージェントは実行時に RegisterObservability() を呼び出して資格情報を提供し、キャッシュはトークンの取得と更新を処理します。

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

configureA365Hostingを使用して、A365 ミドルウェアをアダプターに登録します。このミドルウェアは、手荷物とトークンの配管を自動的に処理します。

import { configureA365Hosting } from "@microsoft/opentelemetry";

configureA365Hosting(adapter, {
  enableBaggage: true,
  enableOutputLogging: false,
});

応答コンテンツをスパン属性としてキャプチャしない場合は、 enableOutputLogging: false を設定します。

// Program.cs — no TokenResolver needed
builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365;
    // IExporterTokenCache<AgenticTokenStruct> is auto-registered via DI
});

エージェントクラスで、ターンごとに RegisterObservability() を呼び出します。

using Microsoft.Agents.A365.Observability.Hosting.Caching;
using Microsoft.Agents.A365.Observability.Runtime.Common;

public class MyAgent : AgentApplication
{
    private readonly IExporterTokenCache<AgenticTokenStruct> _agentTokenCache;

    public MyAgent(AgentApplicationOptions options,
        IExporterTokenCache<AgenticTokenStruct> agentTokenCache) : base(options)
    {
        _agentTokenCache = agentTokenCache;
    }

    protected async Task MessageActivityAsync(
        ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        _agentTokenCache.RegisterObservability(
            turnContext.Activity.Recipient.AgenticAppId,
            turnContext.Activity.Recipient.TenantId,
            new AgenticTokenStruct(
                userAuthorization: UserAuthorization,
                turnContext: turnContext,
                authHandlerName: "AGENTIC"),
            EnvironmentUtils.GetObservabilityAuthenticationScope());
    }
}

検証属性を格納する

ストアの検証を成功させるには、エージェントで InvokeAgentScope、 InferenceScope、および ExecuteToolScopeを実装する必要があります。次の属性は、各スコープに必須または省略可能です。

`InvokeAgentScope`

属性	Status
`gen_ai.agent.id`	Required
`gen_ai.agent.name`	Required
`gen_ai.operation.name`	Required
`gen_ai.input.messages`	Required
`gen_ai.output.messages`	Required
`gen_ai.conversation.id`	Required
`microsoft.tenant.id`	Required
`microsoft.a365.agent.blueprint.id`	Required
`microsoft.agent.user.id`	Required
`microsoft.agent.user.email`	Required
`microsoft.channel.name`	Required
`user.id`	Required
`user.email`	Required
`client.address`	Required
`server.address`	Required
`server.port`	Required
`error.type`	Optional
`gen_ai.agent.description`	Optional
`gen_ai.agent.version`	Optional
`microsoft.a365.agent.platform.id`	Optional
`microsoft.channel.link`	Optional
`microsoft.conversation.item.link`	Optional
`microsoft.session.id`	Optional
`microsoft.session.description`	Optional
`user.name`	Optional
`microsoft.a365.caller.agent.id`	Optional
`microsoft.a365.caller.agent.name`	Optional
`microsoft.a365.caller.agent.blueprint.id`	Optional
`microsoft.a365.caller.agent.platform.id`	Optional
`microsoft.a365.caller.agent.user.email`	Optional
`microsoft.a365.caller.agent.user.id`	Optional
`microsoft.a365.caller.agent.version`	Optional

`ExecuteToolScope`

属性	Status
`gen_ai.agent.id`	Required
`gen_ai.agent.name`	Required
`gen_ai.operation.name`	Required
`gen_ai.tool.name`	Required
`gen_ai.tool.call.id`	Required
`gen_ai.tool.call.arguments`	Required
`gen_ai.tool.call.result`	Required
`gen_ai.tool.type`	Required
`gen_ai.conversation.id`	Required
`microsoft.tenant.id`	Required
`microsoft.a365.agent.blueprint.id`	Required
`microsoft.agent.user.id`	Required
`microsoft.agent.user.email`	Required
`microsoft.channel.name`	Required
`user.id`	Required
`user.email`	Required
`client.address`	Required
`error.type`	Optional
`gen_ai.agent.description`	Optional
`gen_ai.agent.version`	Optional
`gen_ai.tool.description`	Optional
`microsoft.a365.agent.platform.id`	Optional
`microsoft.channel.link`	Optional
`microsoft.conversation.item.link`	Optional
`microsoft.session.id`	Optional
`microsoft.session.description`	Optional
`server.address`	Optional
`server.port`	Optional
`user.name`	Optional

`InferenceScope`

属性	Status
`gen_ai.agent.id`	Required
`gen_ai.agent.name`	Required
`gen_ai.operation.name`	Required
`gen_ai.input.messages`	Required
`gen_ai.output.messages`	Required
`gen_ai.request.model`	Required
`gen_ai.provider.name`	Required
`gen_ai.conversation.id`	Required
`microsoft.tenant.id`	Required
`microsoft.a365.agent.blueprint.id`	Required
`microsoft.agent.user.id`	Required
`microsoft.agent.user.email`	Required
`microsoft.channel.name`	Required
`user.id`	Required
`user.email`	Required
`client.address`	Required
`error.type`	Optional
`gen_ai.agent.description`	Optional
`gen_ai.agent.version`	Optional
`gen_ai.response.finish_reasons`	Optional
`gen_ai.usage.input_tokens`	Optional
`gen_ai.usage.output_tokens`	Optional
`microsoft.a365.agent.platform.id`	Optional
`microsoft.a365.agent.thought.process`	Optional
`microsoft.channel.link`	Optional
`microsoft.conversation.item.link`	Optional
`microsoft.session.id`	Optional
`microsoft.session.description`	Optional
`server.address`	Optional
`server.port`	Optional
`user.name`	Optional

`OutputScope`

属性	Status
`gen_ai.agent.id`	Required
`gen_ai.agent.name`	Required
`gen_ai.operation.name`	Required
`gen_ai.output.messages`	Required
`gen_ai.conversation.id`	Required
`microsoft.tenant.id`	Required
`microsoft.a365.agent.blueprint.id`	Required
`microsoft.agent.user.id`	Required
`microsoft.agent.user.email`	Required
`microsoft.channel.name`	Required
`user.id`	Required
`user.email`	Required
`client.address`	Required
`gen_ai.agent.description`	Optional
`gen_ai.agent.version`	Optional
`microsoft.a365.agent.platform.id`	Optional
`microsoft.channel.link`	Optional
`microsoft.conversation.item.link`	Optional
`microsoft.session.id`	Optional
`microsoft.session.description`	Optional
`user.name`	Optional

可観測性でエージェントをテストする

可観測性を実装した後、テレメトリがキャプチャされていることを確認します。

https://admin.cloud.microsoft/#/agents/all にアクセスします。
エージェントを選択し、[ アクティビティ] を選択します。
セッションとツール呼び出しが表示されることを確認します。

サンプルアプリケーションと高度な構成

作業サンプルと高度な構成オプションについては、各言語のGitHubリポジトリを参照してください。

Troubleshooting

このセクションでは、Microsoft OpenTelemetry Distro と Agent 365 を実装して使用するときの一般的な問題について説明します。

Tip

Agent 365トラブルシューティングガイドには、Agent 365 の開発ライフサイクルの各段階に対応した高レベルのトラブルシューティング推奨事項、ベストプラクティス、トラブルシューティングコンテンツへのリンクが含まれています。

観測データが表示されません

症状：

エージェントが走っている
管理センターにテレメトリはありません
エージェントの活動が見えません

根本原因:

エージェント 365 のエクスポートが有効になっていない
構成エラー
トークンリゾルバの問題

解決策: 問題解決のために以下の手順を試してみてください。

エージェント 365 エクスポートが有効になっていることを確認する

エージェント 365 エクスポーターを明示的に有効にする必要があります。設定しない場合、ディストリビューションはコンソールエクスポーターにフォールバックしたり、何もエクスポートしない可能性があります。コードで有効にします。
- Python
- Node.js
- .NET
```
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
```
Note

ENABLE_A365_OBSERVABILITY_EXPORTER は、コードで enable_a365=True が設定されている場合にのみ有効なセカンダリトグルです。 a365_enable_observability_exporter kwarg を使用して制御することもできます。
```
useMicrosoftOpenTelemetry({
  a365: { enabled: true },
});
```
または、環境変数を設定します。
```
ENABLE_A365_OBSERVABILITY_EXPORTER=true
```
Note

ENABLE_A365_OBSERVABILITY_EXPORTER は、コードで a365 オプションが指定されている場合にのみ有効なセカンダリトグルです。 A365 エクスポーターを単独でアクティブ化することはできません。
```
builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365;
    o.Agent365.Exporter.TokenResolver = async (agentId, tenantId) =>
        await myTokenService.GetTokenAsync(agentId, tenantId);
});
```

トークンリゾルバの設定を確認する

エクスポーターには、エクスポート要求ごとにベアラートークンを返す有効なトークンリゾルバーが必要です。トークンリゾルバーが見つからないか、 nullを返した場合、エクスポートは自動的にスキップされます。
コンソールのエクスポートを有効にし、テレメトリをローカルで確認する

コンソールエクスポーターを追加して、エージェント 365 エンドポイントに到達する前にテレメトリが生成されていることを確認します。
- Python
- Node.js
- .NET
```
use_microsoft_opentelemetry(enable_a365=True, enable_console=True)
```
```
useMicrosoftOpenTelemetry({ enableConsoleExporters: true });
```
```
builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365 | ExportTarget.Console;
});
```

詳細ログ記録を有効化
- Python
- Node.js
- .NET
```
import logging

logging.basicConfig(level=logging.DEBUG)
```
A365_OBSERVABILITY_LOG_LEVELを info または warn に設定して、内部 A365 エクスポーター診断を表示します。
```
A365_OBSERVABILITY_LOG_LEVEL=info
```
内部コンポーネントは、DI から ILoggerFactory 経由でログに記録されます。 ASP.NET Core アプリでは、ログ記録はアプリの構成済みパイプラインを自動的に通過します。コンソールアプリの場合は、明示的に接続します。
```
builder.Services.AddLogging(logging => logging.AddConsole());
```

エクスポートエラーのログを確認する

az webapp log tail コマンドを使用して、監視に関連するエラーのログを検索します。
```
az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"
```

テナント ID またはエージェント ID が見つからない - 範囲がスキップされました

症状： システムは自動的にスパンをドロップし、エクスポートしません。一部のプラットフォームでは、スキップされたスパンの数や、 No spans with tenant/agent identity foundなどのメッセージが記録されます。他のユーザーは、ログを記録せずに削除します。

解決方法:

エクスポートの前に、ディストリビューションパーティションはテナント ID とエージェント ID ごとにまたがっています。テナント ID またはエージェント ID がないスパンは削除され、サービスに送信されることはありません。
スパンを作成する前に、 BaggageBuilder がテナント ID とエージェント ID で設定されていることを確認します。これらの値は OpenTelemetry コンテキストを通じて伝達され、手荷物スコープ内で作成されたすべてのスパンにアタッチされます。プラットフォーム固有の API については、「 Baggage 属性」を参照してください。
ホスティング統合パッケージの手荷物ミドルウェアまたはターンコンテキストヘルパーを使用している場合は、 TurnContext アクティビティにエージェント ID を持つ有効な受信者があることを確認します。

トークン解決失敗 - エクスポートがスキップされるか未承認

症状： トークンリゾルバーは null を返すか、エラーをスローします。プラットフォームによっては、エクスポートが完全にスキップされるか、HTTP 401 で失敗します。

解決方法:

トークンリゾルバーが必要です。見つからない場合、エクスポーターは起動時にエラーをスローします。トークンリゾルバーが提供され、有効なベアラートークンが返されることを確認します。
これらの値はトークンリゾルバーに転送されるため、正しいテナント ID とエージェント ID が BaggageBuilderに渡されていることを確認します。
Azureホステッドエージェントの場合は、マネージド ID に監視スコープに必要な API アクセス許可があることを確認します。
Agent Framework ホスティングパッケージを使用する.NET アプリの場合、トークン交換は DI を介して自動的に処理されます。トークンがない場合は、Microsoft.Agents.A365.Observability.Hosting がインストールされ、登録されていることを確認します。

HTTP 401 認証されていません

症状： HTTP 401 でエクスポートが失敗する。エクスポーターはこのエラーを再試行しません。

解決方法:

トークン対象ユーザーが可観測性エンドポイントスコープと一致するかどうかを確認します。
トークンリゾルバーが、委任されたユーザートークン、正しくない対象ユーザーのトークン、または期限切れのトークンを返していないことを確認します。

HTTP 403 Forbidden（アクセス禁止）

症状： HTTP 403 でエクスポートが失敗する。エクスポーターはこのエラーを再試行しません。

根本原因: HTTP 403 エラーの原因が異なる場合があります。次の解決策を順番に確認してください。

解決方法:

Missing license — テナントに、Microsoft 365 管理センター。
- Test - Microsoft 365 E7
- Microsoft 365 E7
- Microsoft Agent 365 Frontier
Agent365.Observability.OtelWriteアクセス許可がありません - ID (マネージド ID またはアプリの登録) にこのアクセス許可を付与する必要があります。これを指定しないと、HTTP 403 でテレメトリのエクスポートが失敗します。

次のいずれかのオプションを使用して、アクセス許可を付与します。

Option A — Agent 365 CLI (構成ディレクトリにa365.config.jsonおよびa365.generated.config.json、グローバル管理者アカウント、Agent 365 CLI v1.1.139-preview以降が必要です)
```
a365 setup admin --config-dir "<path-to-config-dir>"
```
オプション B — Entra ポータル (構成ファイルは必要ありません。ブループリントアプリの登録に対するグローバル管理者アクセスが必要)
1. Entra ポータル>アプリ登録>ブループリントアプリを選択します。
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 429 / 5xx — 一時的なエラー

症状： エクスポートは、429 や 5xx などの一時的な HTTP 状態コードで失敗します。

解決方法:

通常、これらのエラーは一時的なものであり、単独で解決されます。 Pythonおよび JavaScript ディストリビューションは、HTTP 408、429、および 5xx 状態コードで自動的に再試行します。 .NET ディストリビューションは自動的に再試行されません。
エラーが解決しない場合は、サービス正常性ダッシュボードを確認します。
バッチ間のスケジュールされた遅延を増やすか、最大エクスポートバッチサイズを増やすことで、エクスポートの頻度を減らすことを検討してください。 Pythonおよび JavaScript の場合は、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
)

オプションの完全な一覧については、a365_*を参照してください。

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver: myTokenResolver,
    httpRequestTimeoutMilliseconds: 60000,
  },
});

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365;
    o.Agent365.Exporter.ExporterTimeoutMilliseconds = 60000;
});

エクスポートは成功しますが、テレメトリは Defender または Purview に表示されません

Symptoms: ログには正常なエクスポート (HTTP 200) が表示されますが、テレメトリはMicrosoft DefenderまたはMicrosoft Purviewに表示されません。

解決方法:

エクスポートされたログを表示するための前提条件を満たしていることを確認します。
- Microsoft Purview: 組織の監査を有効にする必要があります。「監査のオンとオフを切り替える」を参照してください。
- Microsoft Defender: CloudAppEvents テーブルにアクセスするために、高度なハンティングを設定する必要があります。高度なハンティングスキーマの CloudAppEvents テーブルを参照してください。
エクスポートが成功した後、テレメトリの設定には数分かかる場合があります。さらに調査する前に待ってください。
スパンに有効な microsoft.tenant.id 属性と gen_ai.agent.id 属性が含まれていることを確認します。 ID 属性が見つからないと、HTTP エクスポートから 200 が返された場合でも、サーバー側でスパンが削除されます。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-05-05

Microsoft OpenTelemetry Distro

主な利点

インストールとコンフィギュレーション

ライブラリをインストールする

コンフィギュレーション

コンテキストの伝達

バゲッジ属性

手荷物ミドルウェア

製品でデータが流れているかどうかを検証する

自動インストルメンテーション

インストルメントカバレッジ

組み込みのインストルメンテーション ライブラリ

セマンティック カーネル

OpenAI

エージェント フレームワーク

LangChain

手動インストルメンテーション

エージェント呼び出し

ツールの実行

推論

アウトプット

ローカル検証

ローカル OTLP エンドポイントを使用して検証する

ローカル出力を使用して検証する

認証を手動で設定する

手動トークン リゾルバー

エージェント フレームワーク アプリでのエージェンティック トークン キャッシュ

検証属性を格納する

InvokeAgentScope

ExecuteToolScope

InferenceScope

OutputScope

可観測性でエージェントをテストする

サンプル アプリケーションと高度な構成

Troubleshooting

観測データが表示されません

テナント ID またはエージェント ID が見つからない - 範囲がスキップされました

トークン解決失敗 - エクスポートがスキップされるか未承認

HTTP 401 認証されていません

HTTP 403 Forbidden（アクセス禁止）

HTTP 429 / 5xx — 一時的なエラー

エクスポートのタイムアウト

エクスポートは成功しますが、テレメトリは Defender または Purview に表示されません

フィードバック

その他のリソース

組み込みのインストルメンテーションライブラリ

セマンティックカーネル

エージェントフレームワーク

手動トークンリゾルバー

エージェントフレームワークアプリでのエージェンティックトークンキャッシュ

`InvokeAgentScope`

`ExecuteToolScope`

`InferenceScope`

`OutputScope`

サンプルアプリケーションと高度な構成