Tracing

このページでは、AIエージェント向けの包括的なトレーシング機能を提供するTracing機能について詳しく説明します。

機能概要

Tracing機能は、エージェントの実行に関する詳細情報を捕捉する強力なモニタリングおよびデバッグツールです。捕捉される情報には以下が含まれます。

戦略の実行
LLM呼び出し
LLMストリーミング（開始、フレーム、完了、エラー）
ツール呼び出し
エージェントグラフ内のノード実行

この機能は、エージェントパイプライン内の主要なイベントを傍受し、構成可能なメッセージプロセッサーに転送することで動作します。これらのプロセッサーは、トレース情報をログファイルやファイルシステム内のその他の種類のファイルなど、様々な出力先に出力でき、開発者はエージェントの動作を把握し、問題を効果的にトラブルシューティングできます。

イベントフロー

Tracing機能は、エージェントパイプライン内のイベントを傍受します。
イベントは、設定されたメッセージフィルターに基づいてフィルタリングされます。
フィルタリングされたイベントは、登録されたメッセージプロセッサーに渡されます。
メッセージプロセッサーはイベントをフォーマットし、それぞれの出力先に出力します。

設定と初期化

基本的なセットアップ

Tracing機能を使用するには、以下が必要です。

1つ以上のメッセージプロセッサーを用意する（既存のものを使用するか、独自に作成できます）。
エージェントにTracingをインストールします。
メッセージフィルターを設定する（オプション）。
メッセージプロセッサーを機能に追加します。

kotlin

// トレースメッセージの出力先として使用されるロガー/ファイルを定義しています 
val logger = KotlinLogging.logger { }
val outputPath = Path("/path/to/trace.log")

// エージェントを作成しています
val agent = AIAgent(
    promptExecutor = simpleOllamaAIExecutor(),
    llmModel = OllamaModels.Meta.LLAMA_3_2,
) {
    install(Tracing) {

        // トレースイベントを処理するメッセージプロセッサーを設定します
        addMessageProcessor(TraceFeatureMessageLogWriter(logger))
        addMessageProcessor(TraceFeatureMessageFileWriter(
            outputPath,
            { path: Path -> SystemFileSystem.sink(path).buffered() }
        ))
    }
}

メッセージフィルタリング

既存のすべてのイベントを処理することも、特定の基準に基づいて一部を選択することもできます。メッセージフィルターを使用すると、どのイベントを処理するかを制御できます。これは、エージェント実行の特定の側面に焦点を当てるのに役立ちます。

kotlin


val fileWriter = TraceFeatureMessageFileWriter(
    outputPath,
    { path: Path -> SystemFileSystem.sink(path).buffered() }
)

addMessageProcessor(fileWriter)

// LLM関連イベントのみをフィルタリング
fileWriter.setMessageFilter { message ->
    message is LLMCallStartingEvent || message is LLMCallCompletedEvent
}

// ツール関連イベントのみをフィルタリング
fileWriter.setMessageFilter { message -> 
    message is ToolCallStartingEvent ||
           message is ToolCallCompletedEvent ||
           message is ToolValidationFailedEvent ||
           message is ToolCallFailedEvent
}

// ノード実行イベントのみをフィルタリング
fileWriter.setMessageFilter { message -> 
    message is NodeExecutionStartingEvent || message is NodeExecutionCompletedEvent
}

大量のトレースデータ

複雑な戦略を持つエージェントや、長時間の実行を行うエージェントでは、トレースイベントの量が膨大になる可能性があります。イベントの量を管理するために、以下の方法を検討してください。

特定のメッセージフィルターを使用してイベント数を減らします。
バッファリングまたはサンプリング機能を備えたカスタムメッセージプロセッサーを実装します。
ログファイルが肥大化するのを防ぐために、ファイルローテーションを使用します。

依存関係グラフ

Tracing機能には以下の依存関係があります。

Tracing
├── AIAgentPipeline (for intercepting events)
├── TraceFeatureConfig
│   └── FeatureConfig
├── Message Processors
│   ├── TraceFeatureMessageLogWriter
│   │   └── FeatureMessageLogWriter
│   ├── TraceFeatureMessageFileWriter
│   │   └── FeatureMessageFileWriter
│   └── TraceFeatureMessageRemoteWriter
│       └── FeatureMessageRemoteWriter
└── Event Types (from ai.koog.agents.core.feature.model)
    ├── AgentStartingEvent
    ├── AgentCompletedEvent
    ├── AgentExecutionFailedEvent
    ├── StrategyStartingEvent
    ├── StrategyCompletedEvent
    ├── NodeExecutionStartingEvent
    ├── NodeExecutionCompletedEvent
    ├── LLMCallStartingEvent
    ├── LLMCallCompletedEvent
    ├── LLMStreamingStartingEvent
    ├── LLMStreamingFrameReceivedEvent
    ├── LLMStreamingFailedEvent
    ├── LLMStreamingCompletedEvent
    ├── ToolCallStartingEvent
    ├── ToolValidationFailedEvent
    ├── ToolCallFailedEvent
    └── ToolCallCompletedEvent

例とクイックスタート

ロガーへの基本的なトレーシング

kotlin

// ロガーを作成します
val logger = KotlinLogging.logger { }

fun main() {
    runBlocking {
       // トレーシング機能付きエージェントを作成します
       val agent = AIAgent(
          promptExecutor = simpleOllamaAIExecutor(),
          llmModel = OllamaModels.Meta.LLAMA_3_2,
       ) {
          install(Tracing) {
             addMessageProcessor(TraceFeatureMessageLogWriter(logger))
          }
       }

       // エージェントを実行します
       agent.run("Hello, agent!")
    }
}

