open-telemetry
/
opentelemetry-java-instrumentation
mirror of https://github.com/open-telemetry/opentelemetry-java-instrumentation.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Another pass on improving the docs

This commit is contained in:
Tyler Benson 2017-07-12 14:28:06 -07:00
parent 6b4c29b6fe
commit 232801ab62
8 changed files with 164 additions and 158 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
README.md
View File

@ -13,12 +13,13 @@ gather all traces in your [Datadog](https://app.datadoghq.com) account.
### Start in minutes
* [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.
* [Install the Datadog Java agent](dd-java-agent). Instructions for supported technologies, web-servers and frameworks.
* [Browse examples](dd-trace-examples). See how to instrument legacy projects based on the most used tehcnologies.
* [Instrument with OpenTracing](https://github.com/opentracing/opentracing-java). Datadog embraces the OpenTracing initiative. So feel free to use the Trace Java API to customize your instrumentation.
* [DD Trace](dd-trace). This Java implementation of the opentracing api is used to report traces to Datadog.
* [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.
* [Install the Datadog Java agent](dd-java-agent) - Instructions for supported technologies, web-servers and frameworks.
* [Browse examples](dd-trace-examples) - See how to instrument legacy projects based on the most used tehcnologies.
* [Instrument with OpenTracing](https://github.com/opentracing/opentracing-java) - Datadog embraces the OpenTracing initiative. So feel free to use the Trace Java API to customize your instrumentation.
* [DD Trace](dd-trace) - Datadog's implementation of the OpenTracing API for reporting traces to the [Datadog agent](https://github.com/DataDog/datadog-trace-agent). Can be used independently from dd-java-agent.
### Help or questions?
And for any questions or feedback, feel free to send us an email: support@datadoghq.com
For any questions or feedback, feel free to send us an email: support@datadoghq.com
You can also ask for help in the datadoghq slack channel: #apm-java

156
dd-java-agent-ittests/src/test/java/com/datadoghq/trace/agent/integration/ElasticsearchIntegrationTest.java
View File

@ -1,5 +1,5 @@
//package com.datadoghq.trace.instrument;
//
package com.datadoghq.trace.agent.integration;
//import com.datadoghq.trace.DDTracer;
//import com.datadoghq.trace.writer.ListWriter;
//import org.elasticsearch.action.index.IndexResponse;
@ -25,79 +25,79 @@
//import static org.elasticsearch.common.xcontent.XContentFactory.jsonBuilder;
//
//
//public class ElasticsearchIntegrationTest {
//
//
// private static ListWriter writer = new ListWriter();
// private static DDTracer tracer = new DDTracer(writer);
// private static final int HTTP_PORT = 9205;
// private static final String HTTP_TRANSPORT_PORT = "9300";
// private static final String ES_WORKING_DIR = "target/es";
// private static String clusterName = "elasticsearch";
// private static Node node;
//
//
// @AfterClass
// public static void stopElasticsearch() throws Exception {
// node.close();
// }
//
// @BeforeClass
// public static void warmup() throws NodeValidationException {
//
//
// //GlobalTracer.register(tracer);
//
//
// Settings settings = Settings.builder()
// .put("path.home", ES_WORKING_DIR)
// .put("path.data", ES_WORKING_DIR + "/data")
// .put("path.logs", ES_WORKING_DIR + "/logs")
// .put("transport.type", "netty4")
// .put("http.type", "netty4")
// .put("cluster.name", clusterName)
// .put("http.port", HTTP_PORT)
// .put("transport.tcp.port", HTTP_TRANSPORT_PORT)
// .put("network.host", "0.0.0.0")
// .build();
// Collection plugins = Collections.singletonList(Netty4Plugin.class);
// node = new PluginConfigurableNode(settings, plugins);
// node.start();
// }
//
//
// @Test
// public void testTransportClient() throws IOException {
//
//
// Settings settings = Settings.builder()
// .put("cluster.name", clusterName).build();
//
// TransportClient client = new PreBuiltTransportClient(settings)
// .addTransportAddress(new InetSocketTransportAddress(Inet4Address.getByName("localhost"), Integer.parseInt(HTTP_TRANSPORT_PORT)));
//
// IndexResponse response = client.prepareIndex("twitter", "tweet", "1")
// .setSource(jsonBuilder()
// .startObject()
// .field("user", "kimchy")
// .field("postDate", new Date())
// .field("message", "trying out Elasticsearch")
// .endObject()
// )
// .get();
//
// //fixme works in debug, not in prod
//// assertThat(writer.getList().size()).isEqualTo(1);
//
//
// }
//
//
// private static class PluginConfigurableNode extends Node {
//
// public PluginConfigurableNode(Settings settings,
// Collection<Class<? extends Plugin>> classpathPlugins) {
// super(InternalSettingsPreparer.prepareEnvironment(settings, null), classpathPlugins);
// }
// }
//}
public class ElasticsearchIntegrationTest {
//
//
// private static ListWriter writer = new ListWriter();
// private static DDTracer tracer = new DDTracer(writer);
// private static final int HTTP_PORT = 9205;
// private static final String HTTP_TRANSPORT_PORT = "9300";
// private static final String ES_WORKING_DIR = "target/es";
// private static String clusterName = "elasticsearch";
// private static Node node;
//
//
// @AfterClass
// public static void stopElasticsearch() throws Exception {
// node.close();
// }
//
// @BeforeClass
// public static void warmup() throws NodeValidationException {
//
//
// //GlobalTracer.register(tracer);
//
//
// Settings settings = Settings.builder()
// .put("path.home", ES_WORKING_DIR)
// .put("path.data", ES_WORKING_DIR + "/data")
// .put("path.logs", ES_WORKING_DIR + "/logs")
// .put("transport.type", "netty4")
// .put("http.type", "netty4")
// .put("cluster.name", clusterName)
// .put("http.port", HTTP_PORT)
// .put("transport.tcp.port", HTTP_TRANSPORT_PORT)
// .put("network.host", "0.0.0.0")
// .build();
// Collection plugins = Collections.singletonList(Netty4Plugin.class);
// node = new PluginConfigurableNode(settings, plugins);
// node.start();
// }
//
//
// @Test
// public void testTransportClient() throws IOException {
//
//
// Settings settings = Settings.builder()
// .put("cluster.name", clusterName).build();
//
// TransportClient client = new PreBuiltTransportClient(settings)
// .addTransportAddress(new InetSocketTransportAddress(Inet4Address.getByName("localhost"), Integer.parseInt(HTTP_TRANSPORT_PORT)));
//
// IndexResponse response = client.prepareIndex("twitter", "tweet", "1")
// .setSource(jsonBuilder()
// .startObject()
// .field("user", "kimchy")
// .field("postDate", new Date())
// .field("message", "trying out Elasticsearch")
// .endObject()
// )
// .get();
//
// //fixme works in debug, not in prod
//// assertThat(writer.getList().size()).isEqualTo(1);
//
//
// }
//
//
// private static class PluginConfigurableNode extends Node {
//
// public PluginConfigurableNode(Settings settings,
// Collection<Class<? extends Plugin>> classpathPlugins) {
// super(InternalSettingsPreparer.prepareEnvironment(settings, null), classpathPlugins);
// }
// }
}

50
dd-java-agent/README.md
View File

@ -9,7 +9,7 @@ Tracing instrumentation can be done in 2 ways:
- Automatically over a set of [supported Web servers, frameworks or database drivers](#instrumented-frameworks)
- By using the [`@Trace` annotation](#custom-instrumentations)
:heavy_exclamation_mark: **Warning:** This library is currently in Alpha. This means that even though we rigorously tested instrumentations you may experience strange behaviors depending on your running environment. Be sure to test thoroughly on a staging environment before releasing to production. For any help please contact [tracehelp@datadoghq.com](mailto:tracehelp@datadoghq.com).
:heavy_exclamation_mark: **Warning:** This library is currently in Alpha. This means that even though we rigorously tested instrumentations you may experience strange behaviors depending on your running environment. Be sure to test thoroughly on a staging environment before releasing to production. For any help please contact [tracehelp@datadoghq.com](mailto:tracehelp@datadoghq.com) or reach out in the datadoghq slack channel: #apm-java.
## Quick start
@ -17,7 +17,7 @@ Tracing instrumentation can be done in 2 ways:
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:
- Run the latest [Datadog Agent](https://app.datadoghq.com/account/settings#agent) (version 5.11.0 or above)
- Run the latest [Datadog Agent](https://app.datadoghq.com/account/settings#agent) (version 5.11.0 or above, or [special instructions for Mac OS X](https://github.com/DataDog/datadog-trace-agent#run-on-osx))
- [Enable APM in the Datadog Agent configuration file](https://app.datadoghq.com/apm/docs/tutorials/configuration) `/etc/dd-agent/datadog.conf`.
```
@ -29,7 +29,7 @@ apm_enabled: true
### 2. Instrument your application
To instrument your project or your servers you simply have to declare the provided `jar` file in your JVM arguments as a valid `-javaagent:`.
To dynamically apply instrumentation you simply have to declare the provided `jar` file in your JVM arguments as a valid `-javaagent:`.
- So first download the `jar` file from the main repository.
@ -38,13 +38,14 @@ To instrument your project or your servers you simply have to declare the provid
curl -OL http://central.maven.org/maven2/com/datadoghq/dd-java-agent/{version}/dd-java-agent-{version}.jar
```
- Then add the following JVM argument when launching your application (in IDE, using Maven run or simply in collaboration with the `>java -jar` command):
- Then add the following JVM argument when launching your application (in your IDE, your maven or gradle application script, or your `java -jar` command):
```
-javaagent:/path/to/the/dd-java-agent-{version}.jar
```
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).
For troubleshooting, look for the `trace-agent.log` along side the other [agent logs](https://help.datadoghq.com/hc/en-us/articles/203037159-Log-Locations).
## Configuration
@ -80,21 +81,22 @@ sampler:
# enableCustomAnnotationTracingOver: ["io","org","com"]
# Disable some instrumentations
# disabledInstrumentations: ["apache http", "mongo", "jetty", "tomcat", ...]
# disabledInstrumentations: ["opentracing-apache-httpclient", "opentracing-mongo-driver", "opentracing-web-servlet-filter"]
```
## Instrumented frameworks
When attached to an application the `dd-java-agent` automatically instruments the following set of frameworks & servers:
When attached to an application the `dd-java-agent` dynamically applies the following opentracing-contrib instrumentation for the following set of frameworks & servers, though additional configuration may be required ([JDBC](#jdbc-instrumentation)):
### Frameworks
| FWK | Versions | Comments |
| Framework | Versions | Comments |
| ------------- |:-------------:| ----- |
| OkHTTP | 3.x | HTTP client calls with [cross-process](http://opentracing.io/documentation/pages/api/cross-process-tracing.html) headers |
| Apache HTTP Client | 4.3 + |HTTP client calls with [cross-process](http://opentracing.io/documentation/pages/api/cross-process-tracing.html) headers|
| AWS SDK | 1.11.119+ | Trace all client calls to any AWS service |
| Web Servlet Filters| Depending on server | See [Servers](#servers) section |
| [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 |
| [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|
| [AWS SDK](https://github.com/opentracing-contrib/java-aws-sdk) | 1.11.119+ | Trace all client calls to any AWS service |
| [Web Servlet Filters](https://github.com/opentracing-contrib/java-web-servlet-filter) | Depending on server | See [Servers](#servers) section |
| [JMS 2](https://github.com/opentracing-contrib/java-jms) | 2.x | Trace calls to message brokers, but distributed trace propagation not yet implemented |
### Servers
@ -110,9 +112,9 @@ Modern web application frameworks such as Dropwizard or Spring Boot are automati
| ------------- |:-------------:| ----- |
| Spring JDBC| 4.x | Please check the following [JDBC instrumentation](#jdbc-instrumentation) section |
| Hibernate| 5.x | Please check the following [JDBC instrumentation](#jdbc-instrumentation) section |
| MongoDB | 3.x | Intercepts all the calls from the MongoDB client |
| Cassandra | 3.2.x | Intercepts all the calls from the Cassandra client |
| Elasticsearch | 5.4.x | Intercepts all the calls from the ES Transport client |
| [MongoDB](https://github.com/opentracing-contrib/java-mongo-driver) | 3.x | Intercepts all the calls from the MongoDB client |
| [Cassandra](https://github.com/opentracing-contrib/java-cassandra-driver) | 3.2.x | Intercepts all the calls from the Cassandra client |
| [Elasticsearch](https://github.com/opentracing-contrib/java-elasticsearch-client) | 5.4.x | Intercepts all the calls from the ES Transport client |
#### JDBC instrumentation
@ -120,7 +122,7 @@ By enabling the JDBC instrumentation you'll intercept all the client calls to t
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).
We also provide an [example project with Spring Boot & MySQL](web application frameworks).
We also provide an [example project](../dd-trace-examples/spring-boot-jdbc) with Spring Boot & H2.
### Disabling instrumentations
@ -130,14 +132,14 @@ If for some reason you need to disable an instrumentation you should uncomment t
...
# Disable a few instrumentations
disabledInstrumentations: ["apache http", "mongo", "tomcat"]
disabledInstrumentations: ["opentracing-apache-httpclient", "opentracing-mongo-driver", "opentracing-web-servlet-filter"]
...
```
The list of values that can be disabled are the top level keys found [here](src/main/resources/dd-trace-supported-framework.yaml)
###
## Custom instrumentations
## Custom instrumentation
### The `@Trace` annotation
@ -172,21 +174,25 @@ public void myMethod() throws InterruptedException{
<version>{version}</version>
</dependency>
```
or
```gradle
compile group: 'com.datadoghq', name: 'dd-trace-annotations', version: {version}
```
- Enable custom tracing by adding in the `dd-trace.yaml` config file the packages you would like to scan as follow `enableCustomAnnotationTracingOver: ["io","org","com"]`.
- Enable custom tracing in the `dd-trace.yaml` config file by setting the packages you would like to scan as follows `enableCustomAnnotationTracingOver: ["io","org","com"]`.
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/).
## Other useful resources
Before instrumenting your own project you might want to run the provided examples:
Before instrumenting your own project you might want to review the provided examples:
- [Dropwizard/MongoDB & Cross process client calls](https://github.com/DataDog/dd-trace-java/blob/dev/dd-trace-examples/dropwizard-mongo-client/)
- [Springboot & MySQL over JDBC](https://github.com/DataDog/dd-trace-java/tree/dev/dd-trace-examples/spring-boot-jdbc)
- [Springboot & H2 over JDBC](https://github.com/DataDog/dd-trace-java/tree/dev/dd-trace-examples/spring-boot-jdbc)
Other links that you might want to read:
- Install on [Docker](https://app.datadoghq.com/apm/docs/tutorials/docker)
- Improve your APM experience for apps running on docker by enabling the [Docker Agent](https://app.datadoghq.com/apm/docs/tutorials/docker)
- Datadog's APM [Terminology](https://app.datadoghq.com/apm/docs/tutorials/terminology)
- [FAQ](https://app.datadoghq.com/apm/docs/tutorials/faq)

2
dd-java-agent/src/main/java/com/datadoghq/trace/agent/integration/DDAgentTracingHelper.java
View File

@ -8,7 +8,7 @@ import java.util.logging.Logger;
import org.jboss.byteman.rule.Rule;
/**
* This class provides helpfull stuff in order to easy patch object using Byteman rules
* This class provides helpful stuff in order to easy patch object using Byteman rules
*
* @param <T> The type of the object to patch
*/

2
dd-trace-examples/README.md
View File

@ -1,7 +1,7 @@
## Datadog Java Tracer examples
The goal of this repository is to offer you some examples about how to instrument your code
using the Opentracing API and the DD Tracer.
using the OpenTracing API and the DD Tracer.
![](https://datadog-live.imgix.net/img/datadog_logo_share_tt.png)

10
dd-trace-examples/async-tracing/README.md
View File

@ -1,7 +1,7 @@
## Opentracing Javaagent
## OpenTracing Javaagent
### Purpose
The Opentracing Java Agent contribution is designed to inject code directly to the JVM.
The OpenTracing Java Agent contribution is designed to inject code directly to the JVM.
It provides to developers a way to instrument their code, without modifying it.
The Java Agent is a compiled Jar and it is added to the JVM using the `-javaagent` option.
@ -10,7 +10,7 @@ a set of rules for instrumenting the code through a collection of `otarules.btm`
The contrib is basically able to serve 2 goals:
- Instrumenting custom or legacy code without modifying it (extremely verbose and painful)
- Inject the others Opentracing contribution in your app (Spring Boot, JDBC wrapper, Jax-Rs, etc. )
- Inject the others OpenTracing contribution in your app (Spring Boot, JDBC wrapper, Jax-Rs, etc. )
and configure them on-fly.
### Run the demo
@ -39,7 +39,7 @@ First add the contrib to the dependencies.
You can find them here: https://github.com/opentracing-contrib
```xml
<!-- Opentracing dependencies -->
<!-- OpenTracing dependencies -->
<dependency>
<groupId>io.opentracing.contrib</groupId>
<artifactId>opentracing-agent-rules-java-net</artifactId>
@ -97,5 +97,3 @@ You have to add all rules necessary to instrument your code as you want.
This is why (almost) nobody uses the agent in that way.
Similarly to the previous example, the tracer is initialised through the yaml config file.

73
dd-trace/README.md
View File

@ -1,12 +1,12 @@
# Datadog Opentracing Tracer
# Datadog OpenTracing Tracer
## Motivations
The Datadog Tracer is an [Opentracing](http://opentracing.io/) compatible tracer. It provides all resources needed to instrument your code
The Datadog Tracer is an [OpenTracing](http://opentracing.io/) compatible tracer. It provides all resources needed to instrument your code
and report each operation and each trace directly to a Datadog APM platform.
Opentracing uses the concept of the **span**. A span is **timed operation** representing a bunch of work executed.
OpenTracing uses the concept of the **span**. A span is **timed operation** representing a bunch of work executed.
Spans can **be linked together**. And a **trace** is a collection of spans, related to the same top action/operation.
Let's see an example.
@ -25,7 +25,7 @@ TRACE:
|----------------------------------------SPAN 4 (Child of 2)..(end) - 50 ms
````
Opentracing provides a way for measuring the time consumed for each operation.
OpenTracing provides a way for measuring the time consumed for each operation.
As just described, the tracer produces a trace composed of 4 spans, each representing a specific action:
1. Span1 is the time from doing the request to getting the response.
@ -34,7 +34,7 @@ on the DB.
3. Span3, a Span1' grandchild, represents the DB time used to retrieve the data
4. Span4 is a child of Span2 and followed Span3. It represents a business/legacy operation.
This is a very simple example of how works [Opentracing](http://opentracing.io/).
This is a very simple example of how works [OpenTracing](http://opentracing.io/).
To dig deeper, read the full documentation: http://opentracing.io/
@ -44,13 +44,13 @@ In order to start to instrument your application, you need to:
1. [Configure the Datadog Tracer](#config)
2. Choose one of the 3 ways to instrument an application:
1. [Use the autotracing agent for supported frawemorks](#framework)
2. [Use the Opentracing API](#api)
1. [Use dd-java-agent for supported frawemorks](#framework)
2. [Use the OpenTracing API in your code](#api)
3. [Use annotations](#annotation)
### <a name="config"></a> Datadog Tracer configuration
The DDTracer is auto-configured using this YAML file.
The DDTracer is configured using a YAML file named `dd-trace.yaml` following the structure below.
By default, the DDTracer tries to reach a local Datadog Agent, but you can change the settings and use a different
location. In order to do that, please, refer you to the latest configuration: [dd-trace.yaml](src/main/resources/dd-trace.yaml)
@ -85,7 +85,7 @@ sampler:
### <a name="framework"></a>Use the Datadog Java agent for well-known framework
Datadog uses instrumentation contributed by [the community](https://github.com/opentracing-contrib) to instrument many frameworks:
SpringBoot, JDBC, Mongo, JMS, Tomcat, etc. By using the Datadog Java agent, you just need to follow few steps in order to get traces.
SpringBoot, JDBC, Mongo, JMS, Tomcat, etc. By using [dd-java-agent](../dd-java-agent), you just need to follow few steps in order to get traces.
Get the latest version of the Datadog Java agent (Do not forget to replace the version `${version}` by the appropriate one).
@ -107,9 +107,9 @@ You can choose which framework you want to instrument, or sending traces to a re
Check the dedicated project for the full documentation: [dd-java-agent](../dd-java-agent)
### <a name="api"></a>Custom instrumentations using Opentracing API
### <a name="api"></a>Custom instrumentations using OpenTracing API
If you want to add custom instrumenting to your code, you have to use the Opentracing API.
If you want to add custom instrumenting to your code, you have to use the OpenTracing API.
The official documentation can be found right here: [](https://github.com/opentracing/opentracing-java).
Let's look at a simple example.
@ -117,7 +117,6 @@ Let's look at a simple example.
```java
class InstrumentedClass {
void method0() {
// Retrieve the tracer using the resolver provided
@ -154,6 +153,7 @@ public class Application {
Tracer tracer = DDTracerFactory.createFromConfigurationFile();
io.opentracing.util.GlobalTracer.register(tracer);
// OR
// Init the tracer from the API
Writer writer = new com.datadoghq.trace.writer.DDAgentWriter();
Sampler sampler = new com.datadoghq.trace.sampling.AllSampler();
@ -165,36 +165,38 @@ public class Application {
}
```
The factory looks for a `dd-trace.yaml` file in the classpath.
`DDTracerFactory` looks for a `dd-trace.yaml` file in the classpath.
Finally, do not forget to add the corresponding dependencies to your project.
```
<!-- Opentracing API -->
Maven:
```xml
<!-- OpenTracing API -->
<dependency>
<groupId>io.opentracing</groupId>
<artifactId>opentracing-api</artifactId>
<version>${opentracing.version}</version>
</dependency>
<!-- Datadog Tracer (only needed if you do not use the Datadog autotracing agent) -->
<!-- Datadog Tracer (only needed if you do not use dd-java-agent) -->
<dependency>
<groupId>com.datadoghq</groupId>
<artifactId>dd-trace</artifactId>
<version>${dd-trace-java.version}</version>
</dependency>
compile group: 'io.opentracing', name: 'opentracing-api', version: '${opentracing.version}'
compile group: 'com.datadoghq', name: 'dd-trace', version: '${dd-trace-java.version}'
```
Gradle:
```groovy
compile group: 'io.opentracing', name: 'opentracing-api', version: "${opentracing.version}"
compile group: 'com.datadoghq', name: 'dd-trace', version: "${dd-trace-java.version}"
```
### <a name="annotation"></a>Custom instrumentations using Annotation
### <a name="annotation"></a>Adding Trace annotations to your methods
Datadog provides a third way to instrument your code: annotations.
The following example is the same as above. Just add `@Trace` to the methods you want to instrument.
An easy way to improve visibility to your application is by adding the `@Trace` annotation on the methods you want to instrument.
This is equivelent to the `method0` example from the [api](#api) section.
```java
class InstrumentedClass {
@ -219,35 +221,34 @@ class InstrumentedClass {
}
```
In order to use annotations, the only required dependency is that package.
```
In order to use annotations, the only required dependency is `dd-trace-annotations`.
Maven:
```xml
<!-- Datadog annotations -->
<dependency>
<groupId>com.datadoghq</groupId>
<artifactId>dd-trace-annotations</artifactId>
<version>${dd-trace-java.version}</version>
</dependency>
compile group: 'com.datadoghq', name: 'dd-trace-annotations', version: '${dd-trace-java.version}'
```
The annotations are resolved at the runtime by the Datadog Java agent. If you want to use the annotations,
so you must run the Datadog Java Agent.
Gradle:
```groovy
compile group: 'com.datadoghq', name: 'dd-trace-annotations', version: "${dd-trace-java.version}"
```
**The annotations are resolved at the runtime by the Datadog Java agent. If you want to use the annotations,
so you must run the Datadog Java Agent.**
To run the agent, please refer to the Datadog Java agent documentation: [dd-java-agent](../dd-java-agent)
## Other useful resources
Before instrumenting your own project you might want to run the provided examples:
Before instrumenting your own project you might want to review the provided examples:
- [Dropwizard/MongoDB & Cross process client calls](https://github.com/DataDog/dd-trace-java/blob/dev/dd-trace-examples/dropwizard-mongo-client/)
- [Springboot & MySQL over JDBC](https://github.com/DataDog/dd-trace-java/tree/dev/dd-trace-examples/spring-boot-jdbc)
- [Springboot & H2 over JDBC](https://github.com/DataDog/dd-trace-java/tree/dev/dd-trace-examples/spring-boot-jdbc)
Other links that you might want to read:
- Install on [Docker](https://app.datadoghq.com/apm/docs/tutorials/docker)
- Improve your APM experience for apps running on docker by enabling the [Docker Agent](https://app.datadoghq.com/apm/docs/tutorials/docker)
- Datadog's APM [Terminology](https://app.datadoghq.com/apm/docs/tutorials/terminology)
- [FAQ](https://app.datadoghq.com/apm/docs/tutorials/faq)
And for any questions, feedback, feel free to send us an email: support@datadoghq.com

16
dd-trace/docs/opentracing-api.md
View File

@ -1,10 +1,10 @@
# Opentracing API
# OpenTracing API
The Opentraction group offers an API to instrument your code.
This document is a kind of a "Quick start for the" official specifications: https://github.com/opentracing/specification
There are several concepts expose by the Opentracing API:
There are several concepts expose by the OpenTracing API:
* The core API used for instrumenting the code
* The tracer implementations, in charge of generating physically the traces. For instance the Datadog Java Tracer generates
@ -12,7 +12,7 @@ traces that can be consumed by the Datadog agent.
* The Asynchronous API to help developers managing their spans and traces in a concurrency context.
## Opentracing Core API
## OpenTracing Core API
Official documentation link: [Opentracting Tracer specification](https://github.com/opentracing/specification/blob/master/specification.md#tracer)
@ -34,7 +34,7 @@ to send the traces to a logger or directly to a running Datadog agent.
Tracer tracer = new DDTracer();
```
Once a tracer is instantiated, you can use it to create and manage span. Opentracing defines a SpanBuilder accessible through
Once a tracer is instantiated, you can use it to create and manage span. OpenTracing defines a SpanBuilder accessible through
the method `buildSpan(String operationName)` to serve this purpose.
@ -77,7 +77,7 @@ You can manipulate them at any time and add extra information using the tags.
Tags are local to the span. So, no tags will be inherit from the parent. In order to propagate meta accross all spans of a
trace, use the `baggageItems` (see right after).
Opentracing Tags are standardized meta and allow developers to add more value to the span.
OpenTracing Tags are standardized meta and allow developers to add more value to the span.
```java
// Create a span, but do not promoting it as the active span
@ -93,7 +93,7 @@ Opentracing Tags are standardized meta and allow developers to add more value to
Tags.HTTP_STATUS.setTag(valuableSpan, 200);
```
All standardized tags can be consulted there: [Opentracing Semantic specification](https://github.com/opentracing/specification/blob/master/semantic_conventions.md)
All standardized tags can be consulted there: [OpenTracing Semantic specification](https://github.com/opentracing/specification/blob/master/semantic_conventions.md)
So, tags are local to the span. If you want set for meta for a trace, you have to use `baggabeItems` instead.
Baggage are very similar to the tags, but they have a powerful capabilities:
@ -106,5 +106,5 @@ Baggage are very similar to the tags, but they have a powerful capabilities:
```
## Opentracing Asynchronous API
see WIP: https://github.com/opentracing/specification/issues/23
## OpenTracing Asynchronous API
see WIP: https://github.com/opentracing/specification/issues/23