4. Span 的生命周期：Span 创建、属性设置、事件记录、状态设置、Span 结束

Span 是链路追踪的基本工作单元，代表分布式系统中一个具名、有时间范围的操作。理解 Span 的生命周期是正确埋点、避免数据丢失或语义错误的前提。一个完整的 Span 从创建到结束，依次经历以下五个阶段：创建、属性设置、事件记录、状态设置、结束。

4.1 Span 生命周期总览

下图展示了 Span 从出生到销毁的完整状态流转，以及每个阶段可执行的操作：

4.2 Span 创建

Span 的创建是链路追踪的起点。在 OpenTelemetry Go SDK 中，通过 Tracer 对象的 Start() 方法创建 Span。创建时需要指定 Span 名称，并可选传入父 Span 上下文来建立父子关系。

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

// 获取 Tracer
tracer := otel.Tracer("shop-service")

// 创建 Span（无父 Span，成为根 Span）
ctx, span := tracer.Start(ctx, "process-order")
defer span.End()

4.3 属性设置

属性（Attributes）是 Span 的键值对元数据，用于描述操作的上下文信息，如请求 ID、用户 ID、数据库表名、HTTP 状态码等。属性应在 Span 活跃期间尽早设置，以便在分析时提供完整上下文。

// 设置单个属性
span.SetAttributes(attribute.String("user.id", "u-10086"))
span.SetAttributes(attribute.Int("http.status_code", 200))

// 批量设置属性（推荐，减少调用次数）
span.SetAttributes(
    attribute.String("db.system", "postgresql"),
    attribute.String("db.statement", "SELECT * FROM orders"),
    attribute.Int("db.rows_affected", 42),
)

4.4 事件记录

事件（Events）是 Span 时间轴上的带时间戳的标注，用于记录操作过程中发生的特定时刻，如异常抛出、缓存命中、外部调用开始/结束等。每个事件包含名称和可选的属性集合。

// 记录简单事件
span.AddEvent("cache-miss")

// 记录带属性的事件
span.AddEvent("exception", 
    attribute.String("exception.type", "TimeoutError"),
    attribute.String("exception.message", "connection timeout after 5s"),
)

// 记录带时间戳的事件（使用 SpanContext 时间）
span.AddEvent("retry-attempt", 
    attribute.Int("attempt", 2),
    attribute.String("status", "pending"),
)

4.5 状态设置

Span 状态（Status）表示操作的整体结果。OpenTelemetry 定义了三种状态码：Unset（默认）、Ok（成功）、Error（失败）。状态应在 Span 结束前设置，通常放在操作逻辑的末尾。

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

// 操作成功
span.SetStatus(codes.Ok, "order processed successfully")

// 操作失败
span.SetStatus(codes.Error, "database connection failed")

// 不显式设置状态时，默认为 Unset（表示未明确指定）

4.6 Span 结束

End() 是 Span 生命周期的终点。调用 End() 后，Span 会被标记为完成，其开始时间和结束时间被固定，所有属性、事件、状态被冻结并准备导出。在 Go 中，通常使用 defer span.End() 确保 Span 在函数退出时自动结束。

func ProcessOrder(ctx context.Context, orderID string) error {
    tracer := otel.Tracer("order-service")
    ctx, span := tracer.Start(ctx, "process-order")
    defer span.End()  // 确保函数退出时 Span 结束

    // 设置属性
    span.SetAttributes(attribute.String("order.id", orderID))

    // 业务逻辑
    if err := validateOrder(orderID); err != nil {
        span.SetStatus(codes.Error, "validation failed")
        span.AddEvent("order-validation-error", 
            attribute.String("error", err.Error()))
        return err
    }

    // 处理订单...
    span.AddEvent("order-validated")
    span.SetStatus(codes.Ok, "order processed")
    return nil
}

4.7 完整生命周期示例

以下代码展示了 Span 五个阶段的完整使用模式：

func HandleHTTPRequest(ctx context.Context, req *http.Request) {
    tracer := otel.Tracer("api-gateway")
    ctx, span := tracer.Start(ctx, "handle-request")
    defer span.End()

    // 阶段1：创建后立即设置属性
    span.SetAttributes(
        attribute.String("http.method", req.Method),
        attribute.String("http.url", req.URL.String()),
        attribute.String("user.agent", req.UserAgent()),
    )

    // 阶段2：记录事件
    span.AddEvent("request-received")

    // 模拟业务处理
    result, err := processPayment(ctx, req)
    if err != nil {
        // 阶段3：记录错误事件
        span.AddEvent("payment-error", 
            attribute.String("error.message", err.Error()))
        // 阶段4：设置错误状态
        span.SetStatus(codes.Error, "payment failed")
        http.Error(w, "Internal Error", 500)
        return
    }

    // 阶段5：设置成功状态
    span.AddEvent("payment-success")
    span.SetStatus(codes.Ok, "payment completed")
    // defer span.End() 自动执行，Span 结束
}