Skip to content

Commit 5d911e5

Browse files
renaudboutetrenaudboutet
authored
Merge pull request #6 from DataDog/dev
Alpha release
2 parents 5f13cdb + dad2391 commit 5d911e5

101 files changed

Lines changed: 4886 additions & 651 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,9 @@ Thumbs.db
3232
# Others #
3333
##########
3434
/logs/*
35+
36+
37+
38+
/target
39+
**/target/
40+
/dd-java-agent/dependency-reduced-pom.xml

‎README.md‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,23 @@
1-
# raclette-java
2-
Experimental repo around Java APM instrumentation
1+
## Datadog APM - Java Agent and Core Tracer
2+
3+
Datadog APM gives you powerful tools to observe and optimize modern applications.
4+
It enables you to see exactly where your requests go and which services or calls are contributing to overall latency.
5+
The lightweight agent is designed to be deployed on every host in your infrastructure,
6+
so it generates gap-free distributed request traces even in the most complex microservice architectures.
7+
8+
This repository offers you all resources you needed to start to instrument your project and
9+
gather all traces in your [Datadog](https://app.datadoghq.com) account.
10+
11+
![](https://datadog-live.imgix.net/img/blog/set-and-monitor-slas/a-postgres-90-percent.png?fit=max)
12+
13+
14+
### Start in minutes
15+
16+
* [Introduction to the Datadog APM](https://www.datadoghq.com/apm/). Learn what you can do with the Next-Gen APM and how to get started.
17+
* [Install the Datadog Java agent](dd-java-agent). Instructions for supported technologies, web-servers and frameworks.
18+
* [Browse examples](dd-trace-examples). See how to instrument legacy projects based on the most used tehcnologies.
19+
* [DD Trace API](dd-trace). We choose to embrace the Opentracting initiative. So feel free to use the Trace Java API to customize your instrumentation.
20+
21+
### Help or questions?
22+
23+
And for any questions or feedback, feel free to send us an email: support@datadoghq.com

‎dd-java-agent/README.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# Datadog Java Agent for APM
2+
3+
*Minimal Java version required: 1.7*
4+
5+
This is a Java Agent made for instrumenting Java applications using the Datadog Tracer. Once attached to one of your JVM you should see traces into your [Datadog APM](https://app.datadoghq.com/apm/search).
6+
7+
Tracing instrumentations can be done in 2 ways:
8+
9+
- Automatically over a set of [supported Web servers, frameworks or database drivers](#instrumented-frameworks)
10+
- By using the [`@trace` annotation](#custom-instrumentations)
11+
12+
:heavy_exclamation_mark: **Warning:** This library is currently at Alpha stage. This means that even if we rigorously tested instrumentations you may experience strange behaviors depending on your running environment. It must evolve quickly though. For any help please contact [support@datadoghq.com](mailto:support@datadoghq.com).
13+
14+
## Quick start
15+
16+
### 1. Install the Datadog Agent on your OS
17+
18+
The Java instrumentation library works in collaboration with a local agent that transmits the traces to Datadog. To install it with tracing please follow these steps:
19+
20+
- Run the latest [Datadog Agent](https://app.datadoghq.com/account/settings#agent) (version 5.11.0 or above)
21+
- [Enable APM in the Datadog Agent configuration file](https://app.datadoghq.com/apm/docs/tutorials/configuration) `/etc/dd-agent/datadog.conf`.
22+
23+
```
24+
[Main]
25+
# Enable the trace agent.
26+
apm_enabled: true
27+
```
28+
- [Restart the Agent](http://docs.datadoghq.com/guides/basic_agent_usage/)
29+
30+
### 2. Instrument your application
31+
32+
To instrument your project or your servers you simply have to declare the provided `jar` file in your JVM arguments as a valid `-javaagent:`.
33+
34+
- So first download the `jar` file from the main repository.
35+
36+
```
37+
# use latest version
38+
curl -OL http://central.maven.org/maven2/com/datadoghq/dd-java-agent/0.0.1/dd-java-agent-0.0.1.jar
39+
```
40+
41+
- Then add the following JVM argument when launching your application (in IDE, using Maven run or simply in collaboration with the `>java -jar` command):
42+
43+
```
44+
-javaagent:/path/to/the/dd-java-agent-0.0.1.jar
45+
```
46+
47+
That's it! If you did this properly the agent was executed at pre-main, had detected and instrumented the supported libraries and custom traces. You should then see traces on [Datadog APM](https://app.datadoghq.com/apm/search).
48+
49+
## Configuration
50+
51+
Configuration is done through a default `dd-trace.yaml` file as a resource in the classpath.
52+
53+
```yaml
54+
# Service name used if none is provided in the app
55+
defaultServiceName: java-app
56+
57+
# The writer to use.
58+
# Could be: LoggingWritter or DDAgentWriter (default)
59+
writer:
60+
# LoggingWriter: Spans are logged using the application configuration
61+
# DDAgentWriter: Spans are forwarding to a Datadog Agent
62+
# - Param 'host': the hostname where the DD Agent running (default: localhost)
63+
# - Param 'port': the port to reach the DD Agent (default: 8126)
64+
type: DDAgentWriter
65+
host: localhost
66+
port: 8126
67+
68+
# The sampler to use.
69+
# Could be: AllSampler (default) or RateSampler
70+
sampler:
71+
# AllSampler: all spans are reported to the writer
72+
# RateSample: only a portion of spans are reported to the writer
73+
# - Param 'rate': the portion of spans to keep
74+
type: AllSampler
75+
# Skip some traces if the root span tag values matches some regexp patterns
76+
# skipTagsPatterns: {"http.url": ".*/demo/add.*"}
77+
78+
# Enable custom tracing (Custom annotations for now)
79+
enableCustomTracing: true
80+
81+
# Disable some instrumentations
82+
# disabledInstrumentations: ["apache http", "mongo", "jetty", "tomcat", ...]
83+
```
84+
85+
If you want to change it, you must create it in your project.
86+
87+
## Instrumented frameworks
88+
89+
When attached to an application the `dd-java-agent` automatically instruments the following set of frameworks & servers.
90+
91+
### Frameworks
92+
93+
| FWK | Versions | Comments |
94+
| ------------- |:-------------:| ----- |
95+
| OkHTTP | 3.x | HTTP client calls with [cross-process](http://opentracing.io/documentation/pages/api/cross-process-tracing.html) headers |
96+
| Apache HTTP Client | 4.x |HTTP client calls with [cross-process](http://opentracing.io/documentation/pages/api/cross-process-tracing.html) headers|
97+
| AWS SDK | 1.x | Trace all client calls to any AWS service |
98+
| Web Servlet Filters| Depending on server | See [Servers](#servers) section |
99+
100+
### Servers
101+
102+
| FWK | Versions | Comments |
103+
| ------------- |:-------------:| -----|
104+
| Jetty | 8.x, 9.x | Trace all incoming HTTP calls with [cross-process](http://opentracing.io/documentation/pages/api/cross-process-tracing.html) capabilities |
105+
| Tomcat | 8.0.x, 8.5.x & 9.x | Trace all incoming HTTP calls with [cross-process](http://opentracing.io/documentation/pages/api/cross-process-tracing.html) capabilities |
106+
107+
Modern web application frameworks such as Dropwizard or Spring Boot are automatically instrumented thanks to these servers instrumentation. (See [example projects](#other-useful-resources))
108+
109+
### Databases
110+
| FWK | Versions | Comments |
111+
| ------------- |:-------------:| ----- |
112+
|Spring JDBC| 4.x | Please check the following [JDBC instrumentation](#jdbc-instrumentation) section |
113+
|Hibernate| 5.x | Please check the following [JDBC instrumentation](#jdbc-instrumentation) section |
114+
| MongoDB | 3.x | Intercepts all the calls from the MongoDB client |
115+
116+
#### JDBC instrumentation
117+
118+
By enabling the JDBC instrumentation you'll intercept all the client calls to the following DBs: MySQL, PostgreSQL, H2, HSQLDB, IBM DB2, SQL Server, Oracle, MariaDB, etc...
119+
120+
But unfortunately this can not be done entirely automatically today. To enable tracing please follow the instructions provided on the [java-jdbc opentracing contrib project](https://github.com/opentracing-contrib/java-jdbc#usage).
121+
122+
We also provide an [example project with Spring Boot & MySQL](web application frameworks).
123+
124+
### Disabling instrumentations
125+
126+
If for some reasons you need to disable an instrumentation you should uncomment the `disabledInstrumentations: ` attribute in the configuration and provide a list as illustrated below:
127+
128+
```yaml
129+
...
130+
131+
# Disable a few instrumentations
132+
disabledInstrumentations: ["apache http", "mongo", "tomcat"]
133+
134+
...
135+
```
136+
137+
###
138+
139+
## Custom instrumentations
140+
141+
### The `@trace` annotation
142+
143+
By adding the `@trace` annotation to a method the `dd-java-agent` automatically measures the execution time.
144+
145+
```java
146+
@Trace
147+
public void myMethod() throws InterruptedException{
148+
...
149+
}
150+
```
151+
152+
By default, the operation name attach to the spawn span will be the name of the method and no meta tags will be attached.
153+
154+
You can use the the `operationName` and `tagsKV` attributes to customize your trace:
155+
156+
```java
157+
@Trace(operationName="Before DB",tagsKV={"mytag","myvalue"})
158+
public void myMethod() throws InterruptedException{
159+
....
160+
}
161+
```
162+
163+
### Enabling custom tracing
164+
165+
- Add the agent as a dependency of your project
166+
167+
```xml
168+
<dependency>
169+
<groupId>com.datadoghq</groupId>
170+
<artifactId>dd-java-agent</artifactId>
171+
<version>{version}</version>
172+
</dependency>
173+
```
174+
175+
- Enable custom tracing by adding in the `dd-trace.yaml` config file `enableCustomTracing: true`
176+
177+
If you want to see custom tracing in action please run the [Dropwizard example](https://github.com/DataDog/dd-trace-java/blob/dev/dd-trace-examples/dropwizard-mongo-client/).
178+
179+
## Other useful resources
180+
181+
Before instrumenting your own project you might want to run the provided examples:
182+
183+
- [Dropwizard/MongoDB & Cross process client calls](https://github.com/DataDog/dd-trace-java/blob/dev/dd-trace-examples/dropwizard-mongo-client/)
184+
- [Springboot & MySQL over JDBC](https://github.com/DataDog/dd-trace-java/tree/dev/dd-trace-examples/spring-boot-jdbc)
185+
186+
Other links that you might want to read:
187+
188+
- Install on [Docker](https://app.datadoghq.com/apm/docs/tutorials/docker)
189+
- Datadog's APM [Terminology](https://app.datadoghq.com/apm/docs/tutorials/terminology)
190+
- [FAQ](https://app.datadoghq.com/apm/docs/tutorials/faq)
191+

0 commit comments

Comments
 (0)