Microsoft OpenTelemetry Distro

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

Note

既存の統合を維持して以前のAgent 365 Observability SDKを使用している場合は、廃止されたSDKのドキュメントや移行ガイドを確認してください。

主な利点

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 を参照してください。

Configuration

エージェント 365 エクスポーターは接続文字列を使用しません。テナントに基づいてエンドポイントが自動的に検出されます。エージェント 365 へのエクスポートを有効にするには、エクスポーターターゲットを設定し、特定のエージェント ID とテナント ID のアクセストークンを返すトークンリゾルバーを提供します。

デフォルトでは、ディストリビューションは委任されたルート上でエクスポートを行いますが、これには Agent365.Observability.OtelWrite のアクセス許可と管理者の承認が必要です。 a365 setup allコマンドはブループリントエージェントにその権限を設定しないので、代わりにアプリ専用リゾルバー付きのS2Sを使ってください。登録エージェントインスタンスは、Observabilityの許可や管理者の同意なしにS2Sルート上でエクスポートできます。

監視を有効にするには、 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()に渡すことで、エクスポーターの動作をカスタマイズできます。

パラメーター	Description	Default
`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`

委任トークンのキャッシュを自動的に処理するには、AgenticTokenCacheInstance を ObservabilityManager とともに使用します:

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	Default
`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)トークンキャッシュ:

TokenResolverを設定しない場合、ディストリビューションは DI 経由でIExporterTokenCache<AgenticTokenStruct>を自動的に登録します。エージェントは実行時に RegisterObservability() を呼び出して認証情報を提供し、キャッシュは委任されたトークン取得と更新を処理します。 a365 setup allで設定したBlueprintエージェントの場合は、委任されたObservability権限と管理者の同意を付与していない限り、代わりにアプリ専用リゾルバ付きのS2Sを使うのが良いでしょう。

// Program.cs — no TokenResolver needed for the delegated route
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	Default
`UseS2SEndpoint`	`true`場合は、サービス間エンドポイントパスを使用します。アプリ専用のトークンリゾルバで使用してください。	`false`
`MaxQueueSize`	バッチプロセッサの最大キューサイズ。	`2048`
`ScheduledDelayMilliseconds`	エクスポートバッチ間の遅延 (ミリ秒単位)。	`5000`
`ExporterTimeoutMilliseconds`	エクスポート操作のタイムアウト (ミリ秒単位)。	`30000`
`MaxExportBatchSize`	エクスポート操作の最大バッチサイズ。	`512`

Note

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

コンテキストの伝達

分散エージェント 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 テレメトリを収集できます。

Category	内容
シグナルパイプライン	トレース、メトリック、およびログ。
リソース検出	サポートされているサービス、ホスト、クラウド、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 ソース、メーター、プロセッサ、またはリーダーを追加します。

Important

自動インストルメンテーションでは、標準の OpenTelemetry 属性のみが設定されます。エージェント 365 に必要なすべての属性が含まれているわけではありません。 BaggageBuilder を使用して、Microsoft固有の属性を追加する必要があります。必要な属性を確認するには、「検証属性を格納する」を参照してください。

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

自動インストルメンテーションは、サポートされているフレームワークによって出力されたテレメトリをリッスンし、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

Note

LangChain フレームワークの自動インストルメンテーションでは、 LangGraph および Deep Agents もサポートされます。同じインストルメンテーションによって、これらのフレームワークのいずれかで構築されたエージェントのテレメトリが自動的にキャプチャされます。

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 を使用して、エクスポートバッチごとに機能します。ディストリビューションでは、2 つの方法がサポートされています。

a365 setup all で設定された Agent 365 対応のブループリントエージェントについては、アプリ専用リゾルバーを使用した S2S を使用してください。このページの組み込みのエージェント型トークンキャッシュと OBO の例は、委任ルートを使用しており、Agent365.Observability.OtelWrite の委任されたアクセス許可と管理者の同意が必要です。 a365 setup all コマンドでは、ブループリントエージェントに対してそのアクセス許可を構成できません。

Tip

Microsoft 365 エージェント SDK を使用してエージェントを構築する場合は、エージェント SDK のObservability Authentication Setup に関するページを参照してください。エージェントエージェントと非エージェントエージェントの両方に対して OBO と S2S トークンの取得を構成する手順について説明します。

手動トークンリゾルバー

Agent Frameworkパイプライン外でトークンを取得する際、Agent Framework以外のアプリを構築する際、サービス間(S2S)認証を使う際は手動リゾルバを使用してください。リゾルバが返すトークンはルートと一致しなければなりません。委任ルートの場合は、 Agent365.Observability.OtelWrite スコープ付きの委任トークンを返します。 S2Sルートでは、 api://9b975845-388f-4429-889e-eab1ef63949c/.default スコープでリクエストした最終的なアプリ専用トークンを返します。 S2S に登録されたブループリントエージェントには、Agent365.Observability.OtelWrite ロールも管理者の同意も必要ありません。

Note

サービス間 (S2S) 認証の場合は、この手動トークンリゾルバーアプローチを使用する必要があります。エージェントトークンキャッシュは、On-Behalf-of (OBO) 認証フローのみをサポートします。

次の例は、OBO（代理実行） トークンリゾルバーパターンを示しています。エージェントは、agentic 認証ハンドラーを介してユーザートークンを取得し、それをオブザーバビリティスコープのトークンと交換します。これらの例では、委任された Agent365.Observability.OtelWrite アクセス許可と管理者の同意が必要です。 S2S (サービス間) の例と OBO と S2S 認証の比較については、「Agent SDK の Observability Authentication Setup」を参照してください。

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

from microsoft.opentelemetry import use_microsoft_opentelemetry
from microsoft.opentelemetry.a365.runtime import get_observability_authentication_scope

_cached_token: str | None = None

def my_token_resolver(agent_id: str, tenant_id: str) -> str | None:
    return _cached_token

use_microsoft_opentelemetry(enable_a365=True, a365_token_resolver=my_token_resolver)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    global _cached_token
    _cached_token = await AGENT_APP.auth.exchange_token(
        context,
        scopes=get_observability_authentication_scope(),
        auth_handler_id="AGENTIC",
    )

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 トークンキャッシュは登録されません。リゾルバーが代わりに使用されます。

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

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

Note

このアプローチでは、委任ルート上の「on-behalf-of (OBO) 」認証フローのみをサポートしており、これには委任された Agent365.Observability.OtelWrite のアクセス許可と管理者の同意が必要となります。サービス間(S2S)認証では、a365 setup allを使用して設定されたブループリントエージェントを含め、代わりにアプリ専用トークンで手動のトークンリゾルバを使用してください。セットアップの手順については、S2S を使用した Agent 365 の有効化を参照してください。

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を実装する必要があります。各スコープは、正規スキーマのスパン操作に対応します。

SDK の範囲	スパン操作	ユニバーサル参照コード
`InvokeAgentScope`	`invoke_agent`	`IA`
`ExecuteToolScope`	`execute_tool`	`ET`
`InferenceScope`	`chat`	`CH`
`OutputScope`	`output_messages`	`OM`

スコープごとの必須属性とオプション属性の完全な一覧（各属性のセマンティクス、値の選択に関するガイダンス、および Microsoft Defender の高度なハンティングでクエリできる属性を含む）については、Agent 365 監視属性リファレンスを参照してください。 [適用先] 列は各属性が属するスコープを識別し、[必須] 列は必須 (M) と省略可能な (O) 属性を区別します。

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

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

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

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

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

プログラミング・リファレンス

Microsoft OpenTelemetry Distroの種類を詳しく確認するには、以下のプログラミング参考記事をご覧ください。

Troubleshooting

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

問題	Description
可観測性データが表示されない	Agent 365のエクスポートが有効でなかったり、設定が完了していない、トークン解決が失敗したりするため、テレメトリが表示されません。
テナント ID またはエージェント ID が見つからない - スパンがスキップされました	必要なテナントまたはエージェントの識別属性が欠落している場合、エクスポート前にスパンが除外されます。
トークンの解決に失敗しました - エクスポートはスキップされたか、許可されていません	トークンの取得中にトークンリゾルバーがトークンまたはエラーを返さない場合、エクスポートはスキップまたは拒否されます。
HTTP 401 Unauthorized（認証が必要です）	要求はサービスに到達しますが、トークンが無効であるか、期限切れであるか、間違った対象ユーザーに対して行われるため、認証は失敗します。
HTTP 403 無効	認可が失敗するのは、テナントライセンスの欠如、未登録のS2Sアイデンティティ、または必要なところで可観測性書き込み権限が欠けているためです。
HTTP 403 Forbidden - エージェント ID の不一致	要求内のエージェント ID がトークン承認エージェント ID と一致しない場合、サービスはエクスポートを拒否します。
HTTP 429 または 5xx エラー - 一時的なエラー	一時的なスロットリングやバックエンドの不安定性による割り込みはエクスポートを中断し、再試行やバッチチューニングが必要になることがあります。
エクスポートのタイムアウト	ネットワーク遅延またはエンドポイントの応答待機時間が原因で、エクスポート操作がタイムアウト制限を超えています。
エクスポートは成功しますが、テレメトリは Defender または Purview に表示されません	データインジェストは成功しますが、ダウンストリームの前提条件とスキーマの要件によって可視性が遅延またはブロックされます。

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に渡されていることを確認します。
S2Sの場合は、 9b975845-388f-4429-889e-eab1ef63949c または api://9b975845-388f-4429-889e-eab1ef63949cの最終アプリ専用のObservabilityトークンを返します。中間ブループリントのアサーション、ブループリントトークン、ユーザートークン、または OBO トークンを返さないでください。
委任ルートの場合は、 Agent365.Observability.OtelWrite スコープ付きの委任トークンを返します。
マネージドIDで直接エクスポートするAzureホストエージェントの場合、マネージドIDがAgent365.Observability.OtelWriteアプリロールを持っているか確認してください。 S2S に登録済みのブループリントエージェントインスタンスには、これは不要です。
Agent Framework ホスティングパッケージを使用する.NET アプリの場合、トークン交換は DI を介して自動的に処理されます。トークンがない場合は、Microsoft.Agents.A365.Observability.Hosting がインストールされ、登録されていることを確認します。

HTTP 401 認証されていません

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

解決方法:

トークンの対象ユーザーが 9b975845-388f-4429-889e-eab1ef63949c または api://9b975845-388f-4429-889e-eab1ef63949c であり、トークンの種類がルートと一致していること、つまり委任ルートには委任トークン、S2S ルートにはアプリ専用トークンが使用されていることを確認しましょう。
S2Sの場合、リゾルバが委任されたユーザートークン、中間ブループリントアサーション、ブループリントトークン、誤ったオーディエンス向けトークン、期限切れトークンを返していないか確認してください。
委任ルートについては、トークンの scp クレームに Agent365.Observability.OtelWrite が含まれているか、トークンが期限切れでないかを確認してください。

HTTP 403 Forbidden（アクセス禁止）

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

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

解決方法:

Missing license — テナントに、Microsoft 365 管理センター。
- テスト - Microsoft 365 E7
- Microsoft 365 E7
- Microsoft エージェント 365 フロンティア
S2S 上の未登録の ID ― 登録済みのループリントエージェントインスタンスは、Agent365.Observability.OtelWrite ロールを持たないアプリ専用トークンを使用して、S2S ルート上でエクスポートをできます。もしそのIDがエージェント365に登録されていなければ、サービスはHTTP 403 insufficient_scopeを返します。ブループリントエージェントの場合、 a365 setup all はエージェントインスタンスを登録します。登録失敗をやり直すには a365 setup all --agent-registration-onlyを実行してください。 Microsoft Entraのアイデンティティを作成するだけではエージェントインスタンスは登録されません。
必要な場所でアクセス許可が不足Agent365.Observability.OtelWriteしています — 委任されたルート、または未登録の ID (標準アプリ登録を含む) に対してアクセス許可を付与します。 S2Sの登録ブループリントエージェントはこの許可を必要としません。

アクセス許可を付与する

委任ルートまたは未登録のIDを使用する場合にのみ、Agent365.Observability.OtelWrite を付与してください。 S2Sを使う登録ブループリントエージェントは、この権限や管理者の同意を必要としません。ルートが使用する権限タイプのみを付与してください:

委任ルート: 委任されたアクセス許可を追加します。
未登録の ID を使用する S2S ルート（カスタムエンジンエージェントで使用される標準的なアプリ登録など）の場合: アプリケーション権限（アプリロール）を追加します。

次のいずれかのオプションを使います。

Agent 365 CLI (委任ルート上のブループリントエージェント)

このコマンドを実行すると、ブループリントとその継承可能なアクセス許可に委任されたアクセス許可が追加され、その後、管理者による承認が付与されます。アプリケーションのアクセス許可が追加されません。グローバル管理者アカウントが必要です。 a365.config.jsonを含むagent projectディレクトリからコマンドを実行するか、--agent-name "<agent-name>"を追加してください。
```
a365 setup permissions custom --resource-app-id 9b975845-388f-4429-889e-eab1ef63949c --scopes Agent365.Observability.OtelWrite
```
Microsoft Entra 管理センター(どちらのルートでも)

設定ファイルは不要です。アプリ登録にはグローバル管理者のアクセスが必要です。委任ルート上のブループリントの場合、このオプションは、そのブループリントがすでにObservability APIを継承権限に含んでいる場合(例えば、以前のCLIバージョンで設定されたブループリントなど)に限ります。それ以外の場合は、Agent 365 CLIを使いましょう。
1. Microsoft Entra 管理センターにアクセスし、アプリの登録を選択し、ブループリントまたは標準アプリ登録を選択します。
2. API のアクセス許可に移動します>アクセス許可の追加>組織が使用する API>9b975845-388f-4429-889e-eab1ef63949cを検索します。
3. 委任ルートについては委任されたアクセス許可を、S2S ルート上の未登録の ID についてはアプリケーションのアクセス許可を選択してください。
4. Agent365.Observability.OtelWriteをチェックしてから「権限を追加」を選択してください。
5. 管理者の同意を付与を選択して確認してください。
追加したアクセス許可の状態は Granted となっています。

HTTP 403 Forbidden — エージェント ID の不一致

症状: HTTP 403 でエクスポートが失敗し、Agent 365 トレースエンドポイントの呼び出しで 403 Forbidden エラーが発生したことを示す、agent-ID-mismatch のようなサーバーメッセージが返されます。

根本原因:このエラーは、エージェントの詳細を設定するときに、エージェントインスタンスクライアント ID ではなくブループリントクライアント ID を使用する場合に発生します。エクスポート URL のエージェント ID がトークンによって承認された ID と一致しないため、トレースエンドポイントは要求を拒否します。

解決方法:

テナント ID が Agent 365 の許可されるテナントの一覧に追加されているかどうかを確認します。
エージェントの詳細は、(ブループリント クライアント ID ではなく) エージェントインスタンスクライアント ID で設定します。
生成されたエクスポート URL を確認します。ロガーを有効にするとログに記録されます。 URL のエージェント ID がエージェントインスタンスのクライアント ID と一致であることを確認します。
SDK ごとに診断ログを有効にするには、「ローカル検証」を参照してください。

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 が返された場合でも、サーバー側でスパンが削除されます。

エージェント 365 監視の概念 - データフロー、ID モデル、認証、スコープ、およびすべての統合パスに適用される制限。
エージェント 365 監視属性リファレンス - エージェント 365 によって取り込まれるすべてのスパンが準拠している必要がある正規スパン属性スキーマ。

フィードバック

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

最終更新: 2026-10-02

Microsoft OpenTelemetry Distro

主な利点

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

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

Configuration

コンテキストの伝達

バゲッジ属性

手荷物ミドルウェア

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

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

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

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

セマンティック カーネル

OpenAI

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

LangChain

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

エージェント呼び出し

ツールの実行

推論

アウトプット

ローカル検証

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

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

認証を手動で設定する

手動トークン リゾルバー

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

検証属性を格納する

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

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

プログラミング・リファレンス

Troubleshooting

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

テナント ID またはエージェント ID が欠落しています — 範囲がスキップされました

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

HTTP 401 認証されていません

HTTP 403 Forbidden（アクセス禁止）

アクセス許可を付与する

HTTP 403 Forbidden — エージェント ID の不一致

HTTP 429 または 5xx エラー - 一時的なエラー

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

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

関連するコンテンツ

フィードバック

その他のリソース

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

セマンティックカーネル

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

手動トークンリゾルバー

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

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