LLM 会話履歴コレクション Mode の設定 - ARMS

デフォルトでは、プローブは大規模言語モデル (LLM) やエージェント呼び出しなど、大規模言語モデル (LLM) を含む呼び出し中に会話履歴を記録します。会話履歴のデータ形式は、OpenTelemetry 仕様に準拠しています。このトピックでは、LLM アプリケーションの会話履歴収集の動作を構成する方法について説明します。

さまざまな録画シナリオをサポートするために、ARMS プローブは会話履歴を収集および記録するための次の 3 つのモードをサポートしています。

Span 属性に会話履歴を記録する (デフォルト)。
会話履歴の記録を停止する。
ログに会話履歴を記録する。

構成を調整して、LLM アプリケーションの会話履歴収集の動作を変更し、さまざまな要件を満たすことができます。

前提条件

Python プローブをインストールしたか、Java プローブをインストールしたこと。

フレームワークとプローブのバージョンは、次の要件を満たす必要があります。

Python アプリケーション

コンポーネント/フレームワーク	サポートされているコンポーネントのバージョン	サポートされているシナリオ	必要なプローブのバージョン
OpenAI Python SDK	1.X	ChatCompletion Completion Embedding	2.0.0 以降

Java アプリケーション

コンポーネント/フレームワーク	サポートされているコンポーネントのバージョン	サポートされているシナリオ	必要なプローブのバージョン
OpenAI Java SDK	1.1.0 以降	ChatCompletion Completion Embedding	4.6.0 以降
Spring AI	1.0.0 以降	OpenAI ChatModel ChatClient (デフォルト) ToolManager (デフォルト)	4.6.0 以降
Spring AI Alibaba	1.0.0.3 以降	DashScope ChatModel	4.6.0 以降

例

このトピックでは、関数を含む React Agent 呼び出しの例を示します。LLM アプリケーションは、ツール定義を使用して大規模言語モデルを呼び出します。モデルは tool_call リクエストを返します。アプリケーションがツール呼び出しを完了すると、ツール呼び出しの結果を使用して大規模言語モデルを再度呼び出し、最終的な出力を生成します。次の時系列グラフは、呼び出しプロシージャを示しています。

Span 属性に会話履歴を記録する

収集動作とデータ形式

これはデフォルトの動作です。プローブは、入力メッセージ、出力メッセージ、システム命令、およびツール定義を Span 属性内に JSON 形式で記録します。

属性名	説明	スキーマ	コンテンツの完全性
`gen_ai.input.messages`	入力メッセージ	gen_ai.input.messages	完全に記録
`gen_ai.output.messages`	出力メッセージ	gen_ai.output.messages	完全に記録
`gen_ai.system_instructions`	システム命令	gen_ai.system_instructions	完全に記録
`gen_ai.tool.definitions`	ツール定義	-	type name description

構成

次の環境変数を使用して、この動作を構成できます。
環境変数
値
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT
True
OTEL_INSTRUMENTATION_GENAI_MESSAGE_CONTENT_CAPTURE_STRATEGY
"span-attributes"

Java アプリケーションの場合は、起動コマンドにシステムプロパティを追加することもできます。例:

-Dotel.instrumentation.genai.capture-message-content=true \
-Dotel.instrumentation.genai.message-content.capture-strategy=span-attributes

例

GenAI Client Span 1

プロパティ	値
Span name	`"chat gpt-4"`
`gen_ai.provider.name`	`"openai"`
`gen_ai.operation.name`	`"chat"`
`gen_ai.request.model`	`"gpt-4"`
`gen_ai.request.max_tokens`	`200`
`gen_ai.request.top_p`	`1.0`
`gen_ai.response.id`	`"chatcmpl-9J3uIL87gldCFtiIbyaOvTeYBRA3l"`
`gen_ai.response.model`	`"gpt-4-0613"`
`gen_ai.usage.output_tokens`	`17`
`gen_ai.usage.input_tokens`	`47`
`gen_ai.response.finish_reasons`	`["tool_calls"]`
`gen_ai.input.messages`	`[ { "role": "user", "parts": [ { "type": "text", "content": "Weather in Paris?" } ] } ]`
`gen_ai.output.messages`	`[ { "role": "assistant", "parts": [ { "type": "tool_call", "id": "call_VSPygqKTWdrhaFErNvMV18Yl", "name": "get_weather", "arguments": { "location": "Paris" } } ], "finish_reason": "tool_call" } ]`
`gen_ai.tool.definitions`	`[ { "type": "function", "name": "get_weather", "description": "Get the current temperature for a specific location." } ]`

GenAI Client Span 2

