okhttp3

Class EventListener

java.lang.Object

okhttp3.EventListener

public abstract class EventListener
extends Object

Listener for metrics events. Extend this class to monitor the quantity, size, and duration of your application's HTTP calls.

All start/connect/acquire events will eventually receive a matching end/release event, either successful (non-null parameters), or failed (non-null throwable). The first common parameters of each event pair are used to link the event in case of concurrent or repeated events e.g. dnsStart(call, domainName) -> dnsEnd(call, domainName, inetAddressList).

Nesting is as follows

• call -> (dns -> connect -> secure connect)* -> request events
• call -> (connection acquire/release)*

Request events are ordered: requestHeaders -> requestBody -> responseHeaders -> responseBody

Since connections may be reused, the dns and connect events may not be present for a call, or may be repeated in case of failure retries, even concurrently in case of happy eyeballs type scenarios. A redirect cross domain, or to use https may cause additional connection and request events.

All event methods must execute fast, without external locking, cannot throw exceptions, attempt to mutate the event parameters, or be re-entrant back into the client. Any IO - writing to files or network should be done asynchronously.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	EventListener.Factory

Field Summary

Fields

Modifier and Type	Field and Description
static EventListener	NONE

Constructor Summary

Constructors

Constructor and Description
EventListener()

Method Summary

Modifier and Type	Method and Description
void	callEnd(Call call) Invoked immediately after a call has completely ended.
void	callFailed(Call call, IOException ioe) Invoked when a call fails permanently.
void	callStart(Call call) Invoked as soon as a call is enqueued or executed by a client.
void	connectEnd(Call call, InetSocketAddress inetSocketAddress, Proxy proxy, Protocol protocol) Invoked immediately after a socket connection was attempted.
void	connectFailed(Call call, InetSocketAddress inetSocketAddress, Proxy proxy, Protocol protocol, IOException ioe) Invoked when a connection attempt fails.
void	connectionAcquired(Call call, Connection connection) Invoked after a connection has been acquired for the call.
void	connectionReleased(Call call, Connection connection) Invoked after a connection has been released for the call.
void	connectStart(Call call, InetSocketAddress inetSocketAddress, Proxy proxy) Invoked just prior to initiating a socket connection.
void	dnsEnd(Call call, String domainName, List<InetAddress> inetAddressList) Invoked immediately after a DNS lookup.
void	dnsStart(Call call, String domainName) Invoked just prior to a DNS lookup.
void	requestBodyEnd(Call call, long byteCount) Invoked immediately after sending a request body.
void	requestBodyStart(Call call) Invoked just prior to sending a request body.
void	requestFailed(Call call, IOException ioe) Invoked when a request fails to be written.
void	requestHeadersEnd(Call call, Request request) Invoked immediately after sending request headers.
void	requestHeadersStart(Call call) Invoked just prior to sending request headers.
void	responseBodyEnd(Call call, long byteCount) Invoked immediately after receiving a response body and completing reading it.
void	responseBodyStart(Call call) Invoked just prior to receiving the response body.
void	responseFailed(Call call, IOException ioe) Invoked when a response fails to be read.
void	responseHeadersEnd(Call call, Response response) Invoked immediately after receiving response headers.
void	responseHeadersStart(Call call) Invoked just prior to receiving response headers.
void	secureConnectEnd(Call call, Handshake handshake) Invoked immediately after a TLS connection was attempted.
void	secureConnectStart(Call call) Invoked just prior to initiating a TLS connection.

Methods inherited from class java.lang.Object

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

Field Detail

NONE

public static final EventListener NONE

Constructor Detail

EventListener

public EventListener()

Method Detail

callStart

public void callStart(Call call)

Invoked as soon as a call is enqueued or executed by a client. In case of thread or stream limits, this call may be executed well before processing the request is able to begin.

This will be invoked only once for a single Call. Retries of different routes or redirects will be handled within the boundaries of a single callStart and callEnd(okhttp3.Call)/callFailed(okhttp3.Call, java.io.IOException) pair.

dnsStart

public void dnsStart(Call call,
                     String domainName)

Invoked just prior to a DNS lookup. See Dns.lookup(String).

This can be invoked more than 1 time for a single Call. For example, if the response to the Call.request() is a redirect to a different host.

If the Call is able to reuse an existing pooled connection, this method will not be invoked. See ConnectionPool.

dnsEnd

public void dnsEnd(Call call,
                   String domainName,
                   List<InetAddress> inetAddressList)

Invoked immediately after a DNS lookup.

This method is invoked after dnsStart(okhttp3.Call, java.lang.String).

connectStart

public void connectStart(Call call,
                         InetSocketAddress inetSocketAddress,
                         Proxy proxy)

Invoked just prior to initiating a socket connection.

This method will be invoked if no existing connection in the ConnectionPool can be reused.

This can be invoked more than 1 time for a single Call. For example, if the response to the Call.request() is a redirect to a different address, or a connection is retried.

secureConnectStart

