Skip to content

Commit 75c805d

Browse files
realarkrealark
authored
Merge pull request #208 from DataDog/ark/sparse_readme
Remove documentation from readme and point to official docs
2 parents dba38c9 + 64fbaba commit 75c805d

File tree

1 file changed

+2
-248
lines changed

1 file changed

+2
-248
lines changed

‎README.md

Lines changed: 2 additions & 248 deletions
Original file line numberDiff line numberDiff line change
@@ -1,249 +1,3 @@
1-
## What is Datadog APM?
1+
# Datadog Java APM
22

3-
Datadog APM traces the path of each request through your application stack, recording the latency of each step along the way. It sends all tracing data to Datadog, where you can easily identify which services or calls are slowing down your application the most.
4-
5-
This repository contains what you need to trace Java applications. Two quick notes up front:
6-
7-
- **Datadog Java APM is currently in Beta**
8-
- Datadog Java APM can only trace applications running Java 1.7 or later
9-
10-
## The Components
11-
12-
These three things help you instrument Java applications:
13-
14-
**[Datadog Java Agent](https://github.com/DataDog/dd-trace-java/tree/master/dd-java-agent)**: a Java Agent that, when passed to your application:
15-
1. Automatically traces many Java frameworks, application servers, and databases using some of the libraries from [opentracing-contrib](https://github.com/opentracing-contrib), and
16-
2. Lets you add annotations to your methods to easily trace their execution times.
17-
18-
**Note:** dd-java-agent is considered experimental. Some integrations may not activate in all cases. Additional manual instrumentation using the [Opentracing API](https://github.com/opentracing/opentracing-java) is strongly encouraged.
19-
20-
**[Datadog Tracer](https://github.com/DataDog/dd-trace-java/tree/master/dd-trace-ot)**: an OpenTracing-compatible library that lets you trace any piece of your Java code, not just whole methods.
21-
22-
**[Datadog APM Agent](https://github.com/DataDog/datadog-trace-agent)**: a (non-Java) service that runs on your application servers, accepting trace data from the Datadog Java Agent and/or Datadog Tracer and sending it to Datadog. (The APM Agent is not part of this repo; it's the same Agent to which all Datadog tracers—Go, Python, etc—send data)
23-
24-
## Getting Started
25-
26-
Before instrumenting your code, [install the Datadog Agent](https://app.datadoghq.com/account/settings#agent) on your application servers (or locally, if you're just trying out Java APM) and enable the APM Agent. See the special instructions for [macOS](https://github.com/DataDog/datadog-trace-agent#run-on-osx) and [Docker](https://github.com/DataDog/docker-dd-agent#tracing--apm) if you're using either.
27-
28-
### Automatic Tracing
29-
30-
#### Java Agent Setup
31-
32-
Download the latest Datadog Java Agent:
33-
34-
```
35-
wget -O dd-java-agent.jar 'https://search.maven.org/remote_content?g=com.datadoghq&a=dd-java-agent&v=LATEST'
36-
```
37-
38-
Then configure your application using either environment variables or system properties (on the command line via `-D`). See the [config](#configuration) section for details.
39-
40-
**Note:** configuration is also required for [Manual Instrumentation](#manual-instrumentation) with the Datadog Tracer.
41-
42-
Finally, add the following JVM argument when starting your application—in your IDE, your Maven or gradle application script, or your `java -jar` command:
43-
44-
```
45-
-javaagent:/path/to/the/dd-java-agent.jar
46-
```
47-
48-
The Java Agent—once passed to your application—automatically traces requests to the frameworks, application servers, and databases shown below. It does this by using various libraries from [opentracing-contrib](https://github.com/opentracing-contrib). In most cases you don't need to install or configure anything; traces will automatically show up in your Datadog dashboards.
49-
50-
#### Configuration
51-
52-
| Config | System Property | Environment Variable | Default |
53-
| ------------------ | --------------------- | ------------------------- | ------------------ |
54-
| service.name | dd.service.name | DD_SERVICE_NAME | `unnamed-java-app` |
55-
| writer.type | dd.writer.type | DD_WRITER_TYPE | `DDAgentWriter` |
56-
| agent.host | dd.agent.host | DD_AGENT_HOST | `localhost` |
57-
| agent.port | dd.agent.port | DD_AGENT_PORT | `8126` |
58-
| priority.sampling | dd.priority.sampling | DD_PRIORITY_SAMPLING | `false` |
59-
60-
#### Application Servers
61-
62-
| Server | Versions | Comments |
63-
| ------------- |:-------------:| -----|
64-
| Java Servlet Compatible | 2.3+, 3.0+ | HTTP client calls with [cross-process](http://opentracing.io/documentation/pages/api/cross-process-tracing.html) headers are linked |
65-
66-
*Note:* Many application servers are Servlet compatible such as Tomcat, Jetty, Websphere, Weblogic, etc.
67-
Also, frameworks like Spring Boot and Dropwizard inherently work because they use a Servlet compatible embedded application server.
68-
69-
#### Frameworks
70-
71-
| Framework | Versions | Comments |
72-
| ------------- |:-------------:| ----- |
73-
| [OkHTTP](https://github.com/opentracing-contrib/java-okhttp) | 3.x | HTTP client calls with [cross-process](http://opentracing.io/documentation/pages/api/cross-process-tracing.html) headers are linked |
74-
| [Apache HTTP Client](https://github.com/opentracing-contrib/java-apache-httpclient) | 4.3 + | HTTP client calls with [cross-process](http://opentracing.io/documentation/pages/api/cross-process-tracing.html) headers are linked|
75-
| [AWS SDK](https://github.com/opentracing-contrib/java-aws-sdk) | 1.11.0+ | Trace all client calls to any AWS service |
76-
| [Web Servlet Filters](https://github.com/opentracing-contrib/java-web-servlet-filter) | Depends on web server | See [Application Servers](#application-servers) |
77-
| [JMS 2](https://github.com/opentracing-contrib/java-jms) | 2.x | Trace calls to message brokers; distributed trace propagation not yet supported |
78-
79-
#### Databases
80-
81-
| Database | Versions | Comments |
82-
| ------------- |:-------------:| ----- |
83-
| JDBC | 4.x | Intercepts calls to JDBC compatible clients |
84-
| [MongoDB](https://github.com/opentracing-contrib/java-mongo-driver) | 3.x | Intercepts all the calls from the MongoDB client |
85-
| [Cassandra](https://github.com/opentracing-contrib/java-cassandra-driver) | 3.2.x | Intercepts all the calls from the Cassandra client |
86-
87-
### The `@Trace` Annotation
88-
89-
The Java Agent lets you add a `@Trace` annotation to any method to measure its execution time. Setup the [Java Agent](#java-agent-setup) first if you haven't done so.
90-
91-
#### Setup
92-
93-
Add the `dd-trace-api` dependency to your project. For Maven, add this to pom.xml:
94-
95-
```xml
96-
<dependency>
97-
<groupId>com.datadoghq</groupId>
98-
<artifactId>dd-trace-api</artifactId>
99-
<version>{version}</version>
100-
</dependency>
101-
```
102-
103-
For gradle, add:
104-
105-
```gradle
106-
compile group: 'com.datadoghq', name: 'dd-trace-api', version: {version}
107-
```
108-
109-
#### Example
110-
111-
Add an annotation to some method in your code:
112-
113-
```java
114-
@Trace
115-
public void myMethod() throws InterruptedException{
116-
...
117-
}
118-
```
119-
120-
You can pass an `operationName` to name the trace data as you want:
121-
122-
```java
123-
@Trace(operationName="database.before")
124-
public void myMethod() throws InterruptedException{
125-
....
126-
}
127-
```
128-
129-
When you don't pass an `operationName`, the Java Agent sets it to the method name.
130-
131-
### Manual Instrumentation
132-
133-
You can use the Datadog Tracer (`dd-trace-ot`) library to measure execution times for specific pieces of code. This lets you trace your application more precisely than you can with the Java Agent alone.
134-
135-
#### Setup
136-
137-
For Maven, add this to pom.xml:
138-
139-
```xml
140-
<!-- OpenTracing API -->
141-
<dependency>
142-
<groupId>io.opentracing</groupId>
143-
<artifactId>opentracing-api</artifactId>
144-
<version>0.31.0</version>
145-
</dependency>
146-
147-
<!-- OpenTracing Util -->
148-
<dependency>
149-
<groupId>io.opentracing</groupId>
150-
<artifactId>opentracing-util</artifactId>
151-
<version>0.31.0</version>
152-
</dependency>
153-
154-
<!-- Datadog Tracer (only needed if you do not use dd-java-agent) -->
155-
<dependency>
156-
<groupId>com.datadoghq</groupId>
157-
<artifactId>dd-trace-ot</artifactId>
158-
<version>${dd-trace-java.version}</version>
159-
</dependency>
160-
```
161-
162-
For gradle, add:
163-
164-
```
165-
compile group: 'io.opentracing', name: 'opentracing-api', version: "0.31.0"
166-
compile group: 'io.opentracing', name: 'opentracing-util', version: "0.31.0"
167-
compile group: 'com.datadoghq', name: 'dd-trace-ot', version: "${dd-trace-java.version}"
168-
```
169-
170-
Configure your application using environment variables or system properties as discussed in the [config](#configuration) section.
171-
172-
#### Examples
173-
174-
Rather than referencing classes directly from `dd-trace-ot` (other than registering `DDTracer`), we strongly suggest using the [OpenTracing API](https://github.com/opentracing/opentracing-java).
175-
[Additional documentation on the api](docs/opentracing-api.md) is also available.
176-
177-
Let's look at a simple example.
178-
179-
```java
180-
class InstrumentedClass {
181-
182-
void method0() {
183-
// 1. Configure your application using environment variables or system properties
184-
// 2. If using the Java Agent (-javaagent;/path/to/agent.jar), do not instantiate the GlobalTracer; the Agent instantiates it for you
185-
Tracer tracer = io.opentracing.util.GlobalTracer.get();
186-
187-
Span span = tracer.buildSpan("operation-name").startActive(true);
188-
span.setTag(DDTags.SERVICE_NAME, "my-new-service");
189-
190-
// The code you're tracing
191-
Thread.sleep(1000);
192-
193-
// If you don't call finish(), the span data will NOT make it to Datadog!
194-
span.finish();
195-
}
196-
}
197-
```
198-
199-
Alternatively, you can wrap the code you want to trace in a `try-with-resources` statement:
200-
201-
```java
202-
class InstrumentedClass {
203-
204-
void method0() {
205-
Tracer tracer = io.opentracing.util.GlobalTracer.get();
206-
207-
try (ActiveSpan span = tracer.buildSpan("operation-name").startActive(true)) {
208-
span.setTag(DDTags.SERVICE_NAME, "my-new-service");
209-
Thread.sleep(1000);
210-
}
211-
}
212-
}
213-
```
214-
215-
In this case, you don't need to call `span.finish()`.
216-
217-
Finally, you must provide a configured tracer. This can be easily done by using the `TracerFactory` or manually
218-
in the bootstrap method (i.e. `main`).
219-
220-
```java
221-
public class Application {
222-
223-
public static void main(String[] args) {
224-
225-
// Initialize the tracer from the configuration file
226-
Tracer tracer = DDTracerFactory.createFromConfigurationFile();
227-
io.opentracing.util.GlobalTracer.register(tracer);
228-
229-
// OR from the API
230-
Writer writer = new datadog.trace.api.writer.DDAgentWriter();
231-
Sampler sampler = new datadog.trace.api.sampling.AllSampler();
232-
Tracer tracer = new datadog.opentracing.DDTracer(writer, sampler);
233-
io.opentracing.util.GlobalTracer.register(tracer);
234-
235-
// ...
236-
}
237-
}
238-
```
239-
240-
## Further Reading
241-
242-
- Browse the [example applications](examples) in this repository to see Java tracing in action
243-
- Read [OpenTracing's documentation](https://github.com/opentracing/opentracing-java); feel free to use the Trace Java API to customize your instrumentation.
244-
- Brush up on [Datadog APM Terminology](https://docs.datadoghq.com/tracing/terminology/)
245-
- Read the [Datadog APM FAQ](https://docs.datadoghq.com/tracing/faq/)
246-
247-
## Get in touch
248-
249-
If you have questions or feedback, email us at [email protected] or chat with us in the datadoghq slack channel #apm-java.
3+
To use and configure Datadog Java APM, see [https://docs.datadoghq.com/tracing/languages/java](https://docs.datadoghq.com/tracing/languages/java)

0 commit comments

Comments
 (0)