Skip to content

Commit 58c9cba

Browse files
gpolaerttylerbenson
gpolaert
authored and
tylerbenson
committed
Documentation
1 parent 07b2324 commit 58c9cba

File tree

1 file changed

+119
-68
lines changed

1 file changed

+119
-68
lines changed

‎dd-trace/README.md

Lines changed: 119 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,18 @@
1-
## Datadog Java Tracer
1+
# Datadog Opentracing Tracer
22

3-
### Motivations
3+
## Motivations
44

5-
The Datadog Java Tracer is an OpenTracing-compatible tracer. It provides all resources needed to instrument your code.
5+
The Datadog Tracer is an Opentracing compatible tracer. It provides all resources needed to instrument your code
6+
and report each operations, each traces directly to a Datadog APM platform.
67

78

8-
Opentracing introduces the concept of the **span**. A span is **timed operation** representing "a bounded process" in the code.
9-
The spans can **be linked together**. And a **trace** is a list of spans, each related to the same top action/operation.
9+
Opentracing uses the concept of the **span**. A span is **timed operation** representing a bunch of work executed.
10+
Spans can **be linked together**. And a **trace** is a collection of spans, related to the same top action/operation.
1011

1112
Let's see an example.
1213

13-
The workflow can be a client requesting, via a HTTP endpoint, some resources store in a DB.
14-
Look at the following scheme.
14+
For instance, a client requesting a resource through an HTTP endpoint.
15+
Look at the following workflow.
1516

1617
````
1718
TRACE:
@@ -31,25 +32,80 @@ As just described, the tracer produces a trace composed of 4 spans, each represe
3132
2. Span2 is the Span1's first child, representing the amount of time to understand the query, and perform the query
3233
on the DB.
3334
3. Span3, a Span1' grandchild, represents the DB time used to retrieve the data
34-
4. Span4 is a child of Span2 and followed Span3. It represents a business process for instance.
35+
4. Span4 is a child of Span2 and followed Span3. It represents a business/legacy operation.
3536

