@microsoft/agents-a365-observability package

エクスポート バッチあたりのスパンの最大数。

OpenTelemetry コンテキスト伝達の要求手荷物ビルダーごと。

このクラスは、OpenTelemetry コンテキストで伝達される手荷物の値を設定するための fluent API を提供します。

例

const scope = new BaggageBuilder()
  .tenantId("tenant-123")
  .agentId("agent-456")
  .build();

scope.enter();
// Baggage is set in this context
// ... do work ...
scope.exit();
// Baggage is restored after exiting the context

手荷物スコープのコンテキストマネージャー。

このクラスは手荷物の値のライフサイクルを管理し、入り口に設定し、終了時に前のコンテキストを復元します。

OpenTelemetry トレースを使用してエージェント 365 を構成するためのビルダー

AI ツール実行操作の OpenTelemetry トレース スコープを提供します。

生成 AI 推論操作用の OpenTelemetry トレース スコープを提供します。

AI エージェント呼び出し操作の OpenTelemetry トレース スコープを提供します。

監視パッケージの構成。 ランタイム設定を継承し、可観測性固有の設定を追加します。

AI エージェントとツールの OpenTelemetry トレースを提供する Agent 365 の主要なエントリ ポイント

エージェント 365 の OpenTelemetry 定数

OpenTelemetry トレース スコープの基本クラス

親スパン リンクを使用した出力メッセージ トレースの OpenTelemetry トレース スコープを提供します。

PerRequestSpanProcessor の構成。 ランタイム設定 (clusterCategory、isNodeEnvDevelopment) を継承し、要求ごとのプロセッサ ガードレールを追加します。

PerRequestSpanProcessor は特定のシナリオでのみ使用され、これらの設定は一般的な ObservabilityConfiguration では公開しないでください。

AI エージェントの詳細

インライン バイナリ データ (base64 エンコード)。

Agent 365 Observability Builder の構成オプション

スコープ作成の呼び出し元の詳細。 人間の呼び出し元、エージェントの呼び出し元、またはその両方 (A2A とチェーン内の人間) をサポートします。

移行に関する注意: v1 では、名前 CallerDetails 人間の呼び出し元 ID (現在 は UserDetails) と呼ばれます。 v2 では、人間とエージェントの両方の呼び出し元情報をグループ化するラッパーとして再利用されました。

