Merge pull request #95 from palazzem/spring-boot-example
[example] update Spring Boot example with a simplified documentation
This commit is contained in:
Emanuele Palazzetti
GitHub
commit
4927f40392
|
|
@ -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`
|
||||
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
A valid ``DD_API_KEY`` is required to post collected traces to the Datadog backend.
|
||||
|
||||
#### 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
|
||||
To launch the application, just:
|
||||
```bash
|
||||
./gradlew bootRun
|
||||
```
|
||||
|
||||
```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, 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'
|
||||
```
|
||||
|
||||
- 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):
|
||||
|
||||
```
|
||||
-javaagent:/path/to/the/dd-java-agent.jar
|
||||
```
|
||||
|
||||
- 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:
|
||||
Once the Gradle task is running. 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)
|
||||
* [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)
|
||||
|
||||
Then, you will able to see traces directly to the DataDog UI.
|
||||
|
||||
|
||||
|
||||
### 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.
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 112 KiB |
|
|
@ -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"
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -0,0 +1,9 @@
|
|||
defaultServiceName: example-spring-boot
|
||||
|
||||
writer:
|
||||
type: DDAgentWriter
|
||||
host: localhost
|
||||
port: 8126
|
||||
|
||||
sampler:
|
||||
type: AllSampler
|
||||
Loading…
Reference in New Issue