エラー処理とエッジケース

メッセージプロセッサーがない場合

Tracing機能にメッセージプロセッサーが追加されていない場合、警告がログに記録されます。

Tracing Feature. No feature out stream providers are defined. Trace streaming has no target.

この機能は引き続きイベントを傍受しますが、どこにも処理または出力されません。

リソース管理

メッセージプロセッサーは、適切に解放する必要のあるリソース（ファイルハンドルなど）を保持する場合があります。適切なクリーンアップを確実に行うために、use拡張関数を使用します。

kotlin

// エージェントを作成しています
val agent = AIAgent(
    promptExecutor = simpleOllamaAIExecutor(),
    llmModel = OllamaModels.Meta.LLAMA_3_2,
) {
    val writer = TraceFeatureMessageFileWriter(
        outputPath,
        { path: Path -> SystemFileSystem.sink(path).buffered() }
    )

    install(Tracing) {
        addMessageProcessor(writer)
    }
}
// エージェントを実行します
agent.run(input)
// ブロックが終了すると、ライターは自動的に閉じられます

特定のイベントをファイルにトレースする

kotlin

install(Tracing) {
    
    val fileWriter = TraceFeatureMessageFileWriter(
        outputPath, 
        { path: Path -> SystemFileSystem.sink(path).buffered() }
    )
    addMessageProcessor(fileWriter)
    
    // LLM呼び出しのみをトレースします
    fileWriter.setMessageFilter { message ->
        message is LLMCallStartingEvent || message is LLMCallCompletedEvent
    }
}

特定のイベントをリモートエンドポイントにトレースする

ネットワーク経由でイベントデータを送信する必要がある場合は、リモートエンドポイントへのトレーシングを使用します。一旦開始されると、リモートエンドポイントへのトレーシングは指定されたポート番号で軽量サーバーを起動し、Kotlin Server-Sent Events (SSE)を介してイベントを送信します。

kotlin

// エージェントを作成しています
val agent = AIAgent(
    promptExecutor = simpleOllamaAIExecutor(),
    llmModel = OllamaModels.Meta.LLAMA_3_2,
) {
    val connectionConfig = DefaultServerConnectionConfig(host = host, port = port)
    val writer = TraceFeatureMessageRemoteWriter(
        connectionConfig = connectionConfig
    )

    install(Tracing) {
        addMessageProcessor(writer)
    }
}
// エージェントを実行します
agent.run(input)
// ブロックが終了すると、ライターは自動的に閉じられます

クライアント側では、FeatureMessageRemoteClientを使用してイベントを受信し、逆シリアル化できます。

kotlin

val clientConfig = DefaultClientConnectionConfig(host = host, port = port, protocol = URLProtocol.HTTP)
val agentEvents = mutableListOf<DefinedFeatureEvent>()

val clientJob = launch {
    FeatureMessageRemoteClient(connectionConfig = clientConfig, scope = this).use { client ->
        val collectEventsJob = launch {
            client.receivedMessages.consumeAsFlow().collect { event ->
                // サーバーからイベントを収集
                agentEvents.add(event as DefinedFeatureEvent)

                // エージェント完了時にイベント収集を停止
                if (event is AgentCompletedEvent) {
                    cancel()
                }
            }
        }
        client.connect()
        collectEventsJob.join()
        client.healthCheck()
    }
}

listOf(clientJob).joinAll()

APIドキュメント

Tracing機能は、以下の主要コンポーネントを持つモジュラーアーキテクチャに従います。

Tracing: エージェントパイプライン内のイベントを傍受する主要な機能クラスです。
TraceFeatureConfig: 機能の動作をカスタマイズするための設定クラスです。
Message Processors: トレースイベントを処理し、出力するコンポーネントです。
- TraceFeatureMessageLogWriter: トレースイベントをロガーに書き込みます。
- TraceFeatureMessageFileWriter: トレースイベントをファイルに書き込みます。
- TraceFeatureMessageRemoteWriter: トレースイベントをリモートサーバーに送信します。

サブグラフ

機能

OpenTelemetry

Tracing

機能概要

イベントフロー

設定と初期化

基本的なセットアップ

メッセージフィルタリング

大量のトレースデータ

依存関係グラフ

例とクイックスタート

ロガーへの基本的なトレーシング

エラー処理とエッジケース

メッセージプロセッサーがない場合

リソース管理

特定のイベントをファイルにトレースする

特定のイベントをリモートエンドポイントにトレースする

APIドキュメント

OpenTelemetry

Tracing ​

機能概要 ​

イベントフロー ​

設定と初期化 ​

基本的なセットアップ ​

メッセージフィルタリング ​

大量のトレースデータ ​

依存関係グラフ ​

例とクイックスタート ​

ロガーへの基本的なトレーシング ​

エラー処理とエッジケース ​

メッセージプロセッサーがない場合 ​

リソース管理 ​

特定のイベントをファイルにトレースする ​

特定のイベントをリモートエンドポイントにトレースする ​

APIドキュメント ​

Tracing

機能概要

イベントフロー

設定と初期化

基本的なセットアップ

メッセージフィルタリング

大量のトレースデータ

依存関係グラフ

例とクイックスタート

ロガーへの基本的なトレーシング

エラー処理とエッジケース

メッセージプロセッサーがない場合

リソース管理

特定のイベントをファイルにトレースする

特定のイベントをリモートエンドポイントにトレースする

APIドキュメント