移行ガイダンスについては、 UserDetails (人間の発信者 ID (以前の CallerDetails) CHANGELOG.md に関するセクションを参照してください。

呼び出しのチャネルを表します

モデルに送信される入力メッセージ (OTEL gen-ai セマンティック規則)。

事前にアップロードされたファイルへの参照。

カスタム/将来の型の拡張可能な部分。

拡張サーバー ツールは、型識別子を使用して詳細を呼び出します。

拡張可能なサーバー ツールは、型識別子を使用して応答を呼び出します。

Agent 365 監視用のカスタム ロガー インターフェイス:バックエンドのログ記録をサポートするためにこのインターフェイスを実装します

推論呼び出しの詳細

推論呼び出しからの応答を記録するための詳細

エージェント スコープを呼び出すための詳細。

モデルによって生成された出力メッセージ (OTEL gen-ai セマンティック規則)。

エージェントからの出力メッセージを含む応答を表します。 出力メッセージ トレースに OutputScope と共に使用されます。 プレーン文字列、構造化された OTEL OutputMessage オブジェクト、または生のディクテーション (OTEL 仕様ごとのツール呼び出し結果として扱われます) を受け入れます。

非同期境界を越えた明示的な親子リンクの親スパンへの参照。 コンテキストの自動伝達が失敗した場合に使用されます (WebSocket コールバック、外部イベント ハンドラーなど)。

モデル推論/考え方の連鎖コンテンツ。

テレメトリ コンテキストを持つ要求を表します。 チャネルと会話の追跡のために、すべてのスコープの種類で使用されます。

サーバー側ツールの呼び出し。

サーバー側ツールの応答。

エージェント呼び出しのエンドポイントを表します

スコープを作成するためのスパン構成の詳細。 OpenTelemetry のスパン オプションを 1 つのオブジェクトにグループ化し、新しいオプションが追加されるとスコープ メソッドシグネチャが安定したままになります。

テキスト形式のコンテンツ。

エージェントによって行われたツール呼び出しの詳細

モデルによって要求されたツール呼び出し。

ツール呼び出しの結果。

外部 URI 参照。

人間のユーザー呼び出し元に関する詳細。

トレース コンテキスト伝達で使用される HTTP ヘッダーのキャリアの種類。 Node.js IncomingHttpHeaders およびプレーン文字列マップと互換性があります。

recordInputMessagesに対して受け入れられた入力。 1 つの文字列、文字列の配列 (下位互換性)、またはバージョン管理されたラッパーをサポートします。

OTEL gen-ai セマンティック規則に従った、すべてのメッセージ パーツの種類の和集合。

注: GenericPart は、カスタムまたは将来のパーツ型との前方互換性のためのキャッチオールとして機能します。 typeは (リテラルではなく) stringであるため、part.typeに対する完全なswitch/caseでは、ハンドルされないケースのコンパイル時エラーは生成されません。

監視の構成オプション - ランタイム オプションを拡張します。 すべてのオーバーライドは、各プロパティ アクセスで呼び出される関数です。

RuntimeConfigurationOptions から継承されます。

• clusterCategory
• isNodeEnvDevelopment

注: isDevelopmentEnvironment は、オーバーライド可能なオプションではなく、(clusterCategory に基づく) 構成クラスの派生ゲッターです。

recordOutputMessagesに対して受け入れられた入力。 1 つの文字列、文字列の配列 (下位互換性)、またはバージョン管理されたラッパーをサポートします。

スパン作成の親コンテキスト。 以下のいずれかを受け入れます:

• ParentSpanRef: 明示的な traceId/spanId ペア (手動アプローチ)
• ParentContext: OTel コンテキスト。通常は extractContextFromHeaders または propagation.extract()

PerRequestSpanProcessor の構成オプション - ランタイム オプションを拡張します。 すべてのオーバーライドは、各プロパティ アクセスで呼び出される関数です。

RuntimeConfigurationOptions から継承されます。

• clusterCategory、isNodeEnvDevelopment

OutputResponse.messagesに対して受け入れられた入力。 プレーン文字列、構造化された OutputMessage、または生のディクテーションをサポートします (OTEL 仕様ごとにツール呼び出し結果として扱われ、JSON.stringify 経由で直接シリアル化されます)。

ログ記録と監視に Agent365Exporter によって使用されるイベント名。 これらは、効率的な監視と集計を保証するために、カーディナリティの低いイベントの種類です。

モデルが OTEL gen-ai セマンティック規則に従って生成を停止した理由。

モデル推論の型に対するさまざまな操作を表します

エージェントを呼び出すことができるさまざまなロールを表します

OTEL gen-ai セマンティック規則ごとのメッセージ参加者の役割。

BLOB、ファイル、URI の各部分のメディア モダリティ。

明示的な親スパン参照を持つ新しいコンテキストを作成します。 これにより、非同期コンテキストが壊れた場合でも、子スパンを正しく親にすることができます。

グローバルに登録された W3C 伝達子を使用して、受信 HTTP ヘッダーからトレース コンテキストを抽出します。 スコープ クラスに ParentContext として渡すことができる OTel ParentContextを返します。

例

const parentCtx = extractContextFromHeaders(req.headers);
const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails, undefined, { parentContext: parentCtx });

メッセージとスタック トレースを使用してログ記録のエラー オブジェクトを書式設定する

特定の OTel コンテキスト (またはアクティブな OTel コンテキスト) から要求ごとのエクスポート トークンを取得します。

現在のロガー インスタンスを取得する

グローバルに登録された W3C 伝達子を使用して、指定されたヘッダー オブジェクトに現在のトレース コンテキスト (traceparent/tracestate ヘッダー) を挿入します。

例

