你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Tracer 接口

参考

包:: com.azure.core.util.tracing

Maven 项目:: com.azure:azure-core:1.46.0

public interface Tracer

所有跟踪程序必须实现才能插入 SDK 的协定。

字段摘要

修饰符和类型	字段和描述
static final String	AZ_TRACING_NAMESPACE_KEY 已放弃将 Azure 资源提供程序命名空间传递到跟踪器工厂方法 createTracer(String libraryName, String libraryVersion, String azNamespace, TracingOptions options) Context其键指示上下文包含 Azure 资源提供程序命名空间。
static final String	DIAGNOSTIC_ID_KEY 已放弃使用 extractContext(Function<String,String> headerGetter) 和 injectContext(BiConsumer<String,String> headerSetter, Context context) 进行上下文传播。 Context其指示上下文包含服务调用的“诊断 ID”的键。
static final String	DISABLE_TRACING_KEY 禁用 Context 跟踪与当前上下文关联的请求的键。
static final String	ENTITY_PATH_KEY Context其指示上下文包含实体路径的键。
static final String	HOST_NAME_KEY Context其指示上下文包含主机名的键。
static final String	MESSAGE_ENQUEUED_TIME 已放弃使用 addLink(TracingLink link) 并传递排队时间作为链接的属性。 Context其键指示分区流中最后一个排队消息的时间。
static final String	PARENT_SPAN_KEY 已放弃弃用，转而改用PARENT_TRACE_CONTEXT_KEY，使用它传播整个 io。opentelemetry。上下文 Context其键指示上下文包含父跨度数据。
static final String	PARENT_TRACE_CONTEXT_KEY Context 用于存储跟踪上下文的键。
static final String	SCOPE_KEY 已放弃请改用。makeSpanCurrent(Context context) Context给定 Span 位于当前上下文中的代码范围的键。
static final String	SPAN_BUILDER_KEY 已放弃改用addLink(TracingLink link) 其 Context 键指示当前上下文中的共享范围生成器。
static final String	SPAN_CONTEXT_KEY 其 Context 指示上下文包含消息跨度上下文的键。
static final String	USER_SPAN_NAME_KEY 已放弃请将范围名称传递给 Tracer。start 方法。其 Context 键指示上下文包含所创建的用户跨度的名称。

方法摘要

修饰符和类型	方法和描述
default void	addEvent(String name, Map<String,Object> attributes, OffsetDateTime timestamp) 已放弃使用 addEvent(String name, Map<String,Object> attributes, OffsetDateTime timestamp, Context context) 使用提供的 `timestamp` 和 `attributes`将事件添加到当前范围。
default void	addEvent(String name, Map<String,Object> attributes, OffsetDateTime timestamp, Context context) 使用提供的 `timestamp` 和 `attributes`将事件添加到中`Context`存在的范围。
default void	addLink(Context context) 已放弃 use addLink(TracingLink link) ) } 提供链接多个跟踪范围的方法。
default void	end(int responseCode, Throwable error, Context context) 已放弃 set specific attribute e.g. 显式http_status_code并使用 end(String errorMessage, Throwable throwable, Context context)。完成当前跟踪范围。
abstract void	end(String errorMessage, Throwable throwable, Context context) 在上下文中完成跨度。
default Context	extractContext(String diagnosticId, Context context) 已放弃使用 extractContext(Function<String,String> headerGetter) 从上游中提取跨度的上下文Context。
default Context	extractContext(Function<String,String> headerGetter) 从上游中提取跨度的上下文Context。
default Context	getSharedSpanBuilder(String spanName, Context context) 已放弃改用addLink(TracingLink link) 返回具有中 Context提供的名称的跨度生成器。
default void	injectContext(BiConsumer<String,String> headerSetter, Context context) 注入跟踪上下文。
default boolean	isEnabled() 检查是否启用了跟踪器。
default AutoCloseable	makeSpanCurrent(Context context) 使范围成为当前范围。
abstract void	setAttribute(String key, String value, Context context) 将元数据添加到当前范围。
default void	setAttribute(String key, long value, Context context) 设置 long 属性。
default Context	setSpanName(String spanName, Context context) 已放弃不需要。设置所创建范围的名称。
abstract Context	start(String methodName, Context context) 创建新的跟踪范围。
default Context	start(String spanName, Context context, ProcessKind processKind) 已放弃请改用 start(String methodName, StartSpanOptions options, Context context) 。为 AMQP 调用创建新的跟踪范围。
default Context	start(String methodName, StartSpanOptions options, Context context) 创建新的跟踪范围。

