Package com.google.api.gax.tracing

Interface ApiTracer

All Known Implementing Classes:
BaseApiTracer, MetricsTracer, OpencensusTracer
@InternalApi public interface ApiTracer
Implementations of this class trace the logical flow of a google cloud client.

A single instance of a tracer represents a logical operation that can be annotated throughout its lifecycle. Constructing an instance of a subclass will implicitly signal the start of a new operation.

For internal use only. google-cloud-java libraries should extend BaseApiTracer.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    ApiTracer.Scope
    A context class to be used with inScope() and a try-with-resources block.

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    attemptCancelled()
    Add an annotation that the attempt was cancelled by the user.
    default void
    attemptFailed(Throwable error, org.threeten.bp.Duration delay)
    This method is obsolete.
    default void
    attemptFailedDuration(Throwable error, Duration delay)
    Adds an annotation that the attempt failed, but another attempt will be made after the delay.
    default void
    attemptFailedRetriesExhausted(Throwable error)
    Adds an annotation that the attempt failed and that no further attempts will be made because retry limits have been reached.
    default void
    attemptPermanentFailure(Throwable error)
    Adds an annotation that the attempt failed and that no further attempts will be made because the last error was not retryable.
    default void
    attemptStarted(int attemptNumber)
    Deprecated.
    Please use attemptStarted(Object, int) instead.
    default void
    attemptStarted(Object request, int attemptNumber)
    Adds an annotation that an attempt is about to start with additional information from the request.
    default void
    attemptSucceeded()
    Adds an annotation that the attempt succeeded.
    default void
    batchRequestSent(long elementCount, long requestSize)
    Adds an annotation that a batch of writes has been flushed.
    default void
    connectionSelected(String id)
    Annotates the operation with selected connection id from the ChannelPool.
    default ApiTracer.Scope
    inScope()
    Asks the underlying implementation to install itself as a thread local.
    default void
    lroStartFailed(Throwable error)
    Signals that the initial RPC for the long running operation failed.
    default void
    lroStartSucceeded()
    Signals that the initial RPC successfully started the long running operation.
    default void
    operationCancelled()
    Signals that the operation was cancelled by the user.
    default void
    operationFailed(Throwable error)
    Signals that the overall operation has failed and no further attempts will be made.
    default void
    operationSucceeded()
    Signals that the overall operation has finished successfully.
    default void
    requestSent()
    Adds an annotation that a streaming request has been sent.
    default void
    responseReceived()
    Adds an annotation that a streaming response has been received.

  • Method Details

    • inScope

      default ApiTracer.Scope inScope()
      Asks the underlying implementation to install itself as a thread local. This allows for interop between clients using gax and external resources to share the same implementation of the tracing. For example OpenCensus will install a thread local that can read by the GRPC.

    • operationSucceeded

      default void operationSucceeded()
      Signals that the overall operation has finished successfully. The tracer is now considered closed and should no longer be used.

    • operationCancelled

      default void operationCancelled()
      Signals that the operation was cancelled by the user. The tracer is now considered closed and should no longer be used.

    • operationFailed

      default void operationFailed(Throwable error)
      Signals that the overall operation has failed and no further attempts will be made. The tracer is now considered closed and should no longer be used.
      Parameters:
      error - the final error that caused the operation to fail.

    • connectionSelected

      default void connectionSelected(String id)
      Annotates the operation with selected connection id from the ChannelPool.
      Parameters:
      id - the local connection identifier of the selected connection.

    • attemptStarted

      @Deprecated default void attemptStarted(int attemptNumber)
      Deprecated.
      Please use attemptStarted(Object, int) instead.
      Adds an annotation that an attempt is about to start. In general this should occur at the very start of the operation. The attemptNumber is zero based. So the initial attempt will be 0.
      Parameters:
      attemptNumber - the zero based sequential attempt number.

    • attemptStarted

      default void attemptStarted(Object request, int attemptNumber)
      Adds an annotation that an attempt is about to start with additional information from the request. In general this should occur at the very start of the operation. The attemptNumber is zero based. So the initial attempt will be 0.
      Parameters:
      attemptNumber - the zero based sequential attempt number.
      request - request of this attempt.

    • attemptSucceeded

      default void attemptSucceeded()
      Adds an annotation that the attempt succeeded.

    • attemptCancelled

      default void attemptCancelled()
      Add an annotation that the attempt was cancelled by the user.

    • attemptFailed

      @ObsoleteApi("Use attemptFailedDuration(Throwable, java.time.Duration) instead") default void attemptFailed(Throwable error, org.threeten.bp.Duration delay)
      This method is obsolete. Use attemptFailedDuration(Throwable, java.time.Duration) instead.

    • attemptFailedDuration

      default void attemptFailedDuration(Throwable error, Duration delay)
      Adds an annotation that the attempt failed, but another attempt will be made after the delay.
      Parameters:
      error - the transient error that caused the attempt to fail.
      delay - the amount of time to wait before the next attempt will start.

    • attemptFailedRetriesExhausted

      default void attemptFailedRetriesExhausted(Throwable error)
      Adds an annotation that the attempt failed and that no further attempts will be made because retry limits have been reached.
      Parameters:
      error - the last error received before retries were exhausted.

    • attemptPermanentFailure

      default void attemptPermanentFailure(Throwable error)
      Adds an annotation that the attempt failed and that no further attempts will be made because the last error was not retryable.
      Parameters:
      error - the error that caused the final attempt to fail.

    • lroStartFailed

      default void lroStartFailed(Throwable error)
      Signals that the initial RPC for the long running operation failed.
      Parameters:
      error - the error that caused the long running operation fail.

    • lroStartSucceeded

      default void lroStartSucceeded()
      Signals that the initial RPC successfully started the long running operation. The long running operation will now be polled for completion.

    • responseReceived

      default void responseReceived()
      Adds an annotation that a streaming response has been received.

    • requestSent

      default void requestSent()
      Adds an annotation that a streaming request has been sent.

    • batchRequestSent

      default void batchRequestSent(long elementCount, long requestSize)
      Adds an annotation that a batch of writes has been flushed.
      Parameters:
      elementCount - the number of elements in the batch.
      requestSize - the size of the batch in bytes.