プロパティ	値
Span name	`"chat gpt-4"`
`gen_ai.provider.name`	`"openai"`
`gen_ai.request.model`	`"gpt-4"`
`gen_ai.request.max_tokens`	`200`
`gen_ai.request.top_p`	`1.0`
`gen_ai.response.id`	`"chatcmpl-call_VSPygqKTWdrhaFErNvMV18Yl"`
`gen_ai.response.model`	`"gpt-4-0613"`
`gen_ai.usage.output_tokens`	`52`
`gen_ai.usage.input_tokens`	`97`
`gen_ai.response.finish_reasons`	`["stop"]`
`gen_ai.input.messages`	`[ { "role": "user", "parts": [ { "type": "text", "content": "Weather in Paris?" } ] }, { "role": "assistant", "parts": [ { "type": "tool_call", "id": "call_VSPygqKTWdrhaFErNvMV18Yl", "name": "get_weather", "arguments": { "location": "Paris" } } ] }, { "role": "tool", "parts": [ { "type": "tool_call_response", "id": " call_VSPygqKTWdrhaFErNvMV18Yl", "response": "rainy, 57°F" } ] } ]`
`gen_ai.output.messages`	`[ { "role": "assistant", "parts": [ { "type": "text", "content": "The weather in Paris is currently rainy with a temperature of 57°F." } ], "finish_reason": "stop" } ]`

会話履歴の収集を停止する

収集動作とデータ形式

このモードでは、プローブは入力メッセージ、出力メッセージ、システム命令などの詳細を記録しません。ツール定義については、基本情報のみが JSON 形式で記録されます。

属性名	説明	スキーマ	コンテンツの完全性
`gen_ai.input.messages`	入力メッセージ	gen_ai.input.messages	記録されない
`gen_ai.output.messages`	出力メッセージ	gen_ai.output.messages	記録されない
`gen_ai.system_instructions`	システム命令	gen_ai.system_instructions	記録されない
`gen_ai.tool.definitions`	ツール定義	-	type name

構成

次の環境変数を使用して、この動作を構成できます。
環境変数
値
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT
False
Java アプリケーションの場合は、起動コマンドにシステムプロパティを追加することもできます。例:
```
-Dotel.instrumentation.genai.capture-message-content=false
```

例

GenAI Client Span 1

プロパティ	値
Span name	`"chat gpt-4"`
`gen_ai.provider.name`	`"openai"`
`gen_ai.operation.name`	`"chat"`
`gen_ai.request.model`	`"gpt-4"`
`gen_ai.request.max_tokens`	`200`
`gen_ai.request.top_p`	`1.0`
`gen_ai.response.id`	`"chatcmpl-9J3uIL87gldCFtiIbyaOvTeYBRA3l"`
`gen_ai.response.model`	`"gpt-4-0613"`
`gen_ai.usage.output_tokens`	`17`
`gen_ai.usage.input_tokens`	`47`
`gen_ai.response.finish_reasons`	`["tool_calls"]`
`gen_ai.tool.definitions`	`[ { "type": "function", "name": "get_weather" } ]`

GenAI Client Span 2

プロパティ	値
Span name	`"chat gpt-4"`
`gen_ai.provider.name`	`"openai"`
`gen_ai.request.model`	`"gpt-4"`
`gen_ai.request.max_tokens`	`200`
`gen_ai.request.top_p`	`1.0`
`gen_ai.response.id`	`"chatcmpl-call_VSPygqKTWdrhaFErNvMV18Yl"`
`gen_ai.response.model`	`"gpt-4-0613"`
`gen_ai.usage.output_tokens`	`52`
`gen_ai.usage.input_tokens`	`97`
`gen_ai.response.finish_reasons`	`["stop"]`

ローカルログに会話履歴を記録する

収集動作とデータ形式

このモードでは、基本情報のみが Span 属性に保持されます。プローブは、入力メッセージ、出力メッセージ、システム命令、およびツール定義を単一行のログとして JSON 形式で記録します。ログはローカルログファイルに保存されます。

属性名	説明	スキーマ	コンテンツの完全性
`gen_ai.input.messages`	入力メッセージ	gen_ai.input.messages	完全に記録
`gen_ai.output.messages`	出力メッセージ	gen_ai.output.messages	完全に記録
`gen_ai.system_instructions`	システム命令	gen_ai.system_instructions	完全に記録
`gen_ai.tool.definitions`	ツール定義	-	type name description

デフォルトでは、プローブが起動すると、次の優先順位で最初に使用可能なフォルダを検索し、ログパスとして使用します。

