Partilhar via

Tracer Interface

  • Referência
Pacote:
com.azure.core.util.tracing
Artefato Maven:
com.azure:azure-core:1.46.0

public interface Tracer

Contrato que todos os rastreadores devem implementar para serem conectáveis ao SDK.

Resumo do campo

Modificador e tipo Campo e descrição
static final String AZ_TRACING_NAMESPACE_KEY

Preterido

Passar o Namespace do Provedor de Recursos do Azure para o método de fábrica do Tracer createTracer(String libraryName, String libraryVersion, String azNamespace, TracingOptions options)

Chave para Context a qual indica que o contexto contém o namespace do provedor de recursos do Azure.
static final String DIAGNOSTIC_ID_KEY

Preterido

Chave para Context a qual indica que o contexto contém uma "ID de diagnóstico" para a chamada de serviço.
static final String DISABLE_TRACING_KEY

Chave para Context a qual desabilita o rastreamento para a solicitação associada ao contexto atual.
static final String ENTITY_PATH_KEY

Chave para Context a qual indica que o contexto contém um caminho de entidade.
static final String HOST_NAME_KEY

Chave para Context a qual indica que o contexto contém o nome do host.
static final String MESSAGE_ENQUEUED_TIME

Preterido

Use addLink(TracingLink link) e passe o tempo enfileirado como um atributo no link.

Chave para Context a qual indica a hora da última mensagem enfileirada no fluxo da partição.
static final String PARENT_SPAN_KEY

Preterido

Preterido em favor de PARENT_TRACE_CONTEXT_KEY, use-o para propagar a E/S completa.opentelemetry.Contexto

Chave para Context a qual indica que o contexto contém dados de span pai.
static final String PARENT_TRACE_CONTEXT_KEY

Context para armazenar o contexto de rastreamento.
static final String SCOPE_KEY

Preterido

Chave para Context o escopo do código em que o span fornecido está no contexto atual.
static final String SPAN_BUILDER_KEY

Preterido

use addLink(TracingLink link) em vez disso

Chave para Context a qual indica o construtor de intervalo compartilhado que está no Contexto atual.
static final String SPAN_CONTEXT_KEY

Chave para Context a qual indica que o contexto contém um contexto de intervalo de mensagens.
static final String USER_SPAN_NAME_KEY

Preterido

passe o nome do intervalo para o Tracer.métodos start.

Chave para Context a qual indica que o contexto contém o nome para os intervalos de usuário criados.

Resumo do método

Modificador e tipo Método e descrição
default void addEvent(String name, Map<String,Object> attributes, OffsetDateTime timestamp)

Preterido

Adiciona um evento ao intervalo atual com o fornecido timestamp e attributes.
default void addEvent(String name, Map<String,Object> attributes, OffsetDateTime timestamp, Context context)

Adiciona um evento ao intervalo presente no Context com o fornecido timestamp e attributes.
default void addLink(Context context)

Preterido

Fornece uma maneira de vincular vários intervalos de rastreamento.
default void end(int responseCode, Throwable error, Context context)

Preterido

definir atributo específico e.g. http_status_code explicitamente e use end(String errorMessage, Throwable throwable, Context context).

Conclui o intervalo de rastreamento atual.
abstract void end(String errorMessage, Throwable throwable, Context context)

Conclui o intervalo no contexto.
default Context extractContext(String diagnosticId, Context context)

Preterido

Extrai o contexto do intervalo de Context upstream.
default Context extractContext(Function<String,String> headerGetter)

Extrai o contexto do intervalo de Context upstream.
default Context getSharedSpanBuilder(String spanName, Context context)

Preterido

use addLink(TracingLink link) em vez disso

Retorna um construtor de intervalos com o nome fornecido em Context.
default void injectContext(BiConsumer<String,String> headerSetter, Context context)

Injeta o contexto de rastreamento.
default boolean isEnabled()

Verifica se o rastreador está habilitado.
default AutoCloseable makeSpanCurrent(Context context)

