public interface NetworkTracer

Observes every ConnectionRequest the NetworkManager runs, so a tracer can time each one and put trace context on it.

Installed with NetworkManager.setNetworkTracer(NetworkTracer). The one implementation is com.codename1.telemetry.Telemetry’s, and it is reached only from the bootstrap the build generates for a project that enables it – so an app that does not trace carries this interface and nothing else.

This is a separate slot from NetworkGuard on purpose. The guard is a security decision: it seals on first install and can veto a request. A tracer observes and decorates, never refuses, and must not have to compete with the guard for the one slot the guard deliberately makes unreplaceable.

Every callback is guarded by the caller: an exception thrown from one is logged and the request carries on untraced.

Methods

`public abstract` `Object requestQueued(ConnectionRequest request)`	A request is being queued, on the thread that queued it – the EDT, for most requests.
`public abstract` `Object beforeRequest(ConnectionRequest request, Object parent)`	An attempt is about to connect, on the network thread, before the request’s headers are written.
`public abstract void afterRequest(ConnectionRequest request, Object attempt, int responseCode, Throwable error)`	An attempt `beforeRequest` started has ended, on the network thread.

Method details

requestQueued

public abstract Object requestQueued(ConnectionRequest request)

A request is being queued, on the thread that queued it – the EDT, for most requests. Whatever this returns is handed back to beforeRequest, which is how a request records the span that was current when the app ASKED for it, rather than whatever is current on the network thread later.

Returns

the parent context, or null

beforeRequest

public abstract Object beforeRequest(ConnectionRequest request, Object parent)

An attempt is about to connect, on the network thread, before the request’s headers are written. Headers added here with ConnectionRequest.addRequestHeader(String, String) are sent. Called again for every retry and redirect, each of which is its own attempt.

Parameters

request ConnectionRequest: the request
parent Object: what requestQueued returned for it – or, for a retry or redirect of a request queued with no parent, the attempt before it (what this method returned then), so that the attempts share one trace

Returns

the attempt’s state, handed to afterRequest, or null to not trace it

afterRequest

public abstract void afterRequest(ConnectionRequest request, Object attempt, int responseCode, Throwable error)

An attempt beforeRequest started has ended, on the network thread.

Parameters

request ConnectionRequest: the request
attempt Object: what beforeRequest returned
responseCode int: the HTTP status, or a value below 100 when none arrived
error Throwable: what failed the attempt, or null