Phoenix项目中Span显示问题的分析与解决

问题背景

在Phoenix项目中，开发人员遇到了一个关于Span显示的异常问题。当Span同时包含SpanAttributes.OPENINFERENCE_SPAN_KIND设置为RETRIEVER类型和SpanAttributes.RETRIEVAL_DOCUMENTS属性时，Span的显示会中断，无法正确展示追踪信息。

问题现象

开发人员通过代码调试确认，Span的属性设置逻辑本身没有报错，所有属性都能正确设置。调试过程中可以看到完整的属性集合，包括：

• session.id
• input.value
• input.mime_type
• retrieval.documents
• output.value
• output.mime_type

然而，这些属性在Phoenix的UI界面上却无法正常显示，导致追踪信息丢失。

根本原因分析

经过深入排查，发现问题并非单独由RETRIEVAL_DOCUMENTS属性引起，而是该属性与OPENINFERENCE_SPAN_KIND设置为RETRIEVER类型的组合导致了显示异常。

进一步研究发现，Phoenix对Span属性的处理要求属性必须是扁平化的对象结构。当使用简单的JSON字符串设置RETRIEVAL_DOCUMENTS属性时，系统无法正确解析和显示这些数据。

解决方案

正确的做法是将检索文档的属性以扁平化的方式设置到Span中，具体实现如下：

# 查询Weaviate集合并添加追踪
def query_weaviate(query_text, limit=3):
    # 为查询创建一个Span
    with tracer.start_as_current_span(
        "query_weaviate", openinference_span_kind="retriever"
    ) as span:
        # 设置Span的输入
        span.set_input(query_text)

        # 查询集合
        collection_name = "Question"
        chunks = client.collections.get(collection_name)
        results = chunks.query.near_text(query=query_text, limit=limit)

        # 将检索到的文档设置为Span的属性
        for i, document in enumerate(results.objects):
            span.set_attribute(f"retrieval.documents.{i}.document.id", str(document.uuid))
            span.set_attribute(f"retrieval.documents.{i}.document.metadata", str(document.metadata))
            span.set_attribute(
                f"retrieval.documents.{i}.document.content", str(document.properties)
            )

        return results

这种扁平化的属性设置方式确保了Phoenix能够正确解析和显示Span中的所有信息。每个文档的属性都被明确地分配到不同的键中，而不是打包在一个JSON字符串里。

最佳实践建议

1. 属性扁平化：始终将复杂数据结构拆分为扁平化的属性键值对
2. 明确命名：使用清晰的命名约定，如示例中的retrieval.documents.{index}.document.{field}
3. 类型转换：确保所有值都转换为字符串形式，避免复杂对象直接作为属性值
4. 结构化数据：对于需要保持结构的数据，考虑使用多个相关属性而非单一JSON字符串

结论

Phoenix项目中的Span显示问题源于属性设置方式不符合系统的解析要求。通过采用扁平化的属性结构，可以确保追踪信息能够正确显示。这一解决方案不仅解决了当前问题，也为类似场景下的Span属性设置提供了参考模式。

开发人员在实现追踪功能时，应当注意目标系统的数据处理能力，选择最适合的属性组织方式，以确保追踪信息的完整性和可读性。