# Interface ApiTracer (2.81.0)

2.81.0 (latest) 2.80.0 2.79.0 2.76.0 2.75.0 2.74.1 2.73.1 2.72.2 2.71.0 2.70.3 2.69.0 2.68.2 2.67.0 2.66.0 2.65.0 2.63.1 2.62.0 2.61.0 2.60.0 2.59.1 2.58.0 2.57.0 2.55.0 2.54.1 2.53.0 2.52.0 2.51.0 2.50.0 2.49.0 2.48.1 2.47.0 2.46.1 2.45.0 2.43.0 2.42.0 2.41.0 2.39.0 2.38.0 2.37.0 2.36.0 2.35.0 2.34.1 2.33.0 2.32.1 2.31.1 2.30.1 2.24.0 2.23.3 2.22.0 2.21.0 2.20.1 2.19.6 2.18.7 2.17.0 2.16.0 2.15.0 2.14.0 2.13.0 2.12.2 2.11.0 2.10.0 2.9.0 2.8.1 2.7.1

    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](https://docs.cloud.google.com/java/docs/reference/gax/latest/com.google.api.gax.tracing.BaseApiTracer).

## Methods

### attemptCancelled()

    public default void attemptCancelled()

Add an annotation that the attempt was cancelled by the user.

### attemptFailed(Throwable error, Duration delay)

    public default void attemptFailed(Throwable error, Duration delay)

> [!WARNING]
> **Obsolete**
>
> *Use attemptFailedDuration(Throwable, java.time.Duration) instead*
>
> This feature is stable for usage in this major version, but may be deprecated in a future release.

This method is obsolete. Use [#attemptFailedDuration(Throwable, java.time.Duration)](https://docs.cloud.google.com/java/docs/reference/gax/latest/com.google.api.gax.tracing.ApiTracer#com_google_api_gax_tracing_ApiTracer_attemptFailedDuration_)
instead.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `error` | `https://docs.oracle.com/javase/8/docs/api/java/lang/Throwable.html` |
| `delay` | `org.threeten.bp.Duration` |

### attemptFailedDuration(Throwable error, Duration delay)

    public default void attemptFailedDuration(Throwable error, Duration delay)

Adds an annotation that the attempt failed, but another attempt will be made after the delay.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `error` | `https://docs.oracle.com/javase/8/docs/api/java/lang/Throwable.html` the transient error that caused the attempt to fail. |
| `delay` | `https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html` the amount of time to wait before the next attempt will start. |

### attemptFailedRetriesExhausted(Throwable error)

    public 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.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `error` | `https://docs.oracle.com/javase/8/docs/api/java/lang/Throwable.html` the last error received before retries were exhausted. |

### attemptPermanentFailure(Throwable error)

    public 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.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `error` | `https://docs.oracle.com/javase/8/docs/api/java/lang/Throwable.html` the error that caused the final attempt to fail. |

### attemptStarted(int attemptNumber) (deprecated)

    public default void attemptStarted(int attemptNumber)

**Deprecated.** *Please use [#attemptStarted(Object, int)](https://docs.cloud.google.com/java/docs/reference/gax/latest/com.google.api.gax.tracing.ApiTracer#com_google_api_gax_tracing_ApiTracer_attemptStarted_java_lang_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.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `attemptNumber` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` the zero based sequential attempt number. |

### attemptStarted(Object request, int attemptNumber)

    public 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** ||
|---|---|
| **Name** | **Description** |
| `request` | `https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html` request of this attempt. |
| `attemptNumber` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` the zero based sequential attempt number. |

### attemptSucceeded()

    public default void attemptSucceeded()

Adds an annotation that the attempt succeeded.

### batchRequestSent(long elementCount, long requestSize)

    public default void batchRequestSent(long elementCount, long requestSize)

Adds an annotation that a batch of writes has been flushed.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `elementCount` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` the number of elements in the batch. |
| `requestSize` | `https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html` the size of the batch in bytes. |

### connectionSelected(String id)

    public default void connectionSelected(String id)

Annotates the operation with selected connection id from the `ChannelPool`.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `id` | `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` the local connection identifier of the selected connection. |

### inScope()

    public 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.

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/java/docs/reference/gax/latest/com.google.api.gax.tracing.ApiTracer.Scope` |   |

### injectTraceContext(Map\<String,String\> carrier)

    public default void injectTraceContext(Map<String,String> carrier)

Extract the trace context from the tracer and add it to the given headers map.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `carrier` | `https://docs.oracle.com/javase/8/docs/api/java/util/Map.html<https://docs.oracle.com/javase/8/docs/api/java/lang/String.html,https://docs.oracle.com/javase/8/docs/api/java/lang/String.html>` |

### lroStartFailed(Throwable error)

    public default void lroStartFailed(Throwable error)

Signals that the initial RPC for the long running operation failed.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `error` | `https://docs.oracle.com/javase/8/docs/api/java/lang/Throwable.html` the error that caused the long running operation fail. |

### lroStartSucceeded()

    public default void lroStartSucceeded()

Signals that the initial RPC successfully started the long running operation. The long running
operation will now be polled for completion.

### operationCancelled()

    public 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(Throwable error)

    public 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.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `error` | `https://docs.oracle.com/javase/8/docs/api/java/lang/Throwable.html` the final error that caused the operation to fail. |

### operationSucceeded()

    public default void operationSucceeded()

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

### requestSent()

    public default void requestSent()

Adds an annotation that a streaming request has been sent.

### requestUrlResolved(String requestUrl)

    public default void requestUrlResolved(String requestUrl)

Annotates the attempt with the full resolved HTTP URL. Only relevant for HTTP transport.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `requestUrl` | `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` the full URL of the request |

### responseHeadersReceived(Map\<String,Object\> headers)

    public default void responseHeadersReceived(Map<String,Object> headers)

Adds an annotation that a streaming response has been received with its headers.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `headers` | `https://docs.oracle.com/javase/8/docs/api/java/util/Map.html<https://docs.oracle.com/javase/8/docs/api/java/lang/String.html,https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html>` |

### responseReceived()

    public default void responseReceived()

Adds an annotation that a streaming response has been received.