APSARA_APM_AGENT_WORKSPACE_DIR 環境変数を使用してフォルダが指定されている場合、ログは指定されたフォルダの .apsara-apm/{language}/logs サブフォルダに記録されます。
プローブのログフォルダ: /home/admin/.opt/.apsara-apm/{language}/logs
ホームフォルダ: ~/.apsara-apm/{language}/{agent_version}_{agent_commit_id}/logs

アプリケーションが起動すると、プローブはログストレージフォルダを示すログメッセージを標準出力に出力します。フォルダ管理を簡素化するために、APSARA_APM_AGENT_WORKSPACE_DIR 環境変数を使用してフォルダを指定できます。

会話履歴ログファイルは genai_messages_{ip}_{pid}.log 形式で命名されます。最大ログファイルサイズは 256 MB です。このサイズを超えると、ファイルはローテーションされます。ファイルシステムには最新の 2 つのログファイルのみが保持されます。古いファイルは削除されます。

構成

次の環境変数を使用して、この動作を構成できます。
環境変数
値
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT
True
OTEL_INSTRUMENTATION_GENAI_MESSAGE_CONTENT_CAPTURE_STRATEGY
"event"
Java アプリケーションの場合は、起動コマンドにシステムプロパティを追加することもできます。例:
```
-Dotel.instrumentation.genai.capture-message-content=true \
-Dotel.instrumentation.genai.message-content.capture-strategy=event
```

例

GenAI Client Span 1

プロパティ	値
Span name	`"chat gpt-4"`
`gen_ai.provider.name`	`"openai"`
`gen_ai.operation.name`	`"chat"`
`gen_ai.request.model`	`"gpt-4"`
`gen_ai.request.max_tokens`	`200`
`gen_ai.request.top_p`	`1.0`
`gen_ai.response.id`	`"chatcmpl-9J3uIL87gldCFtiIbyaOvTeYBRA3l"`
`gen_ai.response.model`	`"gpt-4-0613"`
`gen_ai.usage.output_tokens`	`17`
`gen_ai.usage.input_tokens`	`47`
`gen_ai.response.finish_reasons`	`["tool_calls"]`

GenAI Client Event 1

spanId は GenAI Client Span 1 に対応します。

{
  "scope": {
    "name": "aliyun.instrumentation.openai",
    "version": "1.0.1"
  },
  "timeUnixNano": 1760080084146812928,
  "severity": "UNSPECIFIED",
  "attributes": {
    "event.name": "gen_ai.client.inference.operation.details",
    "gen_ai.provider.name": "openai",
    "gen_ai.operation.name": "chat",
    "gen_ai.request.model": "gpt-4",
    "gen_ai.request.max_tokens": 200,
    "gen_ai.request.top_p": 1.0,
    "gen_ai.response.id": "chatcmpl-9J3uIL87gldCFtiIbyaOvTeYBRA3l",
    "gen_ai.response.model": "gpt-4-0613",
    "gen_ai.usage.output_tokens": 17,
    "gen_ai.usage.input_tokens": 47,
    "gen_ai.response.finish_reasons": ["tool_calls"],
    "gen_ai.input.messages": "[{\"role\":\"user\",\"parts\":[{\"type\":\"text\",\"content\":\"Weather in Paris?\"}]}]",
    "gen_ai.output.messages": "[{\"role\":\"assistant\",\"parts\":[{\"type\":\"tool_call\",\"id\":\"call_VSPygqKTWdrhaFErNvMV18Yl\",\"name\":\"get_weather\",\"arguments\":{\"location\":\"Paris\"}}],\"finish_reason\":\"tool_call\"}]",
    "gen_ai.tool.definitions": "[{\"type\":\"function\",\"name\":\"get_weather\",\"description\":\"Get the current temperature for a specific location.\"}]"
  },
  "traceId": "0b46a347592ac487ed092ebe802c6818",
  "spanId": "b3c40af8cd1a522c"
}

GenAI Client Span 2

プロパティ	値
Span name	`"chat gpt-4"`
`gen_ai.provider.name`	`"openai"`
`gen_ai.request.model`	`"gpt-4"`
`gen_ai.request.max_tokens`	`200`
`gen_ai.request.top_p`	`1.0`
`gen_ai.response.id`	`"chatcmpl-call_VSPygqKTWdrhaFErNvMV18Yl"`
`gen_ai.response.model`	`"gpt-4-0613"`
`gen_ai.usage.output_tokens`	`52`
`gen_ai.usage.input_tokens`	`97`
`gen_ai.response.finish_reasons`	`["stop"]`

GenAI Client Event 2

spanId は GenAI Client Span 2 に対応します。

