你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
Tracer 接口
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。
Context其键指示上下文包含父跨度数据。 |
static final String |
PARENT_TRACE_CONTEXT_KEY
Context 用于存储跟踪上下文的键。 |
static final String |
SCOPE_KEY
已放弃 Context给定 Span 位于当前上下文中的代码范围的键。 |
static final String |
SPAN_BUILDER_KEY
已放弃 其 Context 键指示当前上下文中的共享范围生成器。 |
static final String |
SPAN_CONTEXT_KEY
其 Context 指示上下文包含消息跨度上下文的键。 |
static final String |
USER_SPAN_NAME_KEY
已放弃
请将范围名称传递给 Tracer。
其 Context 键指示上下文包含所创建的用户跨度的名称。 |
方法摘要
字段详细信息
AZ_TRACING_NAMESPACE_KEY
@Deprecated
public static final String AZ_TRACING_NAMESPACE_KEY
已放弃
Context其键指示上下文包含 Azure 资源提供程序命名空间。
DIAGNOSTIC_ID_KEY
@Deprecated
public static final String DIAGNOSTIC_ID_KEY
已放弃
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
已放弃
Context其键指示分区流中最后一个排队消息的时间。
PARENT_SPAN_KEY
@Deprecated
public static final String PARENT_SPAN_KEY
已放弃
Context其键指示上下文包含父跨度数据。 此范围将用作 SDK 创建的所有范围的父范围。
如果在创建范围时未列出跨度数据,则默认将此范围键用作父范围。
PARENT_TRACE_CONTEXT_KEY
public static final String PARENT_TRACE_CONTEXT_KEY
Context 用于存储跟踪上下文的键。 此上下文将用作新范围的父上下文,并在传出 HTTP 调用中传播。
SCOPE_KEY
SPAN_BUILDER_KEY
SPAN_CONTEXT_KEY
public static final String SPAN_CONTEXT_KEY
其 Context 指示上下文包含消息跨度上下文的键。
USER_SPAN_NAME_KEY
@Deprecated
public static final String USER_SPAN_NAME_KEY
已放弃
其 Context 键指示上下文包含所创建的用户跨度的名称。
如果在创建范围时未列出范围名称,则默认使用调用方法的名称。
方法详细信息
addEvent
@Deprecated
public default void addEvent(String name, Map
已放弃
使用提供的 timestamp
和 attributes
将事件添加到当前范围。
如果提供的时间戳不在当前范围范围内,则此 API 不提供任何规范化时间线
支持的属性值包括 String、double、boolean、long、String []、double []、long []。 任何其他 Object 值类型和 null 值都将以无提示方式被忽略。
Parameters:
addEvent
public default void addEvent(String name, Map
使用提供的 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:
addLink
@Deprecated
public default void addLink(Context context)
已放弃
提供链接多个跟踪范围的方法。 在批处理操作中用于关联单个批处理下的多个请求。
代码示例
使用跨度上下文信息链接多个跨度
Parameters:
end
@Deprecated
public default void end(int responseCode, Throwable error, Context context)
已放弃
完成当前跟踪范围。
代码示例
使用给定响应状态代码的相应 OpenTelemetry 状态完成上下文中存在的跟踪范围
Parameters:
null
发生异常,则为 。
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:
null
则为 。
发生。 任何其他非 null 字符串指示错误,并在 中 errorMessage
提供说明。
null
发生异常,则为 。
extractContext
@Deprecated
public default Context extractContext(String diagnosticId, Context context)
已放弃
从 上游 中提取跨度的上下文Context。
代码示例
从有效的诊断 ID 中提取相应的跨度上下文信息
Parameters:
Returns:
extractContext
public default Context extractContext(Function
从 上游 中提取跨度的上下文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:
Returns:
getSharedSpanBuilder
@Deprecated
public default Context getSharedSpanBuilder(String spanName, Context context)
已放弃
返回具有 中 Context提供的名称的跨度生成器。
代码示例
返回具有所提供范围名称的生成器。
Parameters:
Returns:
injectContext
public default void injectContext(BiConsumer
注入跟踪上下文。
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:
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:
makeSpanCurrent
public default AutoCloseable makeSpanCurrent(Context context)
使范围成为当前范围。 实现可能会将其放在 ThreadLocal 上。 确保始终将 try-with-resource 语句与 makeSpanCurrent 一起使用
Parameters:
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:
setAttribute
public abstract void setAttribute(String key, String value, Context context)
将元数据添加到当前范围。 如果在上下文中找不到范围信息,则不添加元数据。
span = tracer.start("EventHubs.process", Context.NONE);
tracer.setAttribute("bar", "baz", span);
Parameters:
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:
setSpanName
@Deprecated
public default Context setSpanName(String spanName, Context context)
已放弃
设置所创建范围的名称。
代码示例
检索返回的跨度的名称
Parameters:
Returns:
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:
Returns:
start
@Deprecated
public default Context start(String spanName, Context context, ProcessKind processKind)
已放弃
为 AMQP 调用创建新的跟踪范围。
context
将检查 有关父范围的信息。 如果找到父范围,新范围将添加为子级。 否则,将创建父范围并将其添加到 , context
任何下游 start()
调用都将使用创建的跨度作为父级。
当 为 SEND时processKind
,在创建的跨度上设置其他请求属性。
当 为 MESSAGE时processKind
,返回返回的范围的诊断 ID 和范围上下文。
使用远程父级创建新的跟踪范围,并在给定的 为 时processKind
PROCESS返回该范围。
代码示例
使用提供的方法名称和 AMQP 操作 SEND 启动跟踪范围
Parameters:
Returns:
start
public default Context start(String methodName, StartSpanOptions options, Context context)
创建新的跟踪范围。
context
将检查 有关父范围的信息。 如果找到父范围,新范围将添加为子级。 否则,将创建父范围并将其添加到 , context
任何下游 start()
调用都将使用创建的跨度作为父级。
代码示例
使用提供的方法名称和显式父范围启动跟踪范围
// 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:
Returns: