Merge pull request #95 from palazzem/spring-boot-example

[example] update Spring Boot example with a simplified documentation

Author: Emanuele Palazzetti

dd-trace-examples/spring-boot-jdbc/README.md

@@ -1,112 +1,60 @@
-## Spring-boot + JDBC example
-### Purpose
+## Spring-boot 
 
-This project aims at demonstrating how to instrument legacy code based on the SpringBoot framework
-and a JDBC connection.
+This project provides a simple API using [Spring Boot][1]. The framework is supported and auto-instrumentation is used
+to trace the endpoints.
 
-We are using the [opentracing contributions](https://github.com/opentracing-contrib) in order to trace:
- * All the JDBC queries and calls to the DB
- * All incoming HTTP calls
- 
- 
-The instrumentation is injected via the Datadog Java Agent. Java agents allows developers to execute
-some code before starting the legacy application. All operations for instrumenting the code are done
-at this time.
+[1]: https://projects.spring.io/spring-boot/
 
 ### Run the demo
 
-The demo consistes into a very simple backend backed by an in-memory db. The Spring Boot application exposes
-2 endpoints that can be reached via an HTTP request.
-
 #### Prerequisites
-1. Run the latest version of Datadog Agent. For instance, you can run it through a docker container: 
-  `docker run -d --name dd-agent -v /var/run/docker.sock:/var/run/docker.sock:ro -v /proc/:/host/proc/:ro -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro -e API_KEY=<YOUR-API-KEY> -e SD_BACKEND=docker -p 8126:8126 -P  datadog/docker-dd-agent:latest`
-    
-#### Run the application
 
-The first step is to edit the Spring configuration file and the Datadog Tracer file and check if the
-connection properties are okay.
-
-```properties
-# file: src/resources/application.properties
-
-spring.datasource.driver-class-name=io.opentracing.contrib.jdbc.TracingDriver
-spring.datasource.url=jdbc:tracing:h2:mem:spring-test
+Be sure to build the project so that the latest version of ``dd-trace-java`` components are used. You can build
+all libraries and examples launching from the ``dd-trace-java`` root folder:
+```bash
+./gradlew clean shadowJar
 ```
 
-```yaml
-# file: src/resources/dd-trace.yaml
-
-# Service name used if none is provided in the app
-defaultServiceName: spring-app
-
-# The writer to use.
-writer:
-  type: DDAgentWriter
-  host: localhost
-  port: 8126
-
-# The sampler to use.
-sampler:
-  type: AllSampler
+Then you can launch the Datadog agent as follows:
+```bash
+cd dd-trace-examples/spring-boot-jdbc
+DD_API_KEY=<your_datadog_api_key> docker-compose up -d
 ```
 
-Then, is to run the Spring Application along the Datadog Java Agent.
-
-- So first download the `jar` file from the main repository.
-
-*NOTE:* While in beta, the latest version is best found on the [Snapshot Repo](https://oss.jfrog.org/artifactory/oss-snapshot-local/com/datadoghq/). 
-
-```
-# download the latest published version:
-wget -O dd-java-agent.jar 'https://search.maven.org/remote_content?g=com.datadoghq&a=dd-java-agent&v=LATEST'
-```
+A valid ``DD_API_KEY`` is required to post collected traces to the Datadog backend.
 
-- Then add the following JVM argument when launching your application (in IDE, using Maven/Gradle run or simply in collaboration with the `>java -jar` command):
+#### Run the application
 
-```
--javaagent:/path/to/the/dd-java-agent.jar
+To launch the application, just:
+```bash
+./gradlew bootRun
 ```
 
-- Finally, build and run the application with the `javaagent` option. (Note, actual flag set in `spring-boot-jdbc.gradle`)
-
-```
-cd path/to/dd-trace-examples/spring-boot-jdbc
-./gradlew bootRun -Pjavaagent=/path/to/the/dd-java-agent.jar
-```
+The ``bootRun`` Gradle command appends automatically the ``-javaagent`` argument, so that you don't need to specify
+the path of the Java Agent. Gradle executes the ``:dd-trace-examples:spring-boot-jdbc:bootRun`` task until you
+stop it.
 
 ### Generate traces
 
-Once the application runs. Go to the following urls:
-
-* [http://localhost:8080/demo/add?name=foo&email=bar](http://localhost:8080/demo/add?name=foo&email=bar)
-* [http://localhost:8080/demo/all](http://localhost:8080/demo/all)
+Once the Gradle task is running. Go to the following urls:
 
-Then, you will able to see traces directly to the DataDog UI.
+* [http://localhost:8080/user/add?name=foo&email=bar](http://localhost:8080/user/add?name=foo&email=bar)
+* [http://localhost:8080/user/all](http://localhost:8080/user/all)
 
-![Datadog APM](apm.png)
-
-### How did we instrument this project?
-
-If you want to instrument your own code (Spring-boot and JDBC based), here is how you should do it.
-
-#### Dependencies
+Then get back to Datadog and wait a bit to see a trace coming.
 
 #### Auto-instrumentation with the `dd-trace-agent`
 
-The instrumentation is entirely done by the datadog agent which embed a set of rules that automatically recognizes & instruments:
+The instrumentation is entirely done by the datadog agent which embed a set of rules that automatically recognizes &
+instruments:
 
 - The java servlet filters
+- The JDBC driver
 
-The datadog agent embeds the [open tracing java agent](https://github.com/opentracing-contrib/java-agent).
+The Java Agent embeds the [OpenTracing Java Agent](https://github.com/opentracing-contrib/java-agent).
 
-JDBC is not automatically instrumented yet by the agent. So you should follow the instructions on the next section.
+#### Note for JDBC tracing configuration
 
-#### JDBC tracing configuration
-
-Just edit your `application.properties` [file](src/main/resources/application.properties)
-and add `:tracing` right after the `jdbc` string as shown below.
-
-```properties
-spring.datasource.url= jdbc:tracing:mysql://localhost:3306/springdb
-```
+JDBC is not automatically instrumented by the Java Agent, so we changed the `application.properties`
+[file](src/main/resources/application.properties) to use the OpenTracing Driver. Without this step in your
+applications, the JDBC driver will not be instrumented.

dd-trace-examples/spring-boot-jdbc/apm.png

@@ -0,0 +1,7 @@
+ddagent:
+    image: datadog/docker-dd-agent
+    environment:
+        - DD_BIND_HOST=0.0.0.0
+        - DD_API_KEY
+    ports:
+        - "127.0.0.1:8126:8126"

dd-trace-examples/spring-boot-jdbc/docker-compose.yml

@@ -1,6 +1,7 @@
+# you must set the following so that OpenTracing traced driver is used
 spring.datasource.driver-class-name=io.opentracing.contrib.jdbc.TracingDriver
 spring.datasource.url=jdbc:tracing:h2:mem:spring-test
-#spring.datasource.driver-class-name=org.h2.Driver
-#spring.datasource.url=jdbc:h2:mem:spring-test
+
+# set the logging level
 logging.level.root=INFO
 logging.level.com.datadoghq.trace=DEBUG

dd-trace-examples/spring-boot-jdbc/src/main/resources/application.properties

@@ -0,0 +1,9 @@
+defaultServiceName: example-spring-boot
+
+writer:
+  type: DDAgentWriter
+  host: localhost
+  port: 8126
+
+sampler:
+  type: AllSampler