3637
This is a very simple example of how works [Opentracing](http://opentracing.io/).
37-
Do not hesitate to go deeper and read the full documentation: http://opentracing.io/
38+
To dig deeper, read the full documentation: http://opentracing.io/
3839

3940

40-
### How to instrument well-known framework?
41+
## How to instrument your application?
42+
43+
There are 3 ways to instrument an application:
44+
1. [Use the autotracing agent for supported frawemorks](#framework)
45+
2. [Use the Opentracing API](#api)
46+
3. [Use annotations](#annotation)
47+
48+
### <a name="framework"></a>Use the autotracing agent for well-known framework
49+
50+
Datadog instruments many frameworks and libraries by default: SpringBoot, JDBC, Mongo, JMS, Tomcat, etc.
51+
By using the autotracing agent, you just need to follow few steps in order to get traces.
4152

42-
Datadog instruments many frameworks and libraries by default: SpringBoot, JDBC, Mongo, JMS, Tomcat, etc.
4353
Check the dedicated project and agent: [dd-java-agent](../dd-java-agent)
4454

4555

46-
### How the Datadog Tracer (DDTrace) is loaded in the project?
56+
### <a name="api"></a>Custom instrumentations using Opentracing API
57+
58+
If you want to add custom instrumenting to your code, you have to use the Opentracing API.
59+
The official documentation can be found right here: [](https://github.com/opentracing/opentracing-java).
60+
61+
Let's look at a simple example.
62+
63+
64+
```java
65+
class InstrumentedClass {
66+
67+
68+
void methodSDK() {
69+
// Retrieve the tracer using the resolver provided
70+
// Make sure you have :
71+
// 1. added the agent to the jvm (-javaagent;/path/to/agent.jar)
72+
// 2. a dd-trace.yaml file in your resources directory
73+
Tracer tracer = io.opentracing.util.GlobalTracer.get();
74+
75+
Span span = tracer.buildSpan("operation-name").startActive();
76+
77+
//Do some thing here ...
78+
Thread.sleep(1_000);
79+
80+
// Close the span, the trace will automatically reported to the writer configured
81+
span.finish();
82+
}
83+
84+
}
85+
```
86+
87+
The method above is now instrumented. As you can see, the tracer is retrieved from a global registry, called `GlobalTracer`.
88+
89+
The last thing you have to do is providing a configured tracer. This can be easily done by using the `TracerFactory`.
90+
in the bootstrap method (like the `main`).
4791

48-
This current implementation uses the trace-resolver feature provides by Opentracing.
49-
That means you can add and load the tracer using a Java Agent directly with the JVM.
92+
```java
93+
public class Application {
5094

51-
The DDTrace is autoconfigured using the YAML file provided in the project: `dd-trace.yaml`.
52-
By default, the DDTrace tries to reach a local Datadog Agent, but you can change the settings and use a different
95+
public static void main(String[] args) {
96+
97+
// Init the tracer from the configuration file
98+
Tracer tracer = DDTracerFactory.createFromConfigurationFile();
99+
io.opentracing.util.GlobalTracer.register(tracer);
100+
101+
// ...
102+
}
103+
}
104+
```
105+
106+
The factory looks for a `dd-trace.yaml` file in the classpath. The DDTracer is auto-configured using this YAML file.
107+
108+
By default, the DDTracer tries to reach a local Datadog Agent, but you can change the settings and use a different
53109
location. In order to do that, please, refer you to the latest configuration: [dd-trace.yaml](src/main/resources/dd-trace.yaml)
54110

55111
```yaml
@@ -76,78 +132,73 @@ sampler:
76132
type: AllSampler
77133
```
78134
79-
To attach the agent to the JVM, you simply have to declare the provided `jar` file in your
80-
JVM arguments as a valid `-javaagent:`. We assume that your `${M2_REPO}` env variable is properly set.
81-
Don't forget to replace the `{version}` placeholder in the following commands.
135+
Do not forget to add the corresponding dependencies to your project.
82136
83-
So first download the `jar` file from the main Maven repository:
84137
138+
```xml
139+
<!-- Opentracing API -->
140+
<dependency>
141+
<groupId>io.opentracing</groupId>
142+
<artifactId>opentracing-api</artifactId>
143+
<version>${opentracing.version}</version>
144+
</dependency>
145+
146+
<!-- Datadog Tracer (only useful if you do not use the Datadog autotracing agent) -->
147+
<dependency>
148+
<groupId>com.datadoghq</groupId>
149+
<artifactId>dd-trace</artifactId>
150+
<version>${dd-trace-java.version}</version>
151+
</dependency>
85152
```
86-
> mvn dependency:get -Dartifact=io.opentracing-contrib:opentracing-agent:${version}
87-
```
88-
Then add the following JVM argument when launching your application (in IDE, using Maven run or simply in collaboration with the `>java -jar` command):
89153

90-
```
91-
-javaagent:${M2_REPO}/io/opentracing-contrib/opentracing-agent/${version}/opentracing-agent-${version}.jar
92-
```
93154

155+
### <a name="annotation"></a>Custom instrumentations using Annotation
94156

95-
At this point, the DDTrace is loaded in the project. Let's see now how to instrument it.
157+
Datadog provides a third way to instrument your code: annotations.
158+
The following example is the same as above. Just add `@Trace` to the methods you want to instrument.
96159

97-
### How to use the Datadog Tracer (DDTrace) for instrumenting legacy code?
160+
```java
161+
class InstrumentedClass {
98162

99-
Once, the DDTrace is loaded, you can start to instrument your code using the Opentracing SDK or the `@Trace` annotation.
100-
`@Trace` is actually a Datadog specific, but we plan to submit it to Opentracing foundation.
163+
@Trace(operationName = "operation-name")
164+
void methodSDK() {
101165

102-
To use them, you have to add the dependency to the DDTrace.
103-
Just edit you `pom.xml` and add this:
166+
//Do some thing here ...
167+
Thread.sleep(1_000);
168+
}
169+
}
170+
```
104171

172+
In order to use annotations, the only required dependency is that package.
105173
```xml
106-
<dependency>
107-
<groupId>com.datadoghq</groupId>
108-
<artifactId>dd-trace</artifactId>
109-
<version>${dd-trace-java.version}</version>
110-
</dependency>
174+
<!-- Datadog annotations -->
175+
<dependency>
176+
<groupId>com.datadoghq</groupId>
177+
<artifactId>dd-trace-annotations</artifactId>
178+
<version>${dd-trace-java.version}</version>
179+
</dependency>
111180
```
181+
The annotations are resolved at the runtime by the autotracing agent. If you want to use the annotations,
182+
so have to provide the agent.
112183

184+
To attach the agent to the JVM, you simply have to declare the provided `jar` file in your
185+
JVM arguments as a valid `-javaagent`. Don't forget to replace the `{version}` placeholder in the following commands.
113186

114-
You can start as shown below, here is an example how to use both of them to instrument 2 simple methods.
187+
So first download the `jar` file from the main Maven repository: http://central.maven.org/maven2/com/datadoghq/dd-java-agent/
115188

116-
```java
117-
class InstrumentedClass {
118-
119-
@Trace
120-
void methodAnnoted() {
121-
// The annotation will do the same thing as the manual instrumentation below
122-
//Do some thing here ...
123-
Thread.sleep(1_000);
124-
}
125-
126-
void methodSDK() {
127-
// Retrieve the tracer using the resolver provided
128-
// Make sure you have :
129-
// 1. added the agent to the jvm (-javaagent;/path/to/agent.jar)
130-
// 2. a dd-trace.yaml file in your resources directory
131-
Tracer tracer = io.opentracing.util.GlobalTracer.get();
132-
133-
Span span = tracer.buildSpan("operation-name").build();
134-
135-
//Do some thing here ...
136-
Thread.sleep(1_000);
137-
138-
// Close the span, the trace will automatically reported to the writer configured
139-
span.close();
140-
}
141-
142-
}
143189
```
190+
> curl -OL http://central.maven.org/maven2/com/datadoghq/dd-java-agent/{version}/dd-java-agent-{version}.jar
191+
```
192+
Then add the following JVM argument when launching your application (in IDE, using Maven run or simply in collaboration with the `>java -jar` command):
144193

145-
If you have a running Datadog Agent with the [APM feature enabled](http://docs.datadoghq.com/tracing/), you should
146-
see traces directly to your Datadog account.
194+
```
195+
-javaagent:/path/to/dd-java-agent-{version}.jar
196+
```
147197

198+
At this point, the DDTrace is loaded in the project.
148199

149200

150-
### Other useful resources
201+
## Other useful resources
151202

152203
Before instrumenting your own project you might want to run the provided examples:
153204

0 commit comments

Comments
 (0)