const headers: Record<string, string> = {};
injectContextToHeaders(headers);
await fetch('http://service-b/process', { headers });

要求ごとのエクスポートが有効になっているかどうかを確認します。 優先順位: 構成プロバイダー > 環境変数 > 内部オーバーライド。 有効にすると、BatchSpanProcessor の代わりに PerRequestSpanProcessor が使用されます。 トークンは、エクスポート時に OTel コンテキスト (非同期ローカル ストレージ) を介して渡されます。

バージョン管理されたInputMessages ラッパーにInputMessagesParamを正規化します。

• string / string[] → ChatMessage[] に変換され、ラップされます
• InputMessages 返→as-is

バージョン管理されたOutputMessages ラッパーにOutputMessagesParamを正規化します。

• string / string[] → OutputMessage[] に変換され、ラップされます
• OutputMessages 返→as-is

既定のコンソール ロガーにリセットする (主にテスト用)

要求ごとのエクスポート トークンを含むコンテキスト内で関数を実行します。 これにより、トークンは OTel Context (ALS) にのみ保持され、レジストリには保持されません。

トークンは、トレースがフラッシュされる前に updateExportToken() を介して後で更新できます。コールバックの実行時間が長く、エクスポート前に元のトークンの有効期限が切れる可能性がある場合に便利です。

受信 HTTP ヘッダーからトレース コンテキストを抽出し、そのコンテキスト内でコールバックを実行します。 コールバック内で作成されたすべてのスパンは、抽出されたトレースの親になります。

例

runWithExtractedTraceContext(req.headers, () => {
  const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
  scope.dispose();
});

明示的な親スパン参照を持つコンテキスト内でコールバック関数を実行します。 これは、コンテキスト伝達が中断される非同期コールバックで子スパンを作成する場合に便利です。

値が常に JSON で解析可能な文字列であることを確認します。

• オブジェクトは JSON.stringify を使用してシリアル化されます。
• 既に有効な JSON オブジェクト/配列である文字列が渡されます。
• その他のすべての文字列 (ベア JSON プリミティブを含む) は、 { [key]: value }ラップされます。

バージョン管理されたメッセージ ラッパーを JSON にシリアル化します。

出力は完全なラッパー オブジェクトです: {"version":"0.1.0","messages":[...]}。

try/catch を使用すると、メッセージ 部分に JSON シリアル化不可能な値 (BigInt、循環参照など) が含まれている場合でも、テレメトリの記録がスローされないようにします。

監視 SDK のカスタム ロガー実装を設定する

Winston の例:

import * as winston from 'winston';
import { setLogger } from '@microsoft/agents-a365-observability';

const winstonLogger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' })
  ]
});

setLogger({
  info: (msg, ...args) => winstonLogger.info(msg, ...args),
  warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
  error: (msg, ...args) => winstonLogger.error(msg, ...args),
  event: (eventType, isSuccess, durationMs, message, details) => {
    // eventType is ExporterEventNames enum value
    winstonLogger.log({ level: isSuccess ? 'info' : 'error', eventType, isSuccess, durationMs, message, ...details });
  }
});

文字列値を MAX_ATTRIBUTE_LENGTH 文字に切り捨てます。 値が制限を超えた場合は、トリミングされ、切り捨てサフィックスが追加され、合計の長さが正確に MAX_ATTRIBUTE_LENGTHに制限されます。

アクティブな OTel コンテキストでエクスポート トークンを更新します。 これを呼び出して、実行時間の長い要求中に元のトークンの有効期限が切れた場合にルート スパンを終了する前にトークンを更新します。

runWithExportTokenによって作成されたのと同じ非同期コンテキスト内で呼び出す必要があります。

スパン属性値の最大長。 この制限を超える値は、サフィックス付きで切り捨てられます。

ObservabilityConfiguration の共有の既定のプロバイダー。

PerRequestSpanProcessorConfiguration の共有既定プロバイダー。

下位互換性のための既定のロガー インスタンス。 setLogger() を介して置き換えることができるグローバル ロガーにデリゲートします。