Connection Timeout Agent

Connection Timeout Agent

This module provides a java agent that uses the instrumentation API to add connect and read timeouts to connections made via HTTP or HTTPs. It only applies these timeouts if none were set explicitly.

The agent is intended as an additional layer of control to use when running untrusted client code that may make calls without explicitly setting timeouts. It is always recommended to set timeouts in client code, rather than relying on this agent.

It currently supports setting timeouts for HTTP connections done using:


The agent can be loaded using the standard Java CLI invocation, by using the -javaagent:... argument.

java<agent-connect-timeout>,<agent-read-timeout>[,<logspec>] -jar

It support two mandatory arguments and an optional one:

  • <agent-connect-timeout> - connection timeout in milliseconds to apply via the agent
  • <agent-read-timeout>- read timeout in milliseconds to apply via the agent
  • <logspec> - if set to v, it will enter verbose mode and print additional information to System.out

If started in verbose mode, output similar to the following will be printed

[AGENT] Preparing to install URL transformers. Configured timeouts - connectTimeout : 1000, readTimeout: 1000 
[AGENT] All transformers installed 
[AGENT] JavaNetTimeoutTransformer asked to transform sun/net/www/protocol/https/AbstractDelegateHttpsURLConnection 
[AGENT] Transformation of sun/net/www/protocol/https/AbstractDelegateHttpsURLConnection complete 
[AGENT] JavaNetTimeoutTransformer asked to transform sun/net/www/protocol/http/HttpURLConnection 
[AGENT] Transformation of sun/net/www/protocol/http/HttpURLConnection complete 

Note that classes will be transformed when they are loaded. It is expected for a transformer for class A to be active but the class not to be transformed until it is actually used.


Various runtime information is exposed through a JMX MBean registered at;ObjectType=Agent.

JMX MBeans


It is always recommended to set timeouts in the client code directly. The agent carries some risks, namely:

  • it is not transparent why and where timeouts are set and can lead to hard-to-debug scenarios
  • it only sets one timeout for the whole JVM, whereas various services may need different timeouts

All HTTP client libraries offer a way of setting connect and read timeouts, and it strongly recommended to do so. Alternatively, various bundles offer a way of centrally defining timeouts, amongst them:

Tested platforms

  • openjdk version "1.8.0_212"
  • openjdk version "11.0.2" 2019-01-15
  • commons-httpclient 3.1
  • httpclient 4.5.4
  • okhttp 3.14.2