Package com.google.api.gax.tracing

Class OpencensusTracer

java.lang.Object
com.google.api.gax.tracing.BaseApiTracer
com.google.api.gax.tracing.OpencensusTracer
All Implemented Interfaces:
ApiTracer
@BetaApi("Surface for tracing is not yet stable") public class OpencensusTracer extends BaseApiTracer
Implementation of ApiTracer that uses OpenCensus.

This implementation wraps an OpenCensus Span for every tracer and annotates that Span with various events throughout the lifecycle of the logical operation.

Each span will be named ClientName.MethodName and will have the following attributes:

attempt count
The Number of attempts sent before the logical operation completed
status
The status code of the last attempt
total response count
The number of messages received across all of the attempts. This will only be set for server streaming and bidi RPCs.
total request count
The number of messages sent across all of the attempts. This will only be set for client streaming and bidi RPCs.
batch count
For batch requests, the number of elements in the request.
batch size
For batch requests, the byte size of the request.

The spans will contain the following annotations:

  • Attempt cancelled with the following attributes:
    attempt
    Zero based sequential attempt number
    attempt request count
    The number of requests sent in this attempt. This will only be set for client streaming and bidi RPCs.
    attempt response count
    The number of responses received in this attempt. This will only be set for server streaming and bidi RPCs.
    connection
    The UUID of the connection which the attempt was sent.
  • Attempt failed, scheduling next attempt with the following attributes:
    attempt
    Zero based sequential attempt number
    status
    The status code of the failed attempt
    delay
    The number of milliseconds to wait before trying again
    attempt request count
    The number of requests sent in this attempt. This will only be set for client streaming and bidi RPCs.
    attempt response count
    The number of responses received in this attempt. This will only be set for server streaming and bidi RPCs.
    connection
    The UUID of the connection which the attempt was sent.
  • Attempts exhausted with the following attributes:
    attempt
    Zero based sequential attempt number
    status
    The status code of the failed attempt
    attempt request count
    The number of requests sent in this attempt. This will only be set for client streaming and bidi RPCs.
    attempt response count
    The number of responses received in this attempt. This will only be set for server streaming and bidi RPCs.
    connection
    The UUID of the connection which the attempt was sent.
  • Attempt failed, error not retryable with the following attributes:
    attempt
    Zero based sequential attempt number
    status
    The status code of the failed attempt
    attempt request count
    The number of requests sent in this attempt. This will only be set for client streaming and bidi RPCs.
    attempt response count
    The number of responses received in this attempt. This will only be set for server streaming and bidi RPCs.
    connection
    The UUID of the connection which the attempt was sent.
  • Attempt succeeded with the following attributes:
    attempt
    Zero based sequential attempt number
    attempt request count
    The number of requests sent in this attempt. This will only be set for client streaming and bidi RPCs.
    attempt response count
    The number of responses received in this attempt. This will only be set for server streaming and bidi RPCs.
    connection
    The UUID of the connection which the attempt was sent.

Long running operations, which are composed of an initial RPC to start the operation and a number of polling RPCs will be represented as a tree of spans. The top level span will be named after the initial RPC name suffixed with "Operation" and will have the following annotations:

  • Operation started
  • Operation failed to start with the following attributes:
    status
    The status code of why the operation failed to start
  • Polling was cancelled with the following attributes:
    attempt
    Zero based sequential poll number.
    attempt request count
  • Scheduling next poll with the following attributes:
    attempt
    Zero based sequential poll number
    status
    OK if the poll succeeded, but the operation is still running.
    delay
    The number of milliseconds to wait before polling again
  • Polling attempts exhausted with the following attributes:
    attempt
    Zero based sequential poll number
    status
    OK if the poll succeeded, but the operation is still running.
  • Polling failed with the following attributes:
    attempt
    Zero based sequential poll number
    status
    OK if the poll succeeded, but the operation is still running.
  • Polling completed with the following attributes:
    attempt
    Zero based sequential poll number

The toplevel long running operation span will also contain child spans to describe the retry attempts for the initial RPC and each poll as described in the general span section above.

