Refactors build to use a parent pom and refactors README (#49)

openzipkin · Oct 9, 2020 · eaf4118 · eaf4118
1 parent 7860a66
commit eaf4118
Show file tree

Hide file tree

Showing 46 changed files with 413 additions and 579 deletions.
diff --git a/.dockerignore b/.dockerignore
@@ -5,6 +5,7 @@
 **/target
 
 **/.idea
+**/*.iml
 **/*.md
 
 **/Dockerfile

diff --git a/.github/workflows/docker-tests.yml b/.github/workflows/docker-tests.yml
@@ -11,7 +11,7 @@ jobs:
   build-on-linux:
     strategy:
       matrix:
-        docker-target: [armeria, webmvc25-jetty, webmvc3-jetty, webmvc4-boot, webmvc4-jetty]
+        project: [armeria, webmvc25-jetty, webmvc3-jetty, webmvc4-boot, webmvc4-jetty]
     runs-on: ubuntu-latest
     name: Build and verify Docker images
     steps:
@@ -30,16 +30,12 @@ jobs:
         uses: actions/checkout@v2
         with:
           fetch-depth: 1
-      - name: Build Docker image openzipkin/example-brave:${{ matrix.docker-target }}-test
-        run: |
-          TARGET=${{ matrix.docker-target }}
-          DOCKER_BUILDKIT=1 docker build -f docker/Dockerfile \
-          -t openzipkin/example-brave:${TARGET}-test \
-          --target ${TARGET} --build-arg target=${TARGET} .
-      - name: Verify Docker image openzipkin/example-brave:${{ matrix.docker-target }}-test
+      - name: Build Docker image openzipkin/example-brave:${{ matrix.project }}-test
+        run:  docker/build_image ${{ matrix.project }} ${{ matrix.project }}-test
+      - name: Verify Docker image openzipkin/example-brave:${{ matrix.project }}-test
         run: |
           # This just makes sure containers run and the HEALTHCHECK works (for now..)
-          IMAGE=openzipkin/example-brave:${{ matrix.docker-target }}-test
+          IMAGE=openzipkin/example-brave:${{ matrix.project }}-test
           docker run --rm --name frontend -d ${IMAGE} frontend
           docker run --rm --name backend -d ${IMAGE} backend
           docker/bin/block-on-health frontend || exit 1

diff --git a/README.md b/README.md
@@ -1,72 +1,85 @@
-# Basic example showing distributed tracing across servlet applications
-This is an example app where two Servlet (Java) services collaborate on
-an http request. Notably, timing of these requests are recorded into
-[Zipkin](https://zipkin.io/), a distributed tracing system. This allows
-you to see the how long the whole operation took, as well how much time
-was spent in each service.
+# Basic example showing distributed tracing across HTTP applications
+This is an example app where two Java services collaborate on a request.
 
-Here's an example of what it looks like:
+Notably, these services send data to [Zipkin](https://zipkin.io/), a
+distributed tracing system. Zipkin allows you to see the how long the operation
+took, as well how much time was spent in each service.
 
-<img width="979" alt="zipkin screen shot" src="https://user-images.githubusercontent.com/6180701/66194897-cb7d1a80-e695-11e9-960d-105d99aa6465.png">
+Here's an example of what it looks like:
 
-This example was ported from https://github.com/openzipkin/sleuth-webmvc-example
+<img width="979" alt="zipkin screen shot" src="https://user-images.githubusercontent.com/64215/95572045-f98cfb80-0a5b-11eb-9d3b-9a1b9b1db6b4.png">
 
 # Implementation Overview
-
-Web requests are served by [Spring MVC](https://spring.io/guides/gs/rest-service/) controllers,
-and tracing is automatically performed for you by [Brave](https://github.com/openzipkin/brave).
-
-This example intentionally avoids advanced topics like async and messaging,
-even though Brave supports that, too. Once you get familiar with things,
-you can play with more interesting [Brave instrumentation](https://github.com/openzipkin/brave/tree/master/instrumentation).
+This example has two services: frontend and backend. Both are [instrumented](https://github.com/openzipkin/brave/tree/master/instrumentation)
+to send tracing data to a third service [Zipkin](https://zipkin.io/). [Brave](https://github.com/openzipkin/brave)
+performs this function.
 
 # Running the example
-This example has two services: frontend and backend. They both report trace data to zipkin. To setup the demo, you need to start Frontend, Backend and Zipkin.
+To setup the demo, you need to start Frontend, Backend and Zipkin. You can do
+this using Java commands or Docker.
 
 Once the services are started, open http://localhost:8081/
-* This will call the backend (http://localhost:9000/api) and show the result, which defaults to a formatted date.
+* This calls the backend (http://localhost:9000/api) and shows its result: a formatted date.
 
-Next, you can view traces that went through the backend via http://localhost:9411/?serviceName=backend
+Afterwards, you can view traces that went through the backend via http://localhost:9411/?serviceName=backend
 * This is a locally run zipkin service which keeps traces in memory
 
-## Starting the Services
+## Starting the services
 
-### Servlet Container Option
-In a separate tab or window, start each of [brave.webmvc.Frontend](/webmvc4-jetty/src/main/java/brave/webmvc/Frontend.java)
-and [brave.webmvc.Backend](/webmvc4-jetty/src/main/java/brave/webmvc/Backend.java):
+First, start [Zipkin](https://zipkin.io/). This stores and queries traces
+reported by the example services. 
+
+Starting Zipkin with Java:
 ```bash
-# choose webmvc25 webmvc3 or webmvc4
-$ cd webmvc4
-$ mvn jetty:run -Pfrontend
-$ mvn jetty:run -Pbackend
+curl -sSL https://zipkin.io/quickstart.sh | bash -s
+java -jar zipkin.jar
 ```
 
-### Spring Boot Option
-In a separate tab or window, start each of [brave.webmvc.Frontend](/webmvc4-boot/src/main/java/brave/webmvc/Frontend.java)
-and [brave.webmvc.Backend](/webmvc4-boot/src/main/java/brave/webmvc/Backend.java):
+### Armeria
+
+Here are our [Armeria](https://armeria.dev/) examples:
+* [HTTP](armeria) - uses Armeria APIs to serve and invoke HTTP requests
+
+#### Starting Armeria with Java
+In a separate tab or window, start each of [brave.example.Frontend](/armeria/src/main/java/brave/example/Frontend.java)
+and [brave.example.Backend](/armeria/src/main/java/brave/example/Backend.java):
 ```bash
-$ cd webmvc4-boot
-$ mvn compile exec:java -Dexec.mainClass=brave.webmvc.Backend
-$ mvn compile exec:java -Dexec.mainClass=brave.webmvc.Frontend
+$ cd armeria
+$ mvn compile exec:java -Dexec.mainClass=brave.example.Backend
+$ mvn compile exec:java -Dexec.mainClass=brave.example.Frontend
 ```
 
-Next, run [Zipkin](https://zipkin.io/), which stores and queries traces
-reported by the above services.
+### Servlet
+Our Servlet examples use [Jetty](https://www.eclipse.org/jetty/) and
+[Spring MVC](https://spring.io/guides/gs/rest-service/) controllers. These
+examples primarily show how configuration works in XML or Java configuration:
+* [WebMVC 2.5](webmvc25-jetty) - Spring XML on Servlet 2.5 container
+* [WebMVC 3](webmvc3-jetty) - Spring XML on Servlet 3 container
+* [WebMVC 4](webmvc4-jetty) - Spring Java Config on Servlet 3 container
 
+#### Starting Jetty with Java
+In a separate tab or window, start each of [brave.example.Frontend](/webmvc4-jetty/src/main/java/brave/example/Frontend.java)
+and [brave.example.Backend](/webmvc4-jetty/src/main/java/brave/example/Backend.java):
 ```bash
-curl -sSL https://zipkin.io/quickstart.sh | bash -s
-java -jar zipkin.jar
+$ cd webmvc4-jetty
+$ mvn jetty:run -Pfrontend
+$ mvn jetty:run -Pbackend
 ```
 
-### Docker Option
-You can run any configuration using pre-built Docker images. Look at
-[docker](docker) for examples.
+### Spring Boot
+Here are our Spring Boot examples:
+* [Spring Boot 1.5](webmvc4-boot) - [Spring MVC 4](https://spring.io/guides/gs/rest-service/)
+
+#### Starting Spring Boot with Java
+In a separate tab or window, start each of [brave.example.Frontend](/webmvc4-boot/src/main/java/brave/example/Frontend.java)
+and [brave.example.Backend](/webmvc4-boot/src/main/java/brave/example/Backend.java):
+```bash
+$ cd webmvc4-boot
+$ mvn compile exec:java -Dexec.mainClass=brave.example.Backend
+$ mvn compile exec:java -Dexec.mainClass=brave.example.Frontend
+```
 
 ## Configuration tips
-To show how wiring works, we have three copies of the same project
-* [WebMVC 2.5](webmvc25-jetty) - Spring XML on Servlet 2.5 container
-* [WebMVC 3](webmvc3-jetty) - Spring XML on Servlet 3 container
-* [WebMVC 4](webmvc4-jetty) - Spring Java Config on Servlet 3 container
 
 There are some interesting details that apply to both
 * If you pass the header `user_name` Brave will automatically propagate it to the backend!

diff --git a/armeria/README.md b/armeria/README.md
@@ -1,36 +1,7 @@
-# Basic example showing distributed tracing across Armeria apps
-This is an example app where two Armeria (Java) services collaborate on an http request. Notably, timing of these requests are recorded into [Zipkin](http://zipkin.io/), a distributed tracing system. This allows you to see the how long the whole operation took, as well how much time was spent in each service.
+## Tracing Example: Armeria
 
-Here's an example of what it looks like
-<img width="960" alt="zipkin screen shot" src="https://user-images.githubusercontent.com/64215/40405563-1885eb04-5e98-11e8-9bd6-53bcd09711d2.png">
+Instead of servlet, this uses [Armeria](https://armeria.dev/) to serve HTTP
+requests. Both services run as a normal Java application.
 
-# Implementation Overview
-
-Web requests are served by [Armeria](https://line.github.io/armeria/server-basics.html) services, which trace requests by using the [Zipkin plugin](https://line.github.io/armeria/advanced-zipkin.html).
-
-These traces are sent out of process over http to Zipkin.
-
-This example intentionally avoids advanced topics like async and load balancing, eventhough Armeria supports them.
-
-# Running the example
-This example has two services: frontend and backend. They both report trace data to zipkin. To setup the demo, you need to start Frontend, Backend and Zipkin.
-
-Once the services are started, open http://localhost:8081/
-* This will call the backend (http://localhost:9000/api) and show the result, which defaults to a formatted date.
-
-Next, you can view traces that went through the backend via http://localhost:9411/?serviceName=backend
-* This is a locally run zipkin service which keeps traces in memory
-
-## Starting the Services
-In a separate tab or window, start each of [Frontend](/brave/example/armeria/Frontend.java) and [Backend](/brave/example/armeria/Backend.java):
-```bash
-$ mvn compile exec:java -Dexec.mainClass=brave.example.Frontend
-$ mvn compile exec:java -Dexec.mainClass=brave.example.Backend
-```
-
-Next, run [Zipkin](http://zipkin.io/), which stores and queries traces reported by the above services.
-
-```bash
-curl -sSL https://zipkin.io/quickstart.sh | bash -s
-java -jar zipkin.jar
-```
+*   brave.example.Frontend and Backend : HTTP controllers with a trace configuration hook
+*   brave.example.HttpTracingFactory : Configures the tracing subsystem
diff --git a/armeria/pom.xml b/armeria/pom.xml
@@ -3,24 +3,25 @@
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>io.zipkin.brave.example</groupId>
+    <artifactId>brave-example-parent</artifactId>
+    <version>1.0-SNAPSHOT</version>
+    <relativePath>../parent-pom.xml</relativePath>
+  </parent>
 
-  <groupId>io.zipkin.brave.example</groupId>
   <artifactId>brave-example-armeria</artifactId>
-  <version>1.0-SNAPSHOT</version>
   <packaging>jar</packaging>
 
   <name>brave-example-armeria</name>
-  <description>Tracing Example: Armeria</description>
+  <description>Tracing Example: Armeria/ Java 15</description>
 
   <properties>
-    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-
-    <maven.compiler.source>1.8</maven.compiler.source>
-    <maven.compiler.target>1.8</maven.compiler.target>
+    <jre.version>15</jre.version>
+    <maven.compiler.release>8</maven.compiler.release>
 
     <!-- temporarily revert 1.1.0 until https://github.com/line/armeria/pull/3023 is discussed -->
     <armeria.version>1.0.0</armeria.version>
-    <brave.version>5.12.6</brave.version>
   </properties>
 
   <dependencies>
@@ -60,42 +61,6 @@
         <type>pom</type>
         <scope>import</scope>
       </dependency>
-      <dependency>
-        <groupId>io.zipkin.brave</groupId>
-        <artifactId>brave-bom</artifactId>
-        <version>${brave.version}</version>
-        <type>pom</type>
-        <scope>import</scope>
-      </dependency>
     </dependencies>
   </dependencyManagement>
-
-  <build>
-    <pluginManagement>
-      <plugins>
-        <plugin>
-          <groupId>org.apache.maven.plugins</groupId>
-          <artifactId>maven-dependency-plugin</artifactId>
-          <version>3.1.2</version>
-        </plugin>
-      </plugins>
-    </pluginManagement>
-
-    <plugins>
-      <plugin>
-        <artifactId>maven-compiler-plugin</artifactId>
-        <version>3.8.1</version>
-        <configuration>
-          <optimize>true</optimize>
-          <debug>true</debug>
-        </configuration>
-      </plugin>
-
-      <plugin>
-        <groupId>org.codehaus.mojo</groupId>
-        <artifactId>exec-maven-plugin</artifactId>
-        <version>3.0.0</version>
-      </plugin>
-    </plugins>
-  </build>
 </project>