Add submodule with interceptors for Apache HttpClient.

brave-apache-http-interceptors/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2013 <kristofa@github.com>
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.

brave-apache-http-interceptors/README.md

@@ -0,0 +1,16 @@
+# brave-apache-http-interceptors #
+
+Http Request and Response interceptors that can be used with [Apache HttpClient](http://hc.apache.org/httpcomponents-client-4.3.x/index.html).
+
+Apache HttpClient is probably the most known and used Java Http client. These interceptors make it easy
+to integrate with brave to catch/trace client requests. The request interceptor will start a new
+Span and submit cs (client sent) annotation. The response interceptor will submit cr (client received)
+annotation.
+
+Example of configuring interceptors with http client:
+
+    final CloseableHttpClient httpclient =
+            HttpClients.custom().addInterceptorFirst(new BraveHttpRequestInterceptor(clientTracer))
+                .addInterceptorFirst(new BraveHttpResponseInterceptor(clientTracer)).build();
+
+It is tested with httpclient version 4.3.3.

brave-apache-http-interceptors/pom.xml

@@ -0,0 +1,84 @@
+<?xml version="1.0"?>
+<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>com.github.kristofa</groupId>
+    <artifactId>brave</artifactId>
+    <version>2.1.2-SNAPSHOT</version>
+  </parent>
+  <artifactId>brave-apache-http-interceptors</artifactId>
+  <name>brave-apache-http-interceptors</name>
+  <description>
+    Apache http client request and response interceptor implementations.
+  </description>
+  <url>https://github.com/kristofa/brave</url>
+  <licenses>
+    <license>
+        <name>Apache 2</name>
+        <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
+        <distribution>repo</distribution>
+    </license>
+   </licenses>
+  <properties>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+  <dependencies>
+    <dependency>
+        <groupId>org.apache.httpcomponents</groupId>
+        <artifactId>httpclient</artifactId>
+        <version>4.3.3</version>
+        <scope>test</scope>
+    </dependency>
+    <dependency>
+        <groupId>org.apache.httpcomponents</groupId>
+        <artifactId>httpcore</artifactId>
+        <version>4.3.2</version>
+    </dependency>
+    <dependency>
+        <groupId>org.apache.commons</groupId>
+        <artifactId>commons-lang3</artifactId>
+        <version>3.1</version>
+    </dependency>
+    <dependency>
+        <groupId>com.github.kristofa</groupId>
+        <artifactId>brave-interfaces</artifactId>
+        <version>2.1.2-SNAPSHOT</version>
+    </dependency>
+    <dependency>
+        <groupId>com.github.kristofa</groupId>
+        <artifactId>mock-http-server</artifactId>
+        <version>4.0</version>
+        <scope>test</scope>
+    </dependency>
+  </dependencies>
+  <build>   
+    <plugins>
+            <plugin>           
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>                
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-eclipse-plugin</artifactId>                
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-source-plugin</artifactId>                
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>                
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-deploy-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-failsafe-plugin</artifactId>      
+        </plugin>        
+        </plugins>
+
+  </build>
+</project>

brave-apache-http-interceptors/src/main/java/com/github/kristofa/brave/httpclient/BraveHttpRequestInterceptor.java

@@ -0,0 +1,79 @@
+package com.github.kristofa.brave.httpclient;
+
+import java.io.IOException;
+
+import org.apache.commons.lang.Validate;
+import org.apache.commons.lang3.StringUtils;
+import org.apache.http.Header;
+import org.apache.http.HttpException;
+import org.apache.http.HttpRequest;
+import org.apache.http.HttpRequestInterceptor;
+import org.apache.http.protocol.HttpContext;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import com.github.kristofa.brave.BraveHttpHeaders;
+import com.github.kristofa.brave.ClientTracer;
+import com.github.kristofa.brave.SpanId;
+
+/**
+ * Apache HttpClient {@link HttpRequestInterceptor} that adds brave/zipkin annotations to outgoing client request.
+ * 
+ * @author kristof
+ */
+public class BraveHttpRequestInterceptor implements HttpRequestInterceptor {
+
+    private final static Logger LOGGER = LoggerFactory.getLogger(BraveHttpRequestInterceptor.class);
+    private static final String REQUEST_ANNOTATION = "request";
+    private static final String TRUE = "true";
+    private static final String FALSE = "false";
+
+    private final ClientTracer clientTracer;
+
+    /**
+     * Creates a new instance.
+     * 
+     * @param clientTracer ClientTracer should not be <code>null</code>.
+     */
+    public BraveHttpRequestInterceptor(final ClientTracer clientTracer) {
+        Validate.notNull(clientTracer);
+        this.clientTracer = clientTracer;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public void process(final HttpRequest request, final HttpContext context) throws HttpException, IOException {
+
+        String spanName = null;
+        final Header spanNameHeader = request.getFirstHeader(BraveHttpHeaders.SpanName.getName());
+        if (spanNameHeader != null) {
+            spanName = spanNameHeader.getValue();
+        }
+
+        if (StringUtils.isEmpty(spanName)) {
+            spanName = request.getRequestLine().getUri();
+        }
+
+        final SpanId newSpanId = clientTracer.startNewSpan(spanName);
+        if (newSpanId != null) {
+            LOGGER.debug("Will trace request. Span Id returned from ClientTracer: {}", newSpanId);
+            request.addHeader(BraveHttpHeaders.Sampled.getName(), TRUE);
+            request.addHeader(BraveHttpHeaders.TraceId.getName(), String.valueOf(newSpanId.getTraceId()));
+            request.addHeader(BraveHttpHeaders.SpanId.getName(), String.valueOf(newSpanId.getSpanId()));
+            if (newSpanId.getParentSpanId() != null) {
+                request.addHeader(BraveHttpHeaders.ParentSpanId.getName(), String.valueOf(newSpanId.getParentSpanId()));
+            }
+        } else {
+            LOGGER.debug("Will not trace request.");
+            request.addHeader(BraveHttpHeaders.Sampled.getName(), FALSE);
+        }
+
+        clientTracer.submitBinaryAnnotation(REQUEST_ANNOTATION, request.getRequestLine().getMethod() + " "
+            + request.getRequestLine().getUri());
+        clientTracer.setClientSent();
+
+    }
+
+}

brave-apache-http-interceptors/src/main/java/com/github/kristofa/brave/httpclient/BraveHttpResponseInterceptor.java

@@ -0,0 +1,59 @@
+package com.github.kristofa.brave.httpclient;
+
+import java.io.IOException;
+
+import org.apache.commons.lang.Validate;
+import org.apache.http.HttpException;
+import org.apache.http.HttpResponse;
+import org.apache.http.HttpResponseInterceptor;
+import org.apache.http.protocol.HttpContext;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import com.github.kristofa.brave.ClientTracer;
+
+/**
+ * Apache HttpClient {@link HttpResponseInterceptor} that gets the HttpResponse, inspects the state. If the response
+ * indicates an error it submits error code and failure annotation. Finally it submits the client received annotation.
+ * 
+ * @author kristof
+ */
+public class BraveHttpResponseInterceptor implements HttpResponseInterceptor {
+
+    private final static Logger LOGGER = LoggerFactory.getLogger(BraveHttpResponseInterceptor.class);
+
+    private static final String FAILURE_ANNOTATION = "failure";
+    private static final String HTTP_RESPONSE_CODE_ANNOTATION = "http.responsecode";
+
+    private final ClientTracer clientTracer;
+
+    /**
+     * Create a new instance.
+     * 
+     * @param clientTracer ClientTracer. Should not be <code>null</code>.
+     */
+    public BraveHttpResponseInterceptor(final ClientTracer clientTracer) {
+        Validate.notNull(clientTracer);
+        this.clientTracer = clientTracer;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public void process(final HttpResponse response, final HttpContext context) throws HttpException, IOException {
+        try {
+
+            final int responseStatus = response.getStatusLine().getStatusCode();
+            if (responseStatus < 200 || responseStatus > 299) {
+                // In this case response will be the error message.
+                clientTracer.submitBinaryAnnotation(HTTP_RESPONSE_CODE_ANNOTATION, responseStatus);
+                clientTracer.submitAnnotation(FAILURE_ANNOTATION);
+            }
+        } finally {
+            clientTracer.setClientReceived();
+        }
+
+    }
+
+}

brave-apache-http-interceptors/src/test/java/com/github/kristofa/brave/httpclient/BraveHttpRequestInterceptorTest.java

@@ -0,0 +1,116 @@
+package com.github.kristofa.brave.httpclient;
+
+import static org.mockito.Mockito.inOrder;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verifyNoMoreInteractions;
+import static org.mockito.Mockito.when;
+
+import java.io.IOException;
+
+import org.apache.http.HttpException;
+import org.apache.http.HttpRequest;
+import org.apache.http.RequestLine;
+import org.apache.http.protocol.HttpContext;
+import org.junit.Before;
+import org.junit.Test;
+import org.mockito.InOrder;
+
+import com.github.kristofa.brave.BraveHttpHeaders;
+import com.github.kristofa.brave.ClientTracer;
+import com.github.kristofa.brave.SpanId;
+
+public class BraveHttpRequestInterceptorTest {
+
+    private static final String PATH = "/path/path2";
+    private static final String METHOD = "GET";
+    private static final Long SPAN_ID = 85446l;
+    private static final Long PARENT_SPAN_ID = 58848l;
+    private static final Long TRACE_ID = 54646l;
+
+    private BraveHttpRequestInterceptor interceptor;
+    private ClientTracer mockClientTracer;
+    private HttpRequest httpRequest;
+    private HttpContext mockHttpContext;
+
+    @Before
+    public void setUp() throws Exception {
+        mockClientTracer = mock(ClientTracer.class);
+        interceptor = new BraveHttpRequestInterceptor(mockClientTracer);
+        httpRequest = mock(HttpRequest.class);
+        final RequestLine mockRequestLine = mock(RequestLine.class);
+        when(mockRequestLine.getUri()).thenReturn(PATH);
+        when(mockRequestLine.getMethod()).thenReturn(METHOD);
+        when(httpRequest.getRequestLine()).thenReturn(mockRequestLine);
+
+        mockHttpContext = mock(HttpContext.class);
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void testBraveHttpRequestInterceptor() {
+        new BraveHttpRequestInterceptor(null);
+    }
+
+    @Test
+    public void testProcessNoTracing() throws HttpException, IOException {
+
+        when(mockClientTracer.startNewSpan(PATH)).thenReturn(null);
+
+        interceptor.process(httpRequest, mockHttpContext);
+
+        final InOrder inOrder = inOrder(mockClientTracer, httpRequest);
+
+        inOrder.verify(mockClientTracer).startNewSpan(PATH);
+        inOrder.verify(httpRequest).addHeader(BraveHttpHeaders.Sampled.getName(), "false");
+        inOrder.verify(mockClientTracer).submitBinaryAnnotation("request", METHOD + " " + PATH);
+        inOrder.verify(mockClientTracer).setClientSent();
+        verifyNoMoreInteractions(mockClientTracer);
+    }
+
+    @Test
+    public void testProcessTracing() throws HttpException, IOException {
+
+        final SpanId spanId = mock(SpanId.class);
+        when(spanId.getSpanId()).thenReturn(SPAN_ID);
+        when(spanId.getParentSpanId()).thenReturn(PARENT_SPAN_ID);
+        when(spanId.getTraceId()).thenReturn(TRACE_ID);
+        when(mockClientTracer.startNewSpan(PATH)).thenReturn(spanId);
+
+        interceptor.process(httpRequest, mockHttpContext);
+
+        final InOrder inOrder = inOrder(mockClientTracer, httpRequest);
+
+        inOrder.verify(mockClientTracer).startNewSpan(PATH);
+        inOrder.verify(httpRequest).addHeader(BraveHttpHeaders.Sampled.getName(), "true");
+        inOrder.verify(httpRequest).addHeader(BraveHttpHeaders.TraceId.getName(), String.valueOf(TRACE_ID));
+        inOrder.verify(httpRequest).addHeader(BraveHttpHeaders.SpanId.getName(), String.valueOf(SPAN_ID));
+        inOrder.verify(httpRequest).addHeader(BraveHttpHeaders.ParentSpanId.getName(), String.valueOf(PARENT_SPAN_ID));
+        inOrder.verify(mockClientTracer).submitBinaryAnnotation("request", METHOD + " " + PATH);
+        inOrder.verify(mockClientTracer).setClientSent();
+        verifyNoMoreInteractions(mockClientTracer);
+
+    }
+
+    @Test
+    public void testProcessTracingNoParentId() throws HttpException, IOException {
+
+        final SpanId spanId = mock(SpanId.class);
+        when(spanId.getSpanId()).thenReturn(SPAN_ID);
+        when(spanId.getParentSpanId()).thenReturn(null);
+        when(spanId.getTraceId()).thenReturn(TRACE_ID);
+        when(mockClientTracer.startNewSpan(PATH)).thenReturn(spanId);
+
+        interceptor.process(httpRequest, mockHttpContext);
+
+        final InOrder inOrder = inOrder(mockClientTracer, httpRequest);
+
+        inOrder.verify(mockClientTracer).startNewSpan(PATH);
+        inOrder.verify(httpRequest).addHeader(BraveHttpHeaders.Sampled.getName(), "true");
+        inOrder.verify(httpRequest).addHeader(BraveHttpHeaders.TraceId.getName(), String.valueOf(TRACE_ID));
+        inOrder.verify(httpRequest).addHeader(BraveHttpHeaders.SpanId.getName(), String.valueOf(SPAN_ID));
+        inOrder.verify(mockClientTracer).submitBinaryAnnotation("request", METHOD + " " + PATH);
+        inOrder.verify(mockClientTracer).setClientSent();
+        verifyNoMoreInteractions(mockClientTracer);
+
+    }
+
+}