This class is thread compatible. It expects callers to follow grpc's threading model: there is only one thread that invokes the operation* and attempt* methods. Please see ApiStreamObserver for more information.

  • Nested Class Summary

    Nested classes/interfaces inherited from interface com.google.api.gax.tracing.ApiTracer

    ApiTracer.Scope

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    attemptCancelled()
    Add an annotation that the attempt was cancelled by the user.
    void
    attemptFailed(Throwable error, org.threeten.bp.Duration delay)
    Adds an annotation that the attempt failed, but another attempt will be made after the delay.
    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.
    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.
    void
    attemptStarted(int attemptNumber)
    Adds an annotation that an attempt is about to start.
    void
    attemptStarted(Object request, int attemptNumber)
    Adds an annotation that an attempt is about to start with additional information from the request.
    void
    attemptSucceeded()
    Adds an annotation that the attempt succeeded.
    void
    batchRequestSent(long elementCount, long requestSize)
    Adds an annotation that a batch of writes has been flushed.
    void
    connectionSelected(String id)
    Annotates the operation with selected connection id from the ChannelPool.
    ApiTracer.Scope
    inScope()
    Asks the underlying implementation to install itself as a thread local.
    void
    lroStartFailed(Throwable error)
    Signals that the initial RPC for the long running operation failed.
    void
    lroStartSucceeded()
    Signals that the initial RPC successfully started the long running operation.
    void
    operationCancelled()
    Signals that the operation was cancelled by the user.
    void
    operationFailed(Throwable error)
    Signals that the overall operation has failed and no further attempts will be made.
    void
    operationSucceeded()
    Signals that the overall operation has finished successfully.
    void
    requestSent()
    Adds an annotation that a streaming request has been sent.
    void
    responseReceived()
    Adds an annotation that a streaming response has been received.

    Methods inherited from class com.google.api.gax.tracing.BaseApiTracer

    getInstance

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • inScope

      public 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.
      Specified by:
      inScope in interface ApiTracer
      Overrides:
      inScope in class BaseApiTracer

    • operationSucceeded

      public void operationSucceeded()
      Signals that the overall operation has finished successfully. The tracer is now considered closed and should no longer be used.
      Specified by:
      operationSucceeded in interface ApiTracer
      Overrides:
      operationSucceeded in class BaseApiTracer

    • operationCancelled

      public void operationCancelled()
      Signals that the operation was cancelled by the user. The tracer is now considered closed and should no longer be used.
      Specified by:
      operationCancelled in interface ApiTracer
      Overrides:
      operationCancelled in class BaseApiTracer

    • operationFailed

      public 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.
      Specified by:
      operationFailed in interface ApiTracer
      Overrides:
      operationFailed in class BaseApiTracer
      Parameters:
      error - the final error that caused the operation to fail.

    • lroStartFailed

      public void lroStartFailed(Throwable error)
      Signals that the initial RPC for the long running operation failed.
      Specified by:
      lroStartFailed in interface ApiTracer
      Overrides:
      lroStartFailed in class BaseApiTracer
      Parameters:
      error - the error that caused the long running operation fail.

    • lroStartSucceeded

      public void lroStartSucceeded()
      Signals that the initial RPC successfully started the long running operation. The long running operation will now be polled for completion.
      Specified by:
      lroStartSucceeded in interface ApiTracer
      Overrides:
      lroStartSucceeded in class BaseApiTracer

    • connectionSelected

      public void connectionSelected(String id)
      Annotates the operation with selected connection id from the ChannelPool.
      Specified by:
      connectionSelected in interface ApiTracer
      Overrides:
      connectionSelected in class BaseApiTracer
      Parameters:
      id - the local connection identifier of the selected connection.

    • attemptStarted

      public void attemptStarted(int attemptNumber)
      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.
      Specified by:
      attemptStarted in interface ApiTracer
      Overrides:
      attemptStarted in class BaseApiTracer
      Parameters:
      attemptNumber - the zero based sequential attempt number.

    • attemptStarted

      public 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.
      Specified by:
      attemptStarted in interface ApiTracer
      Overrides:
      attemptStarted in class BaseApiTracer
      Parameters:
      request - request of this attempt.
      attemptNumber - the zero based sequential attempt number.

    • attemptSucceeded

      public void attemptSucceeded()
      Adds an annotation that the attempt succeeded.
      Specified by:
      attemptSucceeded in interface ApiTracer
      Overrides:
      attemptSucceeded in class BaseApiTracer

    • attemptCancelled

      public void attemptCancelled()
      Add an annotation that the attempt was cancelled by the user.
      Specified by:
      attemptCancelled in interface ApiTracer
      Overrides:
      attemptCancelled in class BaseApiTracer

    • attemptFailed

      public void attemptFailed(Throwable error, org.threeten.bp.Duration delay)
      Adds an annotation that the attempt failed, but another attempt will be made after the delay.
      Specified by:
      attemptFailed in interface ApiTracer
      Overrides:
      attemptFailed in class BaseApiTracer
      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

      public 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.
      Specified by:
      attemptFailedRetriesExhausted in interface ApiTracer
      Overrides:
      attemptFailedRetriesExhausted in class BaseApiTracer
      Parameters:
      error - the last error received before retries were exhausted.

    • attemptPermanentFailure

      public 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.
      Specified by:
      attemptPermanentFailure in interface ApiTracer
      Overrides:
      attemptPermanentFailure in class BaseApiTracer
      Parameters:
      error - the error that caused the final attempt to fail.

    • responseReceived

      public void responseReceived()
      Adds an annotation that a streaming response has been received.
      Specified by:
      responseReceived in interface ApiTracer
      Overrides:
      responseReceived in class BaseApiTracer

    • requestSent

      public void requestSent()
      Adds an annotation that a streaming request has been sent.
      Specified by:
      requestSent in interface ApiTracer
      Overrides:
      requestSent in class BaseApiTracer

    • batchRequestSent

      public void batchRequestSent(long elementCount, long requestSize)
      Adds an annotation that a batch of writes has been flushed.
      Specified by:
      batchRequestSent in interface ApiTracer
      Overrides:
      batchRequestSent in class BaseApiTracer
      Parameters:
      elementCount - the number of elements in the batch.
      requestSize - the size of the batch in bytes.