HttpClient instrumentation

HttpClient is an open source component of the Apache project. It provides an efficient, up-to-date, and feature-rich client-side programming toolkit that supports the HTTP protocol.

You can import and use HttpClient in your SOFABoot project to enable Tracer log printing.

This topic describes how to use SOFATracer to instrument HttpClient. If you have a simple Spring Web project built on SOFABoot, follow these steps:

1. Import Maven dependencies

2. Add a controller that provides a RESTful service

3. Build and initiate a call to HttpClient

4. Run the project

5. View logs

Import Maven dependencies

To enable Tracer log printing for HttpClient, add the following Maven dependencies to your project's pom.xml file:

• SOFATracer dependency

  <dependency>
        <groupId>com.alipay.sofa</groupId>
        <artifactId>tracer-enterprise-sofa-boot-starter</artifactId>
  </dependency>

• HttpClient plugin for SOFATracer

  SOFATracer provides the tracer-enterprise-httpclient-plugin extension to enable tracing for the third-party open source component HttpClient:

  <dependency>
         <groupId>com.alipay.sofa</groupId>
         <artifactId>tracer-enterprise-httpclient-plugin</artifactId>
  </dependency>

• HttpClient dependency

  <dependency>
      <groupId>org.apache.httpcomponents</groupId>
      <artifactId>httpclient</artifactId>
      <!-- Versions 4.3.x - 4.5.x -->
      <version>4.5.3</version>
  </dependency>
  <dependency>
      <groupId>org.apache.httpcomponents</groupId>
      <artifactId>httpasyncclient</artifactId>
      <!-- Version 4.1.x -->
      <version>4.1.3</version>
  </dependency>

Add a controller that provides a RESTful service

Example code:

@RestController
public class SampleRestController {

    private final AtomicLong counter = new AtomicLong(0);

    /**
     * Request http://localhost:8080/httpclient?name=
     *
     * @param name name
     * @return Map of Result
     */
    @RequestMapping("/httpclient")
    public Map<String, Object> greeting(@RequestParam(value = "name", defaultValue = "httpclient") String name) {
        Map<String, Object> map = new HashMap<String, Object>();
        map.put("count", counter.incrementAndGet());
        map.put("name", name);
        return map;
    }
}

Build HttpClient and call the RESTful service

To ensure that HttpClient is correctly instrumented by SOFATracer to print logs in your project, choose an implementation method based on your SOFABoot version:

• For sofaboot-enterprise 3.1.0 (tracer-parent 3.0.2) and earlier, use the com.alipay.sofa.tracer.enterprise.plugins.SofaTracerEnterpriseHttpClientBuilder class to build an HttpClient instance and explicitly call the clientBuilder method.

• For sofaboot-enterprise 3.1.1 (tracer-parent 3.0.3) and later, use the com.alipay.sofa.tracer.plugins.httpclient.SofaTracerHttpClientBuilder class to build an HttpClient instance and explicitly call the clientBuilder method.

The SofaTracerEnterpriseHttpClientBuilder class provides the clientBuilder (synchronous) and asyncClientBuilder (asynchronous) methods to build an org.apache.http.impl.client.HttpClientBuilder instance that is instrumented by SOFATracer. The method signatures are as follows:

 // Constructor for synchronous calls
    public static HttpClientBuilder clientBuilder(HttpClientBuilder clientBuilder);

    // Constructor for synchronous calls that displays the current and target application fields in the log
    public static HttpClientBuilder clientBuilder(HttpClientBuilder clientBuilder,
                                                  String currentApp, String targetApp);

    // Constructor for asynchronous calls
    public static HttpAsyncClientBuilder asyncClientBuilder(HttpAsyncClientBuilder httpAsyncClientBuilder);

    // Constructor for asynchronous calls that displays the current and target application fields in the log
    public static HttpAsyncClientBuilder asyncClientBuilder(HttpAsyncClientBuilder httpAsyncClientBuilder,
                                                            String currentApp, String targetApp);

Code example

• Example of building a synchronous HttpClient call:

  HttpClientBuilder httpClientBuilder = HttpClientBuilder.create();
  //SOFATracer 
  SofaTracerEnterpriseHttpClientBuilder.clientBuilder(httpClientBuilder,"testSyncClient","testSyncServer");
  CloseableHttpClient httpClient=httpClientBuilder.setConnectionManager(connManager).disableAutomaticRetries()
          .build();

• Example of building an asynchronous HttpClient call:

  RequestConfig requestConfig =RequestConfig.custom().setSocketTimeout(6000).setConnectTimeout(6000).setConnectionRequestTimeout(6000).build();
  HttpAsyncClientBuilder httpAsyncClientBuilder =HttpAsyncClientBuilder.create();
  //tracer
  SofaTracerEnterpriseHttpClientBuilder.asyncClientBuilder(httpAsyncClientBuilder,"testAsyncClient","testAsyncServer");
  CloseableHttpAsyncClient asyncHttpclient = httpAsyncClientBuilder.setDefaultRequestConfig(requestConfig).build();

When an HttpClient instance built with SofaTracerEnterpriseHttpClientBuilder calls the previously mentioned RESTful service, SOFATracer automatically instruments the call with trace data.

Run the project

1. Import the SOFABoot project into your IDE.

2. Compile and run the main method in the project to start the application.

3. Use the HttpClient built with SofaTracerEnterpriseHttpClientBuilder to call the http://localhost:8080/httpclient RESTful service provided by the controller.

For more information, see SOFABoot Quick Start.

View logs

The directory path for Tracer logs is defined in the SOFABoot configuration file application.properties.

In the following example, assume that the log printing directory is set to ./logs, which is the root directory of the current application. Also, assume that the current application name passed to SofaTracerEnterpriseHttpClientBuilder is testSyncClient and the target application name is testSyncServer. You will find log files with a structure similar to the following in the project's root directory:

-- tracelog
|-- httpclient-digest.log
|-- httpclient-stat.log

For a synchronous HttpClient call, the summary log httpclient-digest.log is as follows:

2018-10-0920:57:29.923,testSyncClient,0a0fe9271539089849647100179895,0,http://localhost:49685/httpclient,GET,200,0B,-1B,275ms,main,testSyncServer,,

For a synchronous HttpClient call, the statistics log httpclient-stat.log is as follows:

2018-10-0920:57:30.596,testSyncClient,http://localhost:49685/httpclient,GET,1,275,Y,F

For more information about the HttpClient log fields, see Log format > HttpClient logs.