如何使用Spring Cloud Sleuth

本节将更详细地介绍如何使用Spring Cloud Sleuth。它涵盖了诸如使用 Spring Cloud Sleuth API 或通过注释控制跨度生命周期等主题。我们还介绍了一些Spring Cloud Sleuth最佳实践。

如果您从Spring Cloud Sleuth开始，则在进入本节之前，您可能应该阅读入门指南。

1. 使用春云侦探的 API 跨越生命周期

其模块中的春云侦探核心包含由跟踪器实现的所有必要接口。该项目带有OpenZipkin Brave实现。您可以通过查看来检查跟踪器如何桥接到侦探的 API。apiorg.springframework.cloud.sleuth.brave.bridge

最常用的接口是：

org.springframework.cloud.sleuth.Tracer- 使用跟踪器，可以创建捕获请求关键路径的根跨度。
org.springframework.cloud.sleuth.Span- 跨度是需要启动和停止的单个工作单元。包含计时信息以及事件和标记。

您也可以直接使用跟踪器实现的 API。

让我们看一下以下 Span 生命周期操作。

开始：启动跨度时，将分配其名称并记录开始时间戳。
end：跨度完成（记录跨度的结束时间），如果跨度被采样，则有资格收集（例如到 Zipkin）。
继续：跨度继续，例如在另一个线程中。
使用显式父项创建：您可以创建新的范围并为其设置显式父项。

春云侦探为您创建一个实例。为了使用它，您可以自动连线它。`Tracer`

1.1. 创建和结束跨度

您可以使用手动创建跨度，如以下示例所示：Tracer

// Start a span. If there was a span present in this thread it will become
// the `newSpan`'s parent.
Span newSpan = this.tracer.nextSpan().name("calculateTax");
try (Tracer.SpanInScope ws = this.tracer.withSpan(newSpan.start())) {
    // ...
    // You can tag a span
    newSpan.tag("taxValue", taxValue);
    // ...
    // You can log an event on a span
    newSpan.event("taxCalculated");
}
finally {
    // Once done remember to end the span. This will allow collecting
    // the span to send it to a distributed tracing system e.g. Zipkin
    newSpan.end();
}

在前面的示例中，我们可以看到如何创建跨度的新实例。如果此线程中已存在跨度，则它将成为新跨度的父级。

创建范围后始终清洁。

如果范围包含大于 50 个字符的名称，则该名称将被截断为 50 个字符。你的名字必须明确和具体。大牌会导致延迟问题，有时甚至会导致异常。

1.2. 连续跨度

有时，您不想创建一个新的跨度，但想要继续一个。这种情况的示例可能如下所示：

AOP：如果在达到一个方面之前已经创建了一个跨度，您可能不希望创建新跨度。

要继续跨度，您可以将跨度存储在一个线程中，然后将其传递给另一个线程，如下例所示。

Span spanFromThreadX = this.tracer.nextSpan().name("calculateTax");
try (Tracer.SpanInScope ws = this.tracer.withSpan(spanFromThreadX.start())) {
    executorService.submit(() -> {
        // Pass the span from thread X
        Span continuedSpan = spanFromThreadX;
        // ...
        // You can tag a span
        continuedSpan.tag("taxValue", taxValue);
        // ...
        // You can log an event on a span
        continuedSpan.event("taxCalculated");
    }).get();
}
finally {
    spanFromThreadX.end();
}

1.3. 使用显式父级创建范围

您可能希望开始一个新的跨度，并提供该跨度的显式父级。假设跨度的父级位于一个线程中，并且您希望在另一个线程中启动新的跨度。每当您调用时，它都会创建一个范围来引用当前范围内的范围。可以将范围放在作用域中，然后调用，如以下示例所示：Tracer.nextSpan()Tracer.nextSpan()

// let's assume that we're in a thread Y and we've received
// the `initialSpan` from thread X. `initialSpan` will be the parent
// of the `newSpan`
Span newSpan = null;
try (Tracer.SpanInScope ws = this.tracer.withSpan(initialSpan)) {
    newSpan = this.tracer.nextSpan().name("calculateCommission");
    // ...
    // You can tag a span
    newSpan.tag("commissionValue", commissionValue);
    // ...
    // You can log an event on a span
    newSpan.event("commissionCalculated");
}
finally {
    // Once done remember to end the span. This will allow collecting
    // the span to send it to e.g. Zipkin. The tags and events set on the
    // newSpan will not be present on the parent
    if (newSpan != null) {
        newSpan.end();
    }
}

创建这样的跨度后，您必须完成它。否则不报告（例如向Zipkin报告）。

您还可以使用版本显式提供父跨度。Tracer.nextSpan(Span parentSpan)

2. 命名跨度

选择范围名称并非易事。范围名称应描述操作名称。名称应为低基数，因此不应包含标识符。

由于正在进行大量检测，因此某些跨度名称是人为的：

controller-method-name当由方法名称为controllerMethodName
async对于使用包装和接口完成的异步操作。CallableRunnable
方法批注返回类的简单名称。@Scheduled

幸运的是，对于异步处理，您可以提供显式命名。

2.1.@SpanName注解

您可以使用注释显式命名范围，如以下示例所示：@SpanName

@SpanName("calculateTax")
class TaxCountingRunnable implements Runnable {

    @Override
    public void run() {
        // perform logic
    }

}

在这种情况下，当以下列方式处理时，范围被命名为：calculateTax

