3. 属性注入基础：在 Span 上设置属性的 API

属性（Attributes）是 OpenTelemetry 中附加在 Span 上的键值对元数据，用于描述操作的上下文信息，如 HTTP 方法、数据库语句、用户 ID 等。本章聚焦于在 Span 上注入属性的核心 API、数据类型与系统限制。

3.1 核心 API：SetAttribute 与 SetAttributes

OpenTelemetry SDK 为 Span 对象提供了两种属性设置方法，分别适用于单属性注入与批量注入场景。

Python 示例

from opentelemetry import trace

tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("process_order") as span:
    # 单属性注入
    span.set_attribute("order.id", "ORD-12345")
    span.set_attribute("order.amount", 299.99)

    # 批量注入
    attributes = {
        "payment.method": "credit_card",
        "payment.currency": "USD",
        "payment.status": "completed",
    }
    span.set_attributes(attributes)

Go 示例

import "go.opentelemetry.io/otel/attribute"

ctx, span := tracer.Start(ctx, "process_order")
defer span.End()

// 单属性注入
span.SetAttributes(attribute.String("order.id", "ORD-12345"))
span.SetAttributes(attribute.Float64("order.amount", 299.99))

// 批量注入
span.SetAttributes(
    attribute.String("payment.method", "credit_card"),
    attribute.String("payment.currency", "USD"),
    attribute.String("payment.status", "completed"),
)

Java 示例

import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;

Span span = tracer.spanBuilder("process_order").startSpan();

// 单属性注入
span.setAttribute("order.id", "ORD-12345");
span.setAttribute("order.amount", 299.99);

// 批量注入
Attributes attributes = Attributes.builder()
    .put("payment.method", "credit_card")
    .put("payment.currency", "USD")
    .put("payment.status", "completed")
    .build();
span.setAllAttributes(attributes);

span.end();

3.2 属性类型与值限制

OpenTelemetry 规范定义了属性值的合法类型，以及键与值的长度限制。违反限制可能导致数据被静默丢弃或截断。

3.3 属性注入流程与数据流

下图展示了从应用代码调用 set_attribute 到数据最终被导出到后端的数据流与类型校验过程。

3.4 属性命名最佳实践

OpenTelemetry 语义约定（Semantic Conventions）推荐使用点号分隔的命名空间，避免使用大写字母或特殊字符。

• 使用命名空间前缀： http.method、db.system、messaging.system
• 避免保留字符： 键中不应包含 =、&、空格 等 URL 保留字符
• 统一大小写： 全小写 + 下划线分隔，如 order_id 而非 orderId
• 避免动态键名： 不要使用用户输入或运行时生成的字符串作为键名，防止基数爆炸

3.5 常见错误与排查