字段详细信息

AZ_TRACING_NAMESPACE_KEY

@Deprecated
public static final String AZ_TRACING_NAMESPACE_KEY

已放弃

将 Azure 资源提供程序命名空间传递到跟踪器工厂方法 createTracer(String libraryName, String libraryVersion, String azNamespace, TracingOptions options)

Context其键指示上下文包含 Azure 资源提供程序命名空间。

DIAGNOSTIC_ID_KEY

@Deprecated
public static final String DIAGNOSTIC_ID_KEY

已放弃

使用 extractContext(Function<String,String> headerGetter) 和 injectContext(BiConsumer<String,String> headerSetter, Context context) 进行上下文传播。

Context其指示上下文包含服务调用的“诊断 ID”的键。

DISABLE_TRACING_KEY

public static final String DISABLE_TRACING_KEY

禁用 Context 跟踪与当前上下文关联的请求的键。

ENTITY_PATH_KEY

public static final String ENTITY_PATH_KEY

Context其指示上下文包含实体路径的键。

HOST_NAME_KEY

public static final String HOST_NAME_KEY

Context其指示上下文包含主机名的键。

MESSAGE_ENQUEUED_TIME

@Deprecated
public static final String MESSAGE_ENQUEUED_TIME

已放弃

使用 addLink(TracingLink link) 并传递排队时间作为链接的属性。

Context其键指示分区流中最后一个排队消息的时间。

PARENT_SPAN_KEY

@Deprecated
public static final String PARENT_SPAN_KEY

已放弃

弃用，转而改用PARENT_TRACE_CONTEXT_KEY，使用它传播整个 io。opentelemetry。上下文

Context其键指示上下文包含父跨度数据。此范围将用作 SDK 创建的所有范围的父范围。

如果在创建范围时未列出跨度数据，则默认将此范围键用作父范围。

PARENT_TRACE_CONTEXT_KEY

public static final String PARENT_TRACE_CONTEXT_KEY

Context 用于存储跟踪上下文的键。此上下文将用作新范围的父上下文，并在传出 HTTP 调用中传播。

SCOPE_KEY

@Deprecated
public static final String SCOPE_KEY

已放弃

请改用。makeSpanCurrent(Context context)

Context给定 Span 位于当前上下文中的代码范围的键。

SPAN_BUILDER_KEY

@Deprecated
public static final String SPAN_BUILDER_KEY

已放弃

改用addLink(TracingLink link)

其 Context 键指示当前上下文中的共享范围生成器。

SPAN_CONTEXT_KEY

public static final String SPAN_CONTEXT_KEY

其 Context 指示上下文包含消息跨度上下文的键。

USER_SPAN_NAME_KEY

@Deprecated
public static final String USER_SPAN_NAME_KEY

已放弃

请将范围名称传递给 Tracer。start 方法。

其 Context 键指示上下文包含所创建的用户跨度的名称。

如果在创建范围时未列出范围名称，则默认使用调用方法的名称。

方法详细信息

addEvent

@Deprecated
public default void addEvent(String name, Map attributes, OffsetDateTime timestamp)

已放弃

使用 addEvent(String name, Map<String,Object> attributes, OffsetDateTime timestamp, Context context)

