11. 使用 Comments 管理 Span

您可以使用各种注释来管理 span。spring-doc.cn

11.1. 基本原理

使用 Comments 管理 span 有很多充分的理由，包括：spring-doc.cn

  • API 不可知的意思是与 span 协作。使用注释允许用户添加到 span，而无需依赖于 span api。 这样做可以让 Sleuth 更改其核心 API，以减少对用户代码的影响。spring-doc.cn

  • 减少了基本跨度操作的表面积。如果没有此功能，您必须使用 span api，该 api 包含可能被错误使用的生命周期命令。 通过仅公开范围、标签和日志功能，您可以进行协作，而不会意外中断 span 生命周期。spring-doc.cn

  • 与运行时生成的代码协作。使用 Spring Data 和 Feign 等库，接口的实现是在运行时生成的。 因此，对象的 span 包装很繁琐。 现在，你可以通过接口和这些接口的参数提供注释。spring-doc.cn

11.2. 创建新的 Span

如果您不想手动创建本地 span，则可以使用 annotation。 此外，我们还提供了 annotation 以自动方式添加标签。@NewSpan@SpanTagspring-doc.cn

现在我们可以考虑一些用法示例。spring-doc.cn

@NewSpan
void testMethod();

在没有任何参数的情况下对方法进行注释会导致创建一个名称等于带注释的方法名称的新 span。spring-doc.cn

@NewSpan("customNameOnTestMethod4")
void testMethod4();

如果在注释中提供值（直接或通过设置参数），则创建的 span 将提供的值作为名称。namespring-doc.cn

// method declaration
@NewSpan(name = "customNameOnTestMethod5")
void testMethod5(@SpanTag("testTag") String param);

// and method execution
this.testBean.testMethod5("test");

您可以组合名称和标签。让我们专注于后者。 在这种情况下，带注释方法的参数 runtime value 的值将成为 tag 的值。 在我们的示例中，标签键为 ，标签值为 。testTagtestspring-doc.cn

@NewSpan(name = "customNameOnTestMethod3")
@Override
public void testMethod3() {
}

您可以将 Comments 放在类和接口上。 如果您覆盖接口的方法并为 Comments 提供不同的值，则最 具体 1 胜 （在这种情况下是 SET）。@NewSpan@NewSpancustomNameOnTestMethod3spring-doc.cn

11.3. 连续跨度

如果要向现有范围添加标记和注释，可以使用注释，如以下示例所示：@ContinueSpanspring-doc.cn

// method declaration
@ContinueSpan(log = "testMethod11")
void testMethod11(@SpanTag("testTag11") String param);

// method execution
this.testBean.testMethod11("test");
this.testBean.testMethod13();

（请注意，与 annotation 相反，您还可以使用 parameter 添加日志。@NewSpanlogspring-doc.cn

这样，跨度就会继续，并且：spring-doc.cn

  • 日志条目 named 和 created。testMethod11.beforetestMethod11.afterspring-doc.cn

  • 如果引发异常，还会创建一个名为testMethod11.afterFailurespring-doc.cn

  • 将创建键为 和 值为 的标签。testTag11testspring-doc.cn

11.4. 高级标签设置

有 3 种不同的方法可以向 Span 添加标签。它们都由 Annotation 控制。 优先级如下：SpanTagspring-doc.cn

  1. 尝试使用 type 和 provided name 的 bean。TagValueResolverspring-doc.cn

  2. 如果未提供 bean 名称，请尝试计算表达式。 我们搜索 bean。 默认实现使用 SPEL 表达式解析。重要您只能从 SPEL 表达式中引用属性。由于安全约束，不允许执行方法。TagValueExpressionResolverspring-doc.cn

  3. 如果找不到任何要计算的表达式，则返回参数的值。toString()spring-doc.cn

11.4.1. 自定义提取器

以下方法的 tag 值由 interface 的实现计算。 它的类名必须作为属性的值传递。TagValueResolverresolverspring-doc.cn

请考虑以下带注释的方法：spring-doc.cn

@NewSpan
public void getAnnotationForTagValueResolver(
        @SpanTag(key = "test", resolver = TagValueResolver.class) String test) {
}

现在进一步考虑以下 bean 实现：TagValueResolverspring-doc.cn

@Bean(name = "myCustomTagValueResolver")
public TagValueResolver tagValueResolver() {
    return parameter -> "Value from myCustomTagValueResolver";
}

前面的两个示例导致将 tag 值设置为等于 。Value from myCustomTagValueResolverspring-doc.cn

11.4.2. 解析值的表达式

请考虑以下带注释的方法：spring-doc.cn

@NewSpan
public void getAnnotationForTagValueExpression(@SpanTag(key = "test",
        expression = "'hello' + ' characters'") String test) {
}

没有自定义 a 的实现会导致对 SPEL 表达式的计算，并且在 span 上设置了值为 的标记。 如果要使用其他表达式解析机制，则可以创建自己的 bean 实现。TagValueExpressionResolver4 charactersspring-doc.cn

11.4.3. 使用 toString（） 方法

请考虑以下带注释的方法：spring-doc.cn

@NewSpan
public void getAnnotationForArgumentToString(@SpanTag("test") Long param) {
}

运行值为 的上述方法会导致设置 String 值为 .15"15"spring-doc.cn