Runnable runnable = new TraceRunnable(this.tracer, spanNamer, new TaxCountingRunnable());
Future<?> future = executorService.submit(runnable);
// ... some additional logic ...
future.get();

2.2.toString（）Method

创建单独的类是非常罕见的。通常，创建这些类的匿名实例。不能批注此类类。为了克服这个限制，如果存在noannotation，我们检查类是否具有该方法的自定义实现。RunnableCallable@SpanNametoString()

运行此类代码会导致创建名为 span 的范围，如以下示例所示：calculateTax

Runnable runnable = new TraceRunnable(this.tracer, spanNamer, new Runnable() {
    @Override
    public void run() {
        // perform logic
    }

    @Override
    public String toString() {
        return "calculateTax";
    }
});
Future<?> future = executorService.submit(runnable);
// ... some additional logic ...
future.get();

3. 使用注释管理跨度

使用批注管理跨度有很多很好的理由，包括：

与 API 无关意味着跨度协作。使用批注允许用户添加到跨度，而不需要库依赖跨度 API。这样做可以让 Sleuth 更改其核心 API，以减少对用户代码的影响。
减少了基本跨度操作的表面积。如果没有此功能，则必须使用 span api，该 API 具有可能不正确使用的生命周期命令。通过仅公开范围、标记和日志功能，您可以在不意外中断跨度生命周期的情况下进行协作。
与运行时生成的代码协作。使用Spring Data和Feign等库，接口的实现是在运行时生成的。因此，对象的跨度包装很乏味。现在，您可以提供接口注释和这些接口的参数。

3.1. 创建新跨度

如果不想手动创建局部范围，可以使用注释。此外，我们还提供注释以自动方式添加标签。@NewSpan@SpanTag

现在我们可以考虑一些用法示例。

@NewSpan
void testMethod();

在没有任何参数的情况下批注方法会导致创建一个新范围，其名称等于批注的方法名称。

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

如果在批注中提供值（直接或通过设置参数），则创建的范围会将提供的值作为名称。name

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

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

您可以组合名称和标签。让我们关注后者。在这种情况下，批注方法的参数运行时值的值将成为标记的值。在我们的示例中，标签键是，标签值是。testTagtest

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

您可以在类和接口上放置注释。如果您覆盖接口的方法并为注释提供不同的值，则最具体的值获胜（在本例中为 set）。@NewSpan@NewSpancustomNameOnTestMethod3

3.2. 连续跨度

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

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

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

（请注意，与注释相比，您还可以使用参数添加日志。@NewSpanlog

这样，跨度就会继续，并且：

已创建命名的日志条目。testMethod11.beforetestMethod11.after
如果引发异常，则还会创建日志条目 namedis。testMethod11.afterFailure
创建具有键 of 和值 of 的标记。testTag11test

3.3. 高级标签设置

有 3 种不同的方法可以将标签添加到范围。所有这些都由注释控制。优先级如下：SpanTag

尝试使用类型的 bean 和提供的名称。TagValueResolver
如果尚未提供 Bean 名称，请尝试计算表达式。我们寻找阿豆。默认实现使用 SPEL 表达式解析。重要只能引用 SPEL 表达式中的属性。由于安全约束，不允许方法执行。TagValueExpressionResolver
如果我们找不到任何要计算的表达式，则返回参数的值。toString()

3.3.1. 自定义提取器

以下方法的标记值由接口的实现计算。它的类名必须作为属性的值传递。TagValueResolverresolver

请考虑以下带批注的方法：

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

现在进一步考虑以下 Bean 实现：TagValueResolver

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

前面的两个示例导致将标记值设置为等于。Value from myCustomTagValueResolver

3.3.2. 解析值的表达式

请考虑以下带批注的方法：

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

没有自定义实现会导致计算 SPEL 表达式，并且在跨度上设置了值为 of 的标记。如果要使用其他表达式解析机制，可以创建自己的 Bean 实现。TagValueExpressionResolverhello characters

3.3.3. 使用toString（）方法

请考虑以下带批注的方法：

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

使用值 of 运行上述方法，以设置具有 String 值为的标记。15"15"

4. 接下来要读什么

您现在应该了解如何使用Spring Cloud Sleuth以及应遵循的一些最佳实践。您现在可以继续了解特定的Spring CloudSleuth功能，或者您可以跳过并阅读Spring Cloud Sleuth中可用的集成。

秒客网

如何使用Spring Cloud Sleuth

1. 使用春云侦探的 API 跨越生命周期

1.1. 创建和结束跨度

1.2. 连续跨度

1.3. 使用显式父级创建范围

2. 命名跨度

2.1.@SpanName注解

2.2.toString（）Method

3. 使用注释管理跨度

3.1. 创建新跨度

3.2. 连续跨度

3.3. 高级标签设置

3.3.1. 自定义提取器

3.3.2. 解析值的表达式

3.3.3. 使用toString（）方法

4. 接下来要读什么

相关文章

如何使用Spring Cloud Sleuth

1. 使用春云侦探的 API 跨越生命周期

1.1. 创建和结束跨度

1.2. 连续跨度

1.3. 使用显式父级创建范围

2. 命名跨度

2.1.@SpanName注解

2.2.toString（）Method

3. 使用注释管理跨度

3.1. 创建新跨度

3.2. 连续跨度

3.3. 高级标签设置

3.3.1. 自定义提取器

3.3.2. 解析值的表达式

3.3.3. 使用toString（） 方法

4. 接下来要读什么

相关文章

3.3.3. 使用toString（）方法