{
  "scope": {
    "name": "aliyun.instrumentation.openai",
    "version": "1.0.1"
  },
  "timeUnixNano": 1760080084176812928,
  "severity": "UNSPECIFIED",
  "attributes": {
    "event.name": "gen_ai.client.inference.operation.details",
    "gen_ai.provider.name": "openai",
    "gen_ai.operation.name": "chat",
    "gen_ai.request.model": "gpt-4",
    "gen_ai.request.max_tokens": 200,
    "gen_ai.request.top_p": 1.0,
    "gen_ai.response.id": "chatcmpl-VSPygqKTWdrhaFErNvMV18Yl",
    "gen_ai.response.model": "gpt-4-0613",
    "gen_ai.usage.output_tokens": 52,
    "gen_ai.usage.input_tokens": 97,
    "gen_ai.response.finish_reasons": ["stop"],
    "gen_ai.input.messages": "[{\"role\":\"user\",\"parts\":[{\"type\":\"text\",\"content\":\"Weather in Paris?\"}]},{\"role\":\"assistant\",\"parts\":[{\"type\":\"tool_call\",\"id\":\"call_VSPygqKTWdrhaFErNvMV18Yl\",\"name\":\"get_weather\",\"arguments\":{\"location\": \"Paris\"}}]},{\"role\":\"tool\",\"parts\":[{\"type\":\"tool_call_response\",\"id\":\"call_VSPygqKTWdrhaFErNvMV18Yl\",\"response\":\"rainy, 57°F\"}]}]",
    "gen_ai.output.messages": "[{\"role\":\"assistant\",\"parts\":[{\"type\":\"text\",\"content\":\"The weather in Paris is currently rainy with a temperature of 57°F.\"}],\"finish_reason\":\"sto\"}]"
  },
  "traceId": "0b46a347592ac487ed092ebe802c6818",
  "spanId": "0a706a178bd746c5"
}

SLS に会話履歴を記録する

ローカルログに会話履歴を記録するモードでは、LoongCollector を使用してローカルログを Simple Log Service (SLS) に送信し、さらなる処理と消費を行うことができます。

ステップ 1: LoongCollector のインストール

LoongCollector が環境にすでにインストールされている場合は、このステップをスキップしてください。

環境タイプ	リファレンス
Linux	LoongCollector のインストール (Linux)
Windows	LoongCollector のインストール (Linux)
Kubernetes	LoongCollector のインストール (Kubernetes)

ステップ 2: コレクション構成の作成

Simple Log Service コンソールにログオンし、プロジェクトをクリックして、目的の Logstore を展開します。次に、[データインポート] の横にあるアイコンをクリックし、[JSON - テキストログ] エリアで [今すぐインポート] をクリックします。
既存のマシングループを選択するか、ログが配置されているホストのマシングループを作成します。
コレクション構成を作成します。入力構成で、[ファイルパス] をログフォルダパスに設定します。アプリケーションの起動からの標準出力を確認して、フォルダパスを確認します。処理構成では、JSON 解析を選択します。
データの取得と分析を容易にするために、少なくとも次のインデックスをログに追加します。

説明

ログ収集の詳細については、「ホストからテキストログを収集する」をご参照ください。

ステップ 3: SLS で収集されたログの表示

初期構成を完了すると、数分以内にログが SLS に収集されます。

メッセージ長の制限の調整

長すぎるメッセージによる過剰なリソース使用を防ぐため、プローブはデフォルトで長いメッセージコンテンツを切り捨てます。デフォルトの長さはメッセージあたり 8192 文字です。切り捨てられたメッセージは、...[truncated] 識別子で終わります。例:

[
  {
    "role": "assistant",
    "parts": [
      {
        "type": "text",
        "content": "The weather in Paris...[truncated]"
      }
    ],
    "finish_reason": "stop"
  }
]

構成

次の環境変数を使用して、この動作を構成できます。
環境変数
値
OTEL_INSTRUMENTATION_GENAI_MESSAGE_CONTENT_MAX_LENGTH
8192
Java アプリケーションの場合は、起動コマンドにシステムプロパティを追加することもできます。例:
```
-Dotel.instrumentation.genai.message-content.max-length=8192
```

切り捨てられる可能性のあるメッセージ本文

会話履歴タイプ	メッセージ
`gen_ai.input.messages`	TextPart.content
`gen_ai.output.messages`	TextPart.content
`gen_ai.system_instructions`	TextPart.content

環境変数	値
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT	`True`
OTEL_INSTRUMENTATION_GENAI_MESSAGE_CONTENT_CAPTURE_STRATEGY	`"span-attributes"`

環境変数	値
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT	`False`

環境変数	値
OTEL_INSTRUMENTATION_GENAI_MESSAGE_CONTENT_MAX_LENGTH	8192