使用提供的 timestamp 和 attributes将事件添加到当前范围。

如果提供的时间戳不在当前范围范围内，则此 API 不提供任何规范化时间线

支持的属性值包括 String、double、boolean、long、String []、double []、long []。任何其他 Object 值类型和 null 值都将以无提示方式被忽略。

Parameters:

name - 事件的名称。

attributes - 要为事件设置的其他属性。

timestamp - 事件将关联到跨度的即时（UTC）。

addEvent

public default void addEvent(String name, Map attributes, OffsetDateTime timestamp, Context context)

使用提供的 timestamp 和 attributes将事件添加到中Context存在的范围。

如果提供的时间戳不在当前范围范围内，则此 API 不提供任何规范化时间线

支持的属性值包括 String、double、boolean、long、String []、double []、long []。任何其他 Object 值类型和 null 值都将以无提示方式被忽略。

Context span = tracer.start("Cosmos.getItem", Context.NONE);
 tracer.addEvent("trying another endpoint", Collections.singletonMap("endpoint", "westus3"), OffsetDateTime.now(), span);

Parameters:

name - 事件的名称。

attributes - 要为事件设置的其他属性。

timestamp - 事件将关联到跨度的即时（UTC）。

context - 包含事件应关联到的跨度信息的调用元数据。

addLink

@Deprecated
public default void addLink(Context context)

已放弃

use addLink(TracingLink link) ) }

提供链接多个跟踪范围的方法。在批处理操作中用于关联单个批处理下的多个请求。

代码示例

使用跨度上下文信息链接多个跨度

Parameters:

context - 通过调用堆栈传递的其他元数据。

end

@Deprecated
public default void end(int responseCode, Throwable error, Context context)

已放弃

set specific attribute e.g. 显式http_status_code并使用 end(String errorMessage, Throwable throwable, Context context)。

完成当前跟踪范围。

代码示例

使用给定响应状态代码的相应 OpenTelemetry 状态完成上下文中存在的跟踪范围

Parameters:

responseCode - 如果范围位于 HTTP 调用上下文中，则响应状态代码。

error - Throwable 在跨度期间发生的，如果未 null 发生异常，则为。

context - 通过调用堆栈传递的其他元数据。

end

public abstract void end(String errorMessage, Throwable throwable, Context context)

在上下文中完成跨度。

代码示例

以未设置状态完成跟踪范围

Context messageSpan = tracer.start("ServiceBus.message", new StartSpanOptions(SpanKind.PRODUCER), Context.NONE);
 tracer.end(null, null, messageSpan);

使用提供的错误消息完成跟踪范围

Context span = tracer.start("ServiceBus.send", new StartSpanOptions(SpanKind.CLIENT), Context.NONE);
 tracer.end("amqp:not-found", null, span);

使用提供的异常完成跟踪范围

Context sendSpan = tracer.start("ServiceBus.send", new StartSpanOptions(SpanKind.CLIENT), Context.NONE);
 try (AutoCloseable scope = tracer.makeSpanCurrent(sendSpan)) {
     doWork();
 } catch (Throwable ex) {
     throwable = ex;
 } finally {
     tracer.end(null, throwable, sendSpan);
 }

Parameters:

errorMessage - 调用期间发生的错误消息;如果没有错误， null 则为。发生。任何其他非 null 字符串指示错误，并在中 errorMessage提供说明。

throwable - Throwable 在跨度期间发生的，如果未 null 发生异常，则为。

context - 通过调用堆栈传递的其他元数据。

extractContext

@Deprecated
public default Context extractContext(String diagnosticId, Context context)

已放弃

使用 extractContext(Function<String,String> headerGetter)

从上游中提取跨度的上下文Context。

代码示例

从有效的诊断 ID 中提取相应的跨度上下文信息

Parameters:

diagnosticId - 范围跟踪信息的唯一标识符。

context - 通过调用堆栈传递的其他元数据。