Torna a extensão atual.
abstract void setAttribute(String key, String value, Context context)

Adiciona metadados ao intervalo atual.
default void setAttribute(String key, long value, Context context)

Define um atributo longo.
default Context setSpanName(String spanName, Context context)

Preterido

não é necessário.

Define o nome para intervalos criados.
abstract Context start(String methodName, Context context)

Cria um novo intervalo de rastreamento.
default Context start(String spanName, Context context, ProcessKind processKind)

Preterido

Cria um novo intervalo de rastreamento para chamadas AMQP.
default Context start(String methodName, StartSpanOptions options, Context context)

Cria um novo intervalo de rastreamento.

Detalhes do campo

AZ_TRACING_NAMESPACE_KEY

@Deprecated
public static final String AZ_TRACING_NAMESPACE_KEY

Preterido

Passar o Namespace do Provedor de Recursos do Azure para o método de fábrica do Tracer createTracer(String libraryName, String libraryVersion, String azNamespace, TracingOptions options)

Chave para Context a qual indica que o contexto contém o namespace do provedor de recursos do Azure.

DIAGNOSTIC_ID_KEY

@Deprecated
public static final String DIAGNOSTIC_ID_KEY

Preterido

Chave para Context a qual indica que o contexto contém uma "ID de diagnóstico" para a chamada de serviço.

DISABLE_TRACING_KEY

public static final String DISABLE_TRACING_KEY

Chave para Context a qual desabilita o rastreamento para a solicitação associada ao contexto atual.

ENTITY_PATH_KEY

public static final String ENTITY_PATH_KEY

Chave para Context a qual indica que o contexto contém um caminho de entidade.

HOST_NAME_KEY

public static final String HOST_NAME_KEY

Chave para Context a qual indica que o contexto contém o nome do host.

MESSAGE_ENQUEUED_TIME

@Deprecated
public static final String MESSAGE_ENQUEUED_TIME

Preterido

Use addLink(TracingLink link) e passe o tempo enfileirado como um atributo no link.

Chave para Context a qual indica a hora da última mensagem enfileirada no fluxo da partição.

PARENT_SPAN_KEY

@Deprecated
public static final String PARENT_SPAN_KEY

Preterido

Preterido em favor de PARENT_TRACE_CONTEXT_KEY, use-o para propagar a E/S completa.opentelemetry.Contexto

Chave para Context a qual indica que o contexto contém dados de span pai. Esse intervalo será usado como o intervalo pai para todos os intervalos que o SDK cria.

Se nenhum dado de span for listado quando o intervalo for criado, o padrão será usar essa chave de span como o intervalo pai.

PARENT_TRACE_CONTEXT_KEY

public static final String PARENT_TRACE_CONTEXT_KEY

Context para armazenar o contexto de rastreamento. Esse contexto será usado como um contexto pai para novos intervalos e propagado em chamadas HTTP de saída.

SCOPE_KEY

@Deprecated
public static final String SCOPE_KEY

Preterido

Chave para Context o escopo do código em que o span fornecido está no contexto atual.

SPAN_BUILDER_KEY

@Deprecated
public static final String SPAN_BUILDER_KEY

Preterido

use addLink(TracingLink link) em vez disso

Chave para Context a qual indica o construtor de intervalo compartilhado que está no Contexto atual.

SPAN_CONTEXT_KEY

public static final String SPAN_CONTEXT_KEY

Chave para Context a qual indica que o contexto contém um contexto de intervalo de mensagens.

USER_SPAN_NAME_KEY

@Deprecated
public static final String USER_SPAN_NAME_KEY

Preterido

passe o nome do intervalo para o Tracer.métodos start.

Chave para Context a qual indica que o contexto contém o nome para os intervalos de usuário criados.

Se nenhum nome de intervalo for listado quando o intervalo for criado, o padrão será usar o nome do método de chamada.

Detalhes do método

addEvent

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

Preterido

Adiciona um evento ao intervalo atual com o fornecido timestamp e attributes.