public void secureConnectStart(Call call)

Invoked just prior to initiating a TLS connection.

This method is invoked if the following conditions are met:

• The Call.request() requires TLS.
• No existing connection from the ConnectionPool can be reused.

This can be invoked more than 1 time for a single Call. For example, if the response to the Call.request() is a redirect to a different address, or a connection is retried.

secureConnectEnd

public void secureConnectEnd(Call call,
                             @Nullable
                             Handshake handshake)

Invoked immediately after a TLS connection was attempted.

This method is invoked after secureConnectStart(okhttp3.Call).

connectEnd

public void connectEnd(Call call,
                       InetSocketAddress inetSocketAddress,
                       Proxy proxy,
                       @Nullable
                       Protocol protocol)

Invoked immediately after a socket connection was attempted.

If the call uses HTTPS, this will be invoked after secureConnectEnd(Call, Handshake), otherwise it will invoked after connectStart(Call, InetSocketAddress, Proxy).

connectFailed

public void connectFailed(Call call,
                          InetSocketAddress inetSocketAddress,
                          Proxy proxy,
                          @Nullable
                          Protocol protocol,
                          IOException ioe)

Invoked when a connection attempt fails. This failure is not terminal if further routes are available and failure recovery is enabled.

If the call uses HTTPS, this will be invoked after secureConnectEnd(Call, Handshake), otherwise it will invoked after connectStart(Call, InetSocketAddress, Proxy).

connectionAcquired

public void connectionAcquired(Call call,
                               Connection connection)

Invoked after a connection has been acquired for the call.

This can be invoked more than 1 time for a single Call. For example, if the response to the Call.request() is a redirect to a different address.

connectionReleased

public void connectionReleased(Call call,
                               Connection connection)

Invoked after a connection has been released for the call.

This method is always invoked after connectionAcquired(Call, Connection).

This can be invoked more than 1 time for a single Call. For example, if the response to the Call.request() is a redirect to a different address.

requestHeadersStart

public void requestHeadersStart(Call call)

Invoked just prior to sending request headers.

The connection is implicit, and will generally relate to the last connectionAcquired(Call, Connection) event.

This can be invoked more than 1 time for a single Call. For example, if the response to the Call.request() is a redirect to a different address.

requestHeadersEnd

public void requestHeadersEnd(Call call,
                              Request request)

Invoked immediately after sending request headers.

This method is always invoked after requestHeadersStart(Call).

Parameters:

request - the request sent over the network. It is an error to access the body of this request.

requestBodyStart

public void requestBodyStart(Call call)

Invoked just prior to sending a request body. Will only be invoked for request allowing and having a request body to send.

The connection is implicit, and will generally relate to the last connectionAcquired(Call, Connection) event.

This can be invoked more than 1 time for a single Call. For example, if the response to the Call.request() is a redirect to a different address.

requestBodyEnd

public void requestBodyEnd(Call call,
                           long byteCount)

Invoked immediately after sending a request body.

This method is always invoked after requestBodyStart(Call).

requestFailed

public void requestFailed(Call call,
                          IOException ioe)

Invoked when a request fails to be written.

This method is invoked after requestHeadersStart(okhttp3.Call) or requestBodyStart(okhttp3.Call). Note that request failures do not necessarily fail the entire call.

responseHeadersStart

public void responseHeadersStart(Call call)

Invoked just prior to receiving response headers.

The connection is implicit, and will generally relate to the last connectionAcquired(Call, Connection) event.

This can be invoked more than 1 time for a single Call. For example, if the response to the Call.request() is a redirect to a different address.

responseHeadersEnd

public void responseHeadersEnd(Call call,
                               Response response)

Invoked immediately after receiving response headers.

This method is always invoked after responseHeadersStart(okhttp3.Call).

Parameters:

response - the response received over the network. It is an error to access the body of this response.

responseBodyStart

public void responseBodyStart(Call call)

Invoked just prior to receiving the response body.

The connection is implicit, and will generally relate to the last connectionAcquired(Call, Connection) event.

This will usually be invoked only 1 time for a single Call, exceptions are a limited set of cases including failure recovery.

responseBodyEnd

public void responseBodyEnd(Call call,
                            long byteCount)

Invoked immediately after receiving a response body and completing reading it.

Will only be invoked for requests having a response body e.g. won't be invoked for a websocket upgrade.

This method is always invoked after requestBodyStart(Call).

responseFailed

public void responseFailed(Call call,
                           IOException ioe)

Invoked when a response fails to be read.

This method is invoked after responseHeadersStart(okhttp3.Call) or responseBodyStart(okhttp3.Call). Note that response failures do not necessarily fail the entire call.

callEnd

public void callEnd(Call call)

Invoked immediately after a call has completely ended. This includes delayed consumption of response body by the caller.

This method is always invoked after callStart(Call).

callFailed

public void callFailed(Call call,
                       IOException ioe)

Invoked when a call fails permanently.

This method is always invoked after callStart(Call).