Returns:

包含范围上下文的更新 Context 对象。

extractContext

public default Context extractContext(Function headerGetter)

从上游中提取跨度的上下文Context。

代码示例

从有效的诊断 ID 中提取相应的跨度上下文信息

Context parentContext = tracer.extractContext(name -> {
     Object value = messageProperties.get(name);
     return value instanceof String ? (String) value : null;
 });

 StartSpanOptions remoteParentOptions = new StartSpanOptions(SpanKind.CONSUMER)
     .setRemoteParent(parentContext);

 Context spanWithRemoteParent = tracer.start("EventHubs.process", remoteParentOptions, Context.NONE);

 try (AutoCloseable scope = tracer.makeSpanCurrent(spanWithRemoteParent)) {
     doWork();
 } catch (Throwable ex) {
     throwable = ex;
 } finally {
     tracer.end(null, throwable, spanWithRemoteParent);
 }

Parameters:

headerGetter - 范围和 todo 的跟踪信息的唯一标识符。

Returns:

包含范围上下文的更新 Context 对象。

getSharedSpanBuilder

@Deprecated
public default Context getSharedSpanBuilder(String spanName, Context context)

已放弃

改用addLink(TracingLink link)

返回具有中 Context提供的名称的跨度生成器。

代码示例

返回具有所提供范围名称的生成器。

Parameters:

spanName - 为创建的生成器提供范围的名称。

context - 通过调用堆栈传递的其他元数据。

Returns:

包含范围生成器的更新 Context 对象。

injectContext

public default void injectContext(BiConsumer headerSetter, Context context)

注入跟踪上下文。

Context httpSpan = tracer.start("HTTP GET", new StartSpanOptions(SpanKind.CLIENT), methodSpan);
 tracer.injectContext((headerName, headerValue) -> request.setHeader(headerName, headerValue), httpSpan);

 try (AutoCloseable scope = tracer.makeSpanCurrent(httpSpan)) {
     HttpResponse response = getResponse(request);
     httpResponseCode = response.getStatusCode();
 } catch (Throwable ex) {
     throwable = ex;
 } finally {
     tracer.end(httpResponseCode, throwable, httpSpan);
 }

Parameters:

headerSetter - 用于设置上下文的回调。

context - 跟踪上下文实例

isEnabled

public default boolean isEnabled()

检查是否启用了跟踪器。

if (!tracer.isEnabled()) {
     doWork();
 } else {
     Context span = tracer.start("span", Context.NONE);
     try {
         doWork();
     } catch (Throwable ex) {
         throwable = ex;
     } finally {
         tracer.end(null, throwable, span);
     }
 }

Returns:

如果启用跟踪器，则为 true;否则为 false。

makeSpanCurrent

public default AutoCloseable makeSpanCurrent(Context context)

使范围成为当前范围。实现可能会将其放在 ThreadLocal 上。确保始终将 try-with-resource 语句与 makeSpanCurrent 一起使用

Parameters:

context - 具有范围的上下文。

 Context span = tracer.start("EventHubs.process", new StartSpanOptions(SpanKind.CONSUMER), Context.NONE);
 try (AutoCloseable scope = tracer.makeSpanCurrent(span)) {
     doWork();
 } catch (Throwable ex) {
     throwable = ex;
 } finally {
     tracer.end(null, throwable, span);
 }

Returns:

应使用 try-with-resource 语句在同一线程中关闭的 closeable。

setAttribute

public abstract void setAttribute(String key, String value, Context context)

将元数据添加到当前范围。如果在上下文中找不到范围信息，则不添加元数据。

span = tracer.start("EventHubs.process", Context.NONE);
 tracer.setAttribute("bar", "baz", span);

Parameters:

key - 元数据的名称。

value - 元数据的值。

context - 通过调用堆栈传递的其他元数据。

setAttribute

public default void setAttribute(String key, long value, Context context)