Essa API não fornecerá nenhuma normalização se os carimbos de data/hora fornecidos estiverem fora do intervalo do intervalo atual linha do tempo

Os valores de atributo com suporte incluem String, double, boolean, long, String [], double [], long []. Qualquer outro tipo de valor object e valores nulos serão ignorados silenciosamente.

Parameters:

name - o nome do evento.
attributes - os atributos adicionais a serem definidos para o evento.
timestamp - O instante, em UTC, no qual o evento será associado ao intervalo.

addEvent

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

Adiciona um evento ao intervalo presente no Context com o fornecido timestamp e attributes.

Essa API não fornecerá nenhuma normalização se os carimbos de data/hora fornecidos estiverem fora do intervalo do intervalo atual linha do tempo

Os valores de atributo com suporte incluem String, double, boolean, long, String [], double [], long []. Qualquer outro tipo de valor object e valores nulos serão ignorados silenciosamente.

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

Parameters:

name - o nome do evento.
attributes - os atributos adicionais a serem definidos para o evento.
timestamp - O instante, em UTC, no qual o evento será associado ao intervalo.
context - os metadados de chamada que contêm informações do intervalo ao qual o evento deve ser associado.

addLink

@Deprecated
public default void addLink(Context context)

Preterido

Fornece uma maneira de vincular vários intervalos de rastreamento. Usado em operações de envio em lote para relacionar várias solicitações em um único lote.

Exemplos de código

Vincular vários intervalos usando suas informações de contexto de intervalo

Parameters:

context - Metadados adicionais que são passados pela pilha de chamadas.

end

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

Preterido

definir atributo específico e.g. http_status_code explicitamente e use end(String errorMessage, Throwable throwable, Context context).

Conclui o intervalo de rastreamento atual.

Exemplos de código

Conclui o intervalo de rastreamento presente no contexto, com o status OpenTelemetry correspondente para a resposta fornecida status código

Parameters:

responseCode - Resposta status código se o intervalo estiver em um contexto de chamada HTTP.
error - Throwable que ocorreu durante o intervalo ou null se nenhuma exceção ocorreu.
context - Metadados adicionais que são passados pela pilha de chamadas.

end

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

Conclui o intervalo no contexto.

Exemplos de código

Conclui o intervalo de rastreamento com status não status

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

Conclui o intervalo de rastreamento com a mensagem de erro fornecida

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

Conclui o intervalo de rastreamento com exceção fornecida

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 - A mensagem de erro que ocorreu durante a chamada ou null se nenhum erro. Ocorreu. Qualquer outra cadeia de caracteres não nula indica um erro com a descrição fornecida em errorMessage.
throwable - Throwable que ocorreu durante o intervalo ou null se nenhuma exceção ocorreu.
context - Metadados adicionais que são passados pela pilha de chamadas.

extractContext

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

Preterido

Extrai o contexto do intervalo de Context upstream.

Exemplos de código

Extrai as informações de contexto de intervalo correspondentes de uma ID de diagnóstico válida

Parameters:

diagnosticId - Identificador exclusivo para as informações de rastreamento do intervalo.
context - Metadados adicionais que são passados pela pilha de chamadas.

Returns:

O objeto atualizado Context que contém o contexto de intervalo.

extractContext

public default Context extractContext(Function headerGetter)

Extrai o contexto do intervalo de Context upstream.

Exemplos de código

Extrai as informações de contexto de intervalo correspondentes de uma ID de diagnóstico válida

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 - Identificador exclusivo para as informações de rastreamento do intervalo e do todo.

Returns:

O objeto atualizado Context que contém o contexto de intervalo.

getSharedSpanBuilder

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

Preterido

use addLink(TracingLink link) em vez disso

Retorna um construtor de intervalos com o nome fornecido em Context.

Exemplos de código

Retorna um construtor com o nome de intervalo fornecido.

Parameters:

spanName - Nome para dar o intervalo para o construtor criado.
context - Metadados adicionais que são passados pela pilha de chamadas.

Returns:

