[example] update Spring Boot example with a simplified documentation
MODIFY
dd-trace-examples/spring-boot-jdbc/README.md
dd-trace-examples/spring-boot-jdbc/README.md
-## 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.
+A valid ``DD_API_KEY`` is required to post collected traces to the Datadog backend.
-*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'
-```
-
-- 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.

DELETE
dd-trace-examples/spring-boot-jdbc/apm.png
dd-trace-examples/spring-boot-jdbc/apm.png
Binary files a/dd-trace-examples/spring-boot-jdbc/apm.png and /dev/null differ

ADD
dd-trace-examples/spring-boot-jdbc/docker-compose.yml
+ddagent:
+ image: datadog/docker-dd-agent
+ environment:
+ - DD_BIND_HOST=0.0.0.0
+ - DD_API_KEY
+ ports:
+ - "127.0.0.1:8126:8126"

MODIFY
dd-trace-examples/spring-boot-jdbc/src/main/resources/application.properties
dd-trace-examples/spring-boot-jdbc/src/main/resources/application.properties
+# 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

ADD
dd-trace-examples/spring-boot-jdbc/src/main/resources/dd-trace.yaml
+defaultServiceName: example-spring-boot
+
+writer:
+ type: DDAgentWriter
+ host: localhost
+ port: 8126
+
+sampler:
+ type: AllSampler

[example] update Spring Boot example with a simplified documentation