自动插桩 vs 手动插桩

本节将学习：自动插桩的优势和使用场景、手动插桩的必要性和方法、何时使用哪种方式，以及如何混合使用。

自动插桩的优势

自动插桩有什么优势呢？

第一个优势：无需修改代码。 零代码入侵，通过 Agent 自动插桩，适用于现有项目。不需要修改任何代码，就可以获得可观察性。

第二个优势：快速开始。 配置简单，快速获得可观察性，适合快速验证。只需要配置 Agent，就可以开始采集数据。

第三个优势：覆盖广泛。 支持常见的框架和库，自动采集 HTTP、数据库、消息队列等，覆盖大部分场景。例如，Spring Boot 自动插桩可以采集 HTTP 请求、数据库查询等信息。

第四个优势：维护成本低。 不需要维护插桩代码，SDK 更新自动升级，减少维护负担。只需要升级 SDK，就可以获得新的功能。

自动插桩支持哪些框架？ 支持很多框架和库，比如：

• Web 框架：Spring Boot、Express、FastAPI 等
• 数据库：MySQL、PostgreSQL、MongoDB 等
• 消息队列：Kafka、RabbitMQ 等
• HTTP 客户端：OkHttp、Apache HttpClient 等

这就是自动插桩的优势。它让可观察性变得非常简单。

手动插桩的必要性

什么时候需要手动插桩呢？

第一个场景：自定义业务逻辑。 追踪特定业务操作，添加业务相关的属性，自定义 Span 名称和标签。例如，要追踪订单创建的完整流程，需要手动插桩。

第二个场景：自动插桩不支持的场景。 自定义框架或库、第三方 API 调用、复杂的业务逻辑。自动插桩可能不支持这些场景，需要手动插桩。

第三个场景：精细化控制。 控制哪些操作需要追踪，添加自定义的 Metrics，记录业务相关的 Logs。自动插桩可能不够灵活，需要手动插桩。

手动插桩的过程是这样的：在业务逻辑中，手动创建自定义 Span，添加业务属性，记录业务事件，然后导出数据。

代码示例：在订单创建业务逻辑中，可以这样手动插桩：

Span span = tracer.spanBuilder("order.create")
    .setAttribute("order.user_id", request.getUserId())
    .setAttribute("order.total_amount", request.getTotalAmount())
    .startSpan();

这个代码手动创建 Span，添加业务属性。这样就可以追踪订单创建的完整流程，添加业务相关的信息。

自动插桩和手动插桩的对比

让我们对比一下自动插桩和手动插桩。

对比表：

• 代码修改：自动插桩无需修改代码，手动插桩需要修改代码
• 配置复杂度：自动插桩配置简单，手动插桩配置中等
• 覆盖范围：自动插桩覆盖广泛的框架和库，手动插桩覆盖自定义逻辑
• 灵活性：自动插桩灵活性有限，手动插桩灵活性高
• 维护成本：自动插桩维护成本低，手动插桩维护成本中等到高
• 业务属性：自动插桩业务属性有限，手动插桩业务属性完整
• 适用场景：自动插桩适用于通用场景，手动插桩适用于特定业务场景

选择建议：一般来说，优先使用自动插桩，因为它简单、快速、维护成本低。如果需要业务属性或自动插桩不支持，再使用手动插桩。也可以混合使用：自动插桩覆盖通用场景，手动插桩覆盖业务场景。

混合使用策略

最佳实践是什么？ 使用自动插桩 + 手动插桩，混合使用。

第一步：使用自动插桩覆盖通用场景。 HTTP 请求、数据库查询、消息队列等，这些都可以用自动插桩。不需要手动插桩，就可以获得这些信息的追踪。

第二步：使用手动插桩覆盖业务场景。 业务逻辑追踪、业务属性添加、自定义 Metrics 等，这些需要手动插桩。可以在业务逻辑中添加自定义的 Span、Metrics、Logs。

混合使用的示例：HTTP 请求由自动插桩创建 Span，然后在业务逻辑中手动添加业务 Span，数据库查询由自动插桩创建 Span，这样就形成了一个完整的 Trace。

代码示例：在控制器中，HTTP 请求由自动插桩创建 Span，然后在服务中手动添加业务 Span。

这就是混合使用策略。自动插桩覆盖通用场景，手动插桩覆盖业务场景，两者结合，可以获得完整的可观察性。

本节小结

在本节中，我们学习了两种插桩方式：

第一个是自动插桩。 无需修改代码，快速开始，覆盖广泛。它适用于通用场景，维护成本低。

第二个是手动插桩。 精细控制，业务属性，自定义逻辑。它适用于特定业务场景，灵活性高。

最佳实践：自动插桩 + 手动插桩混合使用。自动插桩覆盖通用场景，手动插桩覆盖业务场景。

选择建议：优先使用自动插桩，需要时添加手动插桩。这样可以在简单性和灵活性之间取得平衡。

这就是插桩方式的对比。理解这两种方式的区别和适用场景，是掌握 OpenTelemetry 的关键。

在下一节，我们将深入了解采样策略：如何控制成本和数据完整性。