O objeto atualizado Context que contém o construtor de intervalos.

injectContext

public default void injectContext(BiConsumer headerSetter, Context context)

Injeta o contexto de rastreamento.

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 - retorno de chamada com o qual definir o contexto.
context - instância de contexto de rastreamento

isEnabled

public default boolean isEnabled()

Verifica se o rastreador está habilitado.

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 se o rastreador estiver habilitado; caso contrário, false.

makeSpanCurrent

public default AutoCloseable makeSpanCurrent(Context context)

Torna a extensão atual. As implementações podem colocá-lo no ThreadLocal. Use sempre a instrução try-with-resource com makeSpanCurrent

Parameters:

context - Contexto com span. 
 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:

Pode ser fechado no mesmo thread com a instrução try-with-resource.

setAttribute

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

Adiciona metadados ao intervalo atual. Se nenhuma informação de intervalo for encontrada no contexto, nenhum metadado será adicionado.

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

Parameters:

key - Nome dos metadados.
value - Valor dos metadados.
context - Metadados adicionais que são passados pela pilha de chamadas.

setAttribute

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

Define um atributo longo.

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

Parameters:

key - nome do atributo
value - valor atteribute
context - contexto de rastreamento

setSpanName

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

Preterido

não é necessário.

Define o nome para intervalos criados.

Exemplos de código

Recuperar o nome do intervalo retornado

Parameters:

spanName - Nome para dar o próximo intervalo.
context - Metadados adicionais que são passados pela pilha de chamadas.

Returns:

O objeto atualizado Context que contém o nome do intervalo retornado.

start

public abstract Context start(String methodName, Context context)

Cria um novo intervalo de rastreamento.

O context será verificado para obter informações sobre um intervalo pai. Se um intervalo pai for encontrado, o novo intervalo será adicionado como um filho. Caso contrário, o intervalo pai será criado e adicionado ao e todas as context chamadas downstream start() usarão o intervalo criado como o pai.

Exemplos de código

Inicia um intervalo de rastreamento com o nome do método fornecido e o intervalo pai explícito

// 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 - Nome do método que dispara a criação do intervalo.
context - Metadados adicionais que são passados pela pilha de chamadas.

Returns:

O objeto atualizado Context que contém o intervalo retornado.

start

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

Preterido

Cria um novo intervalo de rastreamento para chamadas AMQP.

O context será verificado para obter informações sobre um intervalo pai. Se um intervalo pai for encontrado, o novo intervalo será adicionado como um filho. Caso contrário, o intervalo pai será criado e adicionado ao e todas as context chamadas downstream start() usarão o intervalo criado como o pai.

Define atributos de solicitação adicionais no intervalo criado quando processKind é SEND.

Retorna a ID de diagnóstico e o contexto de intervalo do intervalo retornado quando processKind é MESSAGE.

Cria um novo intervalo de rastreamento com pai remoto e retorna esse escopo quando o fornecido é processKindPROCESS.

Exemplos de código

Inicia um intervalo de rastreamento com o nome do método fornecido e a operação AMQP SEND

Parameters:

spanName - Nome do método que dispara a criação do intervalo.
context - Metadados adicionais que são passados pela pilha de chamadas.
processKind - Tipo de operação AMQP.

Returns:

O objeto atualizado Context que contém o intervalo retornado.

start

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

Cria um novo intervalo de rastreamento.

O context será verificado para obter informações sobre um intervalo pai. Se um intervalo pai for encontrado, o novo intervalo será adicionado como um filho. Caso contrário, o intervalo pai será criado e adicionado ao e todas as context chamadas downstream start() usarão o intervalo criado como o pai.

Exemplos de código

Inicia um intervalo de rastreamento com o nome do método fornecido e o intervalo pai explícito

// 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 - Nome do método que dispara a criação do intervalo.
options - opções de criação de intervalo.
context - Metadados adicionais que são passados pela pilha de chamadas.

Returns:

O objeto atualizado Context que contém o intervalo retornado.

Aplica-se a