diff --git a/java-client/src/main/java/co/elastic/clients/transport/instrumentation/Instrumentation.java b/java-client/src/main/java/co/elastic/clients/transport/instrumentation/Instrumentation.java
index 37acf0c49..f4eca1ab0 100644
--- a/java-client/src/main/java/co/elastic/clients/transport/instrumentation/Instrumentation.java
+++ b/java-client/src/main/java/co/elastic/clients/transport/instrumentation/Instrumentation.java
@@ -23,22 +23,55 @@
 import co.elastic.clients.transport.TransportOptions;
 import co.elastic.clients.transport.http.TransportHttpClient;
 
+/**
+ * Instrumentation for an Elasticsearch client. It allows creating a {@link Instrumentation.Context} for each request,
+ * with callbacks for the various stages of request and response processing.
+ */
 public interface Instrumentation {
 
+    /**
+     * Create a context for a given request and the corresponding endpoint.
+     */
     <TRequest> Context newContext(TRequest request, Endpoint<TRequest, ?, ?> endpoint);
 
+    /**
+     * A context with lifecycle callbacks for the various stages of request and response processing. Must be {@link #close()}d.
+     */
     interface Context extends AutoCloseable {
+
+        /**
+         * Sets this context (or the underlying abstraction) as the current thread's scope, so that neste call can
+         * nest child contexts.
+         */
         ThreadScope makeCurrent();
 
+        /**
+         * Called once the initial API request has been serialized and the http request has been prepared.
+         */
         void beforeSendingHttpRequest(TransportHttpClient.Request httpRequest, TransportOptions options);
+
+        /**
+         * Called after the http response has been received, and before analyzing it.
+         */
         void afterReceivingHttpResponse(TransportHttpClient.Response httpResponse);
+
+        /**
+         * Called after the http response has been deserialized
+         */
         <TResponse> void afterDecodingApiResponse(TResponse apiResponse);
+
+        /**
+         * Called when any stage of request processing caused a failure.
+         */
         void recordException(Throwable thr);
 
         @Override
         void close();
     }
 
+    /**
+     * A thread scope. Closing it will detach the scope from the current thread.
+     */
     interface ThreadScope extends AutoCloseable {
         @Override
         void close();