设置 long 属性。

Context span = tracer.start("EventHubs.process", Context.NONE);
 tracer.setAttribute("foo", 42, span);

Parameters:

key - 属性名称

value - atteribute 值

context - 跟踪上下文

setSpanName

@Deprecated
public default Context setSpanName(String spanName, Context context)

已放弃

不需要。

设置所创建范围的名称。

代码示例

检索返回的跨度的名称

Parameters:

spanName - 要指定下一个范围的名称。

context - 通过调用堆栈传递的其他元数据。

Returns:

包含返回范围名称的更新 Context 对象。

start

public abstract Context start(String methodName, Context context)

创建新的跟踪范围。

context将检查有关父范围的信息。如果找到父范围，新范围将添加为子级。否则，将创建父范围并将其添加到， context 任何下游 start() 调用都将使用创建的跨度作为父级。

代码示例

使用提供的方法名称和显式父范围启动跟踪范围

// start a new tracing span with given name and parent context implicitly propagated
 // in io.opentelemetry.context.Context.current()

 Throwable throwable = null;
 Context span = tracer.start("keyvault.setsecret", Context.NONE);
 try {
     doWork();
 } catch (Throwable ex) {
     throwable = ex;
 } finally {
     tracer.end(null, throwable, span);
 }

Parameters:

methodName - 触发跨度创建的方法的名称。

context - 通过调用堆栈传递的其他元数据。

Returns:

包含返回的范围的更新 Context 对象。

start

@Deprecated
public default Context start(String spanName, Context context, ProcessKind processKind)

已放弃

请改用 start(String methodName, StartSpanOptions options, Context context) 。

为 AMQP 调用创建新的跟踪范围。

当为 SEND时processKind，在创建的跨度上设置其他请求属性。

当为 MESSAGE时processKind，返回返回的范围的诊断 ID 和范围上下文。

使用远程父级创建新的跟踪范围，并在给定的为时processKindPROCESS返回该范围。

代码示例

使用提供的方法名称和 AMQP 操作 SEND 启动跟踪范围

Parameters:

spanName - 触发跨度创建的方法的名称。

context - 通过调用堆栈传递的其他元数据。

processKind - AMQP 操作类型。

Returns:

包含返回的范围的更新 Context 对象。

start

public default Context start(String methodName, StartSpanOptions options, Context context)

创建新的跟踪范围。

代码示例

使用提供的方法名称和显式父范围启动跟踪范围

// start a new CLIENT tracing span with the given start options and explicit parent context
 StartSpanOptions options = new StartSpanOptions(SpanKind.CLIENT)
     .setAttribute("key", "value");
 Context spanFromOptions = tracer.start("keyvault.setsecret", options, Context.NONE);
 try {
     doWork();
 } catch (Throwable ex) {
     throwable = ex;
 } finally {
     tracer.end(null, throwable, spanFromOptions);
 }

Parameters:

methodName - 触发跨度创建的方法的名称。

options - 跨度创建选项。

context - 通过调用堆栈传递的其他元数据。

Returns:

包含返回的范围的更新 Context 对象。

通过

Tracer 接口

字段摘要

方法摘要

字段详细信息

AZ_TRACING_NAMESPACE_KEY

DIAGNOSTIC_ID_KEY

DISABLE_TRACING_KEY

ENTITY_PATH_KEY

HOST_NAME_KEY

MESSAGE_ENQUEUED_TIME

PARENT_SPAN_KEY

PARENT_TRACE_CONTEXT_KEY

SCOPE_KEY

SPAN_BUILDER_KEY

SPAN_CONTEXT_KEY

USER_SPAN_NAME_KEY

方法详细信息

addEvent

addEvent

addLink

end

end

extractContext

extractContext

getSharedSpanBuilder

injectContext

isEnabled

makeSpanCurrent

setAttribute

setAttribute

setSpanName

start

start

start

适用于

其他资源