手动插桩：自定义业务 Span

欢迎回到第 9 章的学习。在上一节，我们学习了消息队列追踪。现在我们要学习手动插桩：自定义业务 Span。

本节将学习：@WithSpan 注解使用、Tracer API 使用、自定义属性、以及错误处理。

@WithSpan 注解使用

@WithSpan 注解是什么？ @WithSpan 注解用于在方法上自动创建 Span，简化手动插桩。

如何使用 @WithSpan 注解呢？

第一步：在方法上添加注解。 在 Service 类的方法上添加 @WithSpan 注解。

第二步：指定 Span 名称。 指定 Span 名称（如 "order.create"）。

第三步：运行应用并测试。 运行应用并测试业务方法。

第四步：查看 Trace。 在 Grafana Tempo 中查看 Trace 数据。

代码示例：

package com.shoehub.orderservice.service;

import io.opentelemetry.instrumentation.annotations.WithSpan;
import org.springframework.stereotype.Service;

@Service
public class OrderService {
    
    @WithSpan("order.create")
    public Order createOrder(OrderRequest request) {
        // Business logic
        return order;
    }
    
    @WithSpan("order.get")
    public Order getOrder(Long id) {
        // Business logic
        return order;
    }
}

@WithSpan 注解的自动 Span 创建功能。

Tracer API 使用

Tracer API 是什么？ Tracer API 提供更精细的控制，可以手动创建和管理 Span。

如何使用 Tracer API 呢？

第一步：注入 Tracer。 在 Service 类中注入 Tracer。

第二步：创建 Span。 使用 tracer.spanBuilder() 创建 Span。

第三步：管理 Scope。 使用 try-with-resources 管理 Scope。

第四步：设置 Span 属性。 设置 Span 属性。

第五步：处理异常。 处理异常，记录错误状态。

代码示例：

package com.shoehub.orderservice.service;

import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.context.Scope;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class OrderService {
    
    @Autowired
    private Tracer tracer;
    
    public Order createOrder(OrderRequest request) {
        Span span = tracer.spanBuilder("order.create")
            .startSpan();
        
        try (Scope scope = span.makeCurrent()) {
            // Business logic
            span.setAttribute("order.amount", request.getAmount());
            return order;
        } catch (Exception e) {
            span.recordException(e);
            span.setStatus(StatusCode.ERROR, e.getMessage());
            throw e;
        } finally {
            span.end();
        }
    }
}

Tracer API 的精细控制功能。

自定义属性

自定义属性是什么？ 自定义属性用于添加业务相关的信息，丰富追踪数据。

如何添加自定义属性呢？

第一步：获取当前 Span。 使用

Span.current()

第二步：添加自定义属性。 使用

span.setAttribute()

第三步：添加不同类型的属性。 添加不同类型的属性（String、Long、Double、Boolean）。

代码示例：

@WithSpan("order.create")
public Order createOrder(OrderRequest request) {
    Span span = Span.current();
    
    // Adding custom attributes
    span.setAttribute("order.id", order.getId());
    span.setAttribute("user.id", request.getUserId());
    span.setAttribute("business.type", "order-creation");
    span.setAttribute("order.amount", request.getAmount());
    span.setAttribute("order.items", request.getItems().size());
    
    return order;
}

可以使用 TraceQL 查询自定义属性。

错误处理

错误处理是什么？ 错误处理用于记录异常信息，标记 Span 状态。

如何处理错误呢？

第一步：捕获异常。 在 try-catch 块中捕获异常。

第二步：记录异常。 使用

span.recordException(e)

第三步：设置错误状态。 使用

span.setStatus(StatusCode.ERROR, e.getMessage())

第四步：重新抛出异常。 如果需要，重新抛出异常。

代码示例：

@WithSpan("order.create")
public Order createOrder(OrderRequest request) {
    Span span = Span.current();
    
    try {
        // Business logic
        return order;
    } catch (Exception e) {
        span.recordException(e);
        span.setStatus(StatusCode.ERROR, e.getMessage());
        throw e;
    }
}

错误处理对于诊断问题非常重要。

本节小结

在本节中，我们学习了手动插桩：自定义业务 Span：

第一个是 @WithSpan 注解。 在方法上自动创建 Span，简化手动插桩。

第二个是 Tracer API。 提供更精细的控制，手动创建和管理 Span。

第三个是自定义属性。 添加业务相关的信息，丰富追踪数据。

第四个是错误处理。 记录异常信息，标记 Span 状态。

手动插桩总结： 手动插桩包括 @WithSpan 注解（自动创建 Span）、Tracer API（精细控制）、自定义属性（业务信息）、错误处理（异常记录）。这些功能组合在一起，构成了灵活的手动插桩能力。

这就是手动插桩：自定义业务 Span。掌握这些功能，可以灵活地追踪业务逻辑。

在下一节，我们将学习 Metrics 收集：自定义业务指标。学习如何使用 Meter API 收集业务指标。