生成式客户端 AI 跨度的语义约定

状态: 开发中

Span

推理

状态:

此跨度代表客户端调用生成式 AI 模型或服务，该模型或服务根据输入提示生成响应或请求工具调用。

跨度名称应为 {gen_ai.operation.name} {gen_ai.request.model}。单个 GenAI 系统和框架的语义约定可能会指定不同的跨度名称格式，并且必须遵循 跨度名称的总体指南。

跨度类型应为 CLIENT，对于表示同一进程中模型调用的跨度，可以设置为 INTERNAL。当被检测的 GenAI 系统通常运行在与其客户端不同的进程中，或者当 GenAI 调用通过已检测的协议（如 HTTP）发生时，建议使用 CLIENT 类型。

**Span 状态**应遵循 记录错误文档。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
gen_ai.operation.name		必需	字符串	正在执行的操作的名称。[1]	chat；generate_content；text_completion
gen_ai.provider.name		必需	字符串	由客户端或服务器仪器识别的生成式 AI 提供商。[2]	openai；gcp.gen_ai；gcp.vertex_ai
error.type		如果操作以错误结束，则条件必需	字符串	描述操作结束的错误类别。[3]	timeout；java.net.UnknownHostException；server_certificate_invalid；500
gen_ai.conversation.id		如果可用，则条件必需	字符串	对话（会话、线程）的唯一标识符，用于在此对话中存储和关联消息。[4]	conv_5j66UpCpwteGg4YSxUnt7lPY
gen_ai.output.type		有条件地必需 [5]	字符串	表示客户端请求的内容类型。[6]	text；json；image
gen_ai.request.choice.count		如果在请求中可用且不等于 1，则条件必需	int	目标候选补全数量。	3
gen_ai.request.model		有条件必需 如果可用。	字符串	正在请求的 GenAI 模型名称。[7]	gpt-4
gen_ai.request.seed		如果适用且请求包含种子，则条件必需	int	具有相同种子值的请求更有可能返回相同的结果。	100
server.port		如果设置了 server.address，则条件必需。	int	GenAI 服务器端口。[8]	80; 8080; 443
gen_ai.request.frequency_penalty		推荐	double	GenAI 请求的频率惩罚设置。	0.1
gen_ai.request.max_tokens		推荐	int	模型为请求生成的最大令牌数。	100
gen_ai.request.presence_penalty		推荐	double	GenAI 请求的存在惩罚设置。	0.1
gen_ai.request.stop_sequences		推荐	string[]	模型将用于停止生成更多令牌的序列列表。	["forest", "lived"]
gen_ai.request.temperature		推荐	double	GenAI 请求的温度设置。	0.0
gen_ai.request.top_k		推荐	double	GenAI 请求的 top_k 采样设置。	1.0
gen_ai.request.top_p		推荐	double	GenAI 请求的 top_p 采样设置。	1.0
gen_ai.response.finish_reasons		推荐	string[]	模型停止生成令牌的原因数组，对应于收到的每个生成。	["stop"]；["stop", "length"]
gen_ai.response.id		推荐	字符串	补全的唯一标识符。	chatcmpl-123
gen_ai.response.model		推荐	字符串	生成响应的模型名称。[9]	gpt-4-0613
gen_ai.usage.input_tokens		推荐	int	GenAI 输入（提示）使用的令牌数。	100
gen_ai.usage.output_tokens		推荐	int	GenAI 响应（补全）使用的令牌数。	180
server.address		推荐	字符串	GenAI 服务器地址。[10]	example.com；10.1.2.80；/tmp/my.sock
gen_ai.input.messages		选择加入	any	作为输入提供给模型的聊天记录。[11]	[   {     “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”,         “result”: “rainy, 57°F”       }     ]   } ]
gen_ai.output.messages		选择加入	any	模型返回的消息，每条消息代表一个特定的模型响应（choice, candidate）。[12]	[   {     “role”: “assistant”,     “parts”: [       {         “type”: “text”,         “content”: “The weather in Paris is currently rainy with a temperature of 57°F."       }     ],     “finish_reason”: “stop”   } ]
gen_ai.system_instructions		选择加入	any	与聊天记录分开提供给 GenAI 模型或代理的系统消息或指令。[13]	[   {     “type”: “text”,     “content”: “You are an Agent that greet users, always use greetings tool to respond”   } ]; [   {     “type”: “text”,     “content”: “You are a language translator."   },   {     “type”: “text”,     “content”: “Your mission is to translate text in English to French."   } ]
gen_ai.tool.definitions		选择加入	any	可供 GenAI 代理或模型使用的源系统工具定义列表。[14]	[   {     “type”: “function”,     “name”: “get_current_weather”,     “description”: “Get the current weather in a given location”,     “parameters”: {       “type”: “object”,       “properties”: {         “location”: {           “type”: “string”,           “description”: “The city and state, e.g. San Francisco, CA”         },         “unit”: {           “type”: “string”,           “enum”: [             “celsius”,             “fahrenheit”           ]         }       },       “required”: [         “location”,         “unit”       ]     }   } ]

[1] gen_ai.operation.name: 如果预定义值之一适用，但特定系统使用不同名称，则建议在特定 GenAI 系统的语义约定中记录它，并在仪器中使用系统特定的名称。如果未记录不同名称，仪器库应使用适用的预定义值。

[2] gen_ai.provider.name: 属性应根据仪器尽可能多的了解来设置，并且可能与实际的模型提供商不同。

通过 OpenAI REST API 和相应的客户端库可以访问包括 Azure OpenAI、Gemini 和 AI 托管平台在内的多个提供商，但它们可能会代理或托管来自不同提供商的模型。

gen_ai.request.model、gen_ai.response.model 和 server.address 属性可能有助于识别实际使用的系统。

gen_ai.provider.name 属性充当一个区分器，用于在 GenAI 语义约定中识别该提供商特定的 GenAI 遥测格式。它应与特定于提供商的属性和信号一致。例如，与 AWS Bedrock 相关的 GenAI 跨度、指标和事件应将 gen_ai.provider.name 设置为 aws.bedrock，并包含适用的 aws.bedrock.* 属性，并且不应包含 openai.* 属性。

[3] error.type: error.type 应匹配生成式 AI 提供商或客户端库返回的错误代码、发生的异常的规范名称或另一个低基数错误标识符。仪器应记录它们报告的错误列表。

[4] gen_ai.conversation.id: 仪器应在可轻松获得给定操作的对话 ID 时填充它，例如

• 当被仪器化的客户端框架管理对话历史时（请参阅 LlamaIndex chat store）

• 当仪器化维护后端会话的 GenAI 客户端库时（请参阅 AWS Bedrock agent sessions，OpenAI Assistant threads）

管理对话历史的应用程序开发人员可以添加对话 ID 到 GenAI 和其他跨度或日志，使用仪器库提供的自定义跨度或日志记录处理器或钩子。

[5] gen_ai.output.type: 适用时，如果请求包含输出格式。

[6] gen_ai.output.type: 当客户端请求特定类型的输出时，应使用此属性。模型可能会返回零个或多个此类型的输出。此属性指定输出模态，而不是实际输出格式。例如，如果请求了图像，则实际输出可能是指向图像文件的 URL。未来的输出格式详细信息可能会在 gen_ai.output.{type}.* 属性中记录。

[7] gen_ai.request.model: 正在请求的 GenAI 模型名称。如果模型由供应商提供，则值必须是请求模型的准确名称。如果模型是经过微调的自定义模型，则该值应比经过微调的基础模型更具体。

[8] server.port: 从客户端观察时，并且通过中间件通信时，server.port 应表示任何中间件（例如代理）后面的服务器端口，如果可用。

[9] gen_ai.response.model: 如果可用。提供响应的 GenAI 模型名称。如果模型由供应商提供，则值必须是实际使用的模型的准确名称。如果模型是经过微调的自定义模型，则该值应比经过微调的基础模型具有更具体的名称。

[10] server.address: 从客户端观察到时，并且在通过中介进行通信时，server.address 应表示任何中介（例如代理）后面的服务器地址，如果可用。

[11] gen_ai.input.messages: 仪器化必须遵循 输入消息 JSON schema。当属性记录在事件上时，它必须以结构化形式记录。当记录在 Span 上时，如果不支持结构化格式，则可能记录为 JSON 字符串，否则应记录为结构化格式。

消息必须按发送给模型的顺序提供。仪器可以提供一种方法供用户过滤或截断输入消息。

有关更多详细信息，请参阅 在属性上记录内容 部分。

[12] gen_ai.output.messages: 仪器化必须遵循 输出消息 JSON schema

每条消息代表模型生成的单个输出选择/候选。每条消息恰好对应一个生成（选择/候选），反之亦然 - 一个选择不能跨越多条消息，或者一条消息不能包含来自多个选择的部分。

当属性记录在事件上时，它必须以结构化形式记录。当记录在跨度上时，如果不支持结构化格式，它可以被记录为 JSON 字符串，否则应以结构化形式记录。

仪器可以提供一种方法供用户过滤或截断输出消息。

有关更多详细信息，请参阅 在属性上记录内容 部分。

[13] gen_ai.system_instructions: 当相应的提供商或 API 允许将系统指令或消息与聊天历史分开提供时，应使用此属性。

作为聊天记录一部分的指令应记录在 gen_ai.input.messages 属性中，而不是此处。

仪器必须遵循 System instructions JSON schema。

当记录在跨度上时，如果不支持结构化格式，它可以被记录为 JSON 字符串，否则应以结构化形式记录。

仪器可以提供一种方法供用户过滤或截断系统指令。

有关更多详细信息，请参阅 在属性上记录内容 部分。

[14] gen_ai.tool.definitions: 此属性的值匹配源系统工具定义格式。

预计它是一个对象数组，其中每个对象代表一个工具定义。如果仪器可用序列化字符串，仪器应尽最大努力将其反序列化为数组。当记录在跨度上时，如果不支持结构化格式，它可以被记录为 JSON 字符串，否则应以结构化形式记录。

由于此属性可能很大，因此不建议默认填充它。仪器可以提供一种启用填充此属性的方法。

error.type 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
_OTHER	当检测不到自定义值时使用的回退错误值。

gen_ai.operation.name 具有以下知名值列表。如果其中之一适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
chat	聊天完成操作，例如 OpenAI Chat API
create_agent	创建 GenAI 代理
embeddings	嵌入操作，例如 OpenAI 创建嵌入 API
execute_tool	执行工具
generate_content	多模态内容生成操作，例如 Gemini 生成内容
invoke_agent	调用 GenAI 代理
text_completion	文本补全操作，例如 OpenAI Completions API (Legacy)

gen_ai.output.type 具有以下知名值列表。如果其中之一适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
image	Image
json	具有已知或未知架构的 JSON 对象
speech	Speech
text	纯文本

gen_ai.provider.name 具有以下知名值列表。如果其中之一适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
anthropic	Anthropic
aws.bedrock	AWS Bedrock
azure.ai.inference	Azure AI Inference
azure.ai.openai	Azure OpenAI
cohere	Cohere
deepseek	DeepSeek
gcp.gemini	Gemini [15]
gcp.gen_ai	任何 Google 生成式 AI 端点 [16]
gcp.vertex_ai	Vertex AI [17]
groq	Groq
ibm.watsonx.ai	IBM Watsonx AI
mistral_ai	Mistral AI
openai	OpenAI
perplexity	Perplexity
x_ai	xAI

[15]: 访问 ‘generativelanguage.googleapis.com’ 端点时使用。也称为 AI Studio API。

[16]: 在特定后端未知时可能使用。

[17]: 访问 ‘aiplatform.googleapis.com’ 端点时使用。

Embeddings

状态:

描述 GenAI embeddings 跨度 - 对生成式 AI 模型或服务的请求，该模型或服务根据输入生成 embeddings。gen_ai.operation.name 应为 embeddings。跨度名称应为 {gen_ai.operation.name} {gen_ai.request.model}。

**Span 类型**应为 CLIENT。

**Span 状态**应遵循 记录错误文档。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
gen_ai.operation.name		必需	字符串	正在执行的操作的名称。[1]	chat；generate_content；text_completion
error.type		如果操作以错误结束，则条件必需	字符串	描述操作结束时发生的错误类型。[2]	timeout；java.net.UnknownHostException；server_certificate_invalid；500
gen_ai.request.model		有条件必需 如果可用。	字符串	正在请求的 GenAI 模型名称。[3]	gpt-4
server.port		如果设置了 server.address，则条件必需。	int	GenAI 服务器端口。[4]	80; 8080; 443
gen_ai.embeddings.dimension.count		推荐	int	输出 embeddings 的预期维度数。	512; 1024
gen_ai.request.encoding_formats		推荐	string[]	在 embeddings 操作中请求的编码格式（如果指定）。[5]	["base64"]；["float", "binary"]
gen_ai.usage.input_tokens		推荐	int	GenAI 输入（提示）使用的令牌数。	100
server.address		推荐	字符串	GenAI 服务器地址。[6]	example.com；10.1.2.80；/tmp/my.sock

[1] gen_ai.operation.name: 如果预定义值之一适用，但特定系统使用不同名称，则建议在特定 GenAI 系统的语义约定中记录它，并在仪器中使用系统特定的名称。如果未记录不同名称，仪器库应使用适用的预定义值。

[2] error.type：error.type 应匹配生成式 AI 提供程序或客户端库返回的错误代码、发生的异常的标准名称或另一个低基数错误标识符。Instrumentations 应记录其报告的错误列表。

[3] gen_ai.request.model: 正在请求的 GenAI 模型名称。如果模型由供应商提供，则值必须是请求模型的准确名称。如果模型是经过微调的自定义模型，则该值应比经过微调的基础模型更具体。

[4] server.port: 从客户端观察时，并且在通过中介进行通信时，server.port 应代表任何中介（例如代理）之后的服务器端口，如果可用。

[5] gen_ai.request.encoding_formats: 在某些 GenAI 系统中，编码格式称为 embedding 类型。此外，某些 GenAI 系统每个请求只接受一种格式。

[6] server.address: 从客户端观察并与中介通信时，server.address 应表示任何中介（例如代理）之后的服务器地址，如果可用。

error.type 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
_OTHER	当检测不到自定义值时使用的回退错误值。

gen_ai.operation.name 具有以下知名值列表。如果其中之一适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
chat	聊天完成操作，例如 OpenAI Chat API
create_agent	创建 GenAI 代理
embeddings	嵌入操作，例如 OpenAI 创建嵌入 API
execute_tool	执行工具
generate_content	多模态内容生成操作，例如 Gemini 生成内容
invoke_agent	调用 GenAI 代理
text_completion	文本补全操作，例如 OpenAI Completions API (Legacy)

执行工具跨度

状态:

描述工具执行跨度。

gen_ai.operation.name 应为 execute_tool。

跨度名称应为 execute_tool {gen_ai.tool.name}。

能够检测工具执行调用的 GenAI 检测应这样做。但是，工具通常由应用程序代码执行。建议应用程序开发人员遵循此语义约定来处理由应用程序代码调用的工具。

Span 类型应为 INTERNAL。

**Span 状态**应遵循 记录错误文档。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
gen_ai.operation.name		必需	字符串	正在执行的操作的名称。[1]	chat；generate_content；text_completion
error.type		如果操作以错误结束，则条件必需	字符串	描述操作结束时发生的错误类型。[2]	timeout；java.net.UnknownHostException；server_certificate_invalid；500
gen_ai.tool.call.id		如果可用，则 Recommended	字符串	工具调用的标识符。	call_mszuSIzqtI65i1wAUOE8w5H4
gen_ai.tool.description		如果可用，则 Recommended	字符串	工具的描述。	将两个数字相乘
gen_ai.tool.name		推荐	字符串	代理使用的工具的名称。	Flights
gen_ai.tool.type		如果可用，则 Recommended	字符串	代理使用的工具的类型 [3]	function；extension；datastore
gen_ai.tool.call.arguments		选择加入	any	传递给工具调用的参数。[4]	{     “location”: “San Francisco?”,     “date”: “2025-10-01” }
gen_ai.tool.call.result		选择加入	any	工具调用返回的结果（如果存在且执行成功）。[5]	{   “temperature_range”: {     “high”: 75,     “low”: 60   },   “conditions”: “sunny” }

[1] gen_ai.operation.name: 如果预定义值之一适用，但特定系统使用不同名称，则建议在特定 GenAI 系统的语义约定中记录它，并在仪器中使用系统特定的名称。如果未记录不同名称，仪器库应使用适用的预定义值。

[2] error.type：error.type 应匹配生成式 AI 提供程序或客户端库返回的错误代码、发生的异常的标准名称或另一个低基数错误标识符。Instrumentations 应记录其报告的错误列表。

[3] gen_ai.tool.type: Extension: 在代理端执行的工具，用于直接调用外部 API，弥合代理与真实世界系统之间的差距。代理端操作是指代理在服务器上或代理控制的环境内执行的操作。Function: 在客户端执行的工具，代理为此类工具生成参数，然后客户端执行逻辑。客户端操作是指用户端或客户端应用程序内执行的操作。Datastore: 代理用于访问和查询结构化或非结构化外部数据的工具，用于检索增强任务或知识更新。

[4] gen_ai.tool.call.arguments: > [!WARNING]

此属性可能包含敏感信息。

预期为对象 - 如果可用的检测对象中包含序列化的字符串，则检测对象应尽最大努力将其反序列化为对象。在跨度上记录时，如果不支持结构化格式，则可能记录为 JSON 字符串，否则应记录为结构化形式。

[5] gen_ai.tool.call.result: > [!WARNING]

此属性可能包含敏感信息。

预期为对象 - 如果可用的检测对象中包含序列化的字符串，则检测对象应尽最大努力将其反序列化为对象。在跨度上记录时，如果不支持结构化格式，则可能记录为 JSON 字符串，否则应记录为结构化形式。

error.type 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
_OTHER	当检测不到自定义值时使用的回退错误值。

gen_ai.operation.name 具有以下知名值列表。如果其中之一适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
chat	聊天完成操作，例如 OpenAI Chat API
create_agent	创建 GenAI 代理
embeddings	嵌入操作，例如 OpenAI 创建嵌入 API
execute_tool	执行工具
generate_content	多模态内容生成操作，例如 Gemini 生成内容
invoke_agent	调用 GenAI 代理
text_completion	文本补全操作，例如 OpenAI Completions API (Legacy)

捕获指令、输入和输出

完整（已缓冲）内容

模型指令、用户消息和模型输出被视为敏感内容，并且通常体积庞大。

由于存储成本高昂、监管要求或需要对操作数据和用户数据强制执行不同的访问模型，因此在遥测数据中记录大量或敏感内容可能会有问题。

OpenTelemetry 检测默认不应捕获它们，但应提供选项供用户选择加入。

应用程序开发人员应根据应用程序的需求和成熟度选择合适的用法模式。

1. [默认] 不记录指令、输入或输出。

2. 使用相应的属性（gen_ai.system_instructions、gen_ai.input.messages、gen_ai.output.messages）在 GenAI 跨度上记录指令、输入和输出。

   这种方法最适合遥测量可控且隐私法规不适用或遥测存储符合这些法规的情况，例如在预生产环境中。

   有关更多详细信息，请参阅 在属性上记录内容 部分。

3. 将内容存储在外部，并在跨度上记录引用。

   这种模式推荐在遥测量是问题或需要安全处理敏感数据的生产环境中。使用外部存储可以实现单独的访问控制。

   有关更多详细信息，请参阅 将内容上传到外部存储 部分。

在属性上记录内容

在 gen_ai.system_instructions、gen_ai.input.messages 和 gen_ai.output.messages 属性中捕获的内容可能会很大。

它可能包含媒体，即使是文本形式，它也可能大于可观测性后端对遥测信封或属性值的限制。

输入和输出属性遵循在 输入 JSON schema 和 输出 JSON schema 中正式定义的通用结构。另请参阅它们在 Python 代码 中的表示。

如果给定语言中的跨度尚未支持结构化属性，则相应的属性值应在跨度上序列化为 JSON 字符串，并在事件上以结构化形式记录。

检测可以提供一个配置选项，允许截断单个消息内容等属性，同时保留 JSON 结构。

将内容上传到外部存储

检测可以支持用户定义的进程内钩子来处理内容上传。

该钩子应独立于控制 gen_ai.system_instructions、gen_ai.input.messages 和 gen_ai.output.messages 捕获的 opt-in 标志运行。

如果支持并配置了此类钩子，则检测应无论跨度采样决策如何，都调用该钩子，使用

• 指令、输入和输出对象，使用此约定中定义的格式，并在它们被序列化为 JSON 字符串之前；
• 跨度实例

钩子实现应能够丰富和修改提供的跨度、指令和消息对象。

如果检测配置为也记录 gen_ai.system_instructions、gen_ai.input.messages 和 gen_ai.output.messages 属性，则应在调用钩子之后进行记录，并应记录在钩子实现中可能被修改的值。

钩子 API 应为通用。应用程序或发行版负责钩子实现，包括

• 同步或异步上传过程，
• 在跨度上记录上传内容的引用，
• 以不同方式处理内容。

应用程序或 OpenTelemetry 发行版也可以在遥测处理管道（进程内或通过收集器）中实现内容上传，基于 gen_ai.system_instructions、gen_ai.input.messages 和 gen_ai.output.messages 属性。鉴于潜在的数据量，建议相应地调整 OpenTelemetry SDK 管道中的批处理和导出设置。

待定：记录外部存储内容的引用的通用方法。

请查看 LLM 调用示例。

流式传输块

待办