Documentation #29
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,17 +1,18 @@ | ||
| # Datadog Opentracing Tracer | ||
|
|
||
| ## Motivations | ||
|
|
||
| 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. | ||
| 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. | ||
|
|
||
| For instance, a client requesting a resource through an HTTP endpoint. | ||
| Look at the following workflow. | ||
|
|
||
| ```` | ||
| TRACE: | ||
|
|
@@ -31,27 +32,31 @@ As just described, the tracer produces a trace composed of 4 spans, each represe | |
| 2. Span2 is the Span1's first child, representing the amount of time to understand the query, and perform the query | ||
| 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/). | ||
| To dig deeper, read the full documentation: http://opentracing.io/ | ||
|
|
||
|
|
||
| ## How to instrument your application? | ||
|
There was a problem hiding this comment. Before this advanced section, we should provide a "Quick start guide" where we put the strict minimum to have it running (just the java agent) + say to have the Agent running. With the config defaults, that should just work. Similar examples for other languages: https://app.datadoghq.com/apm/install |
||
|
|
||
| In order to start to instrument your application, you need to: | ||
|
|
||
| 1. [Configure the Datadog Tracer](#config) | ||
|
There was a problem hiding this comment. That should be 2. instead of 1.: first you instrument your app, then you may need to tweak the config (but most of the time you won't right away). |
||
| 2. Choose one of the 3 ways to instrument an application: | ||
|
There was a problem hiding this comment. Imho, we should not oppose these 3 ways (not "choose one"), but instead offer them all together. ie. we should word it as successive steps:
|
||
| 1. [Use the autotracing agent for supported frawemorks](#framework) | ||
| 2. [Use the Opentracing API](#api) | ||
| 3. [Use annotations](#annotation) | ||
|
|
||
| ### <a name="config"></a> Datadog Tracer configuration | ||
|
|
||
| The DDTracer is auto-configured using this YAML file. | ||
|
|
||
| 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) | ||
|
|
||
| *Make sure that file is present in your classpath*. | ||
|
|
||
| ```yaml | ||
| # Service name used if none is provided in the app | ||
| defaultServiceName: unnamed-java-app | ||
|
|
@@ -76,78 +81,162 @@ sampler: | |
| type: AllSampler | ||
| ``` | ||
|
|
||
|
|
||
| ### <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. | ||
|
|
||
|
|
||
| Get the latest version of the Datadog Java agent (Do not forget to replace the version `${version}` by the appropriate one). | ||
|
|
||
| ```bash | ||
| version=0.1.1 | ||
| curl -OL http://central.maven.org/maven2/com/datadoghq/dd-java-agent/${version}/dd-java-agent-${version}.jar | ||
| ``` | ||
| Then, attach the Java agent to your JVM using th `javaagent` option. | ||
|
|
||
| ```bash | ||
| java -javaagent:/path/to/dd-java-agent-${version}.jar ... | ||
| ``` | ||
|
|
||
| If you have a local Datadog agent running on your host, traces are visible in your Datadog account. | ||
|
|
||
|
|
||
| You can choose which framework you want to instrument, or sending traces to a remote Datadog agent by configuring the Datadog Java Agent YAML file. | ||
| Check the dedicated project for the full documentation: [dd-java-agent](../dd-java-agent) | ||
|
|
||
|
|
||
| ### <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. | ||
| The official documentation can be found right here: [](https://github.com/opentracing/opentracing-java). | ||
|
|
||
| Let's look at a simple example. | ||
|
|
||
|
|
||
| ```java | ||
| class InstrumentedClass { | ||
|
|
||
|
|
||
| void method0() { | ||
| // Retrieve the tracer using the resolver provided | ||
| // Make sure you have : | ||
| // 1. added the agent to the jvm (-javaagent;/path/to/agent.jar) | ||
| // 2. a dd-trace.yaml file in your resources directory | ||
| Tracer tracer = io.opentracing.util.GlobalTracer.get(); | ||
|
|
||
| Span span = tracer.buildSpan("operation-name").startActive(); | ||
| new io.opentracing.tag.StringTag("service-name").set(span, "new-service-name"); | ||
|
|
||
|
|
||
| //Do some thing here ... | ||
| Thread.sleep(1_000); | ||
|
|
||
| // Close the span, the trace will automatically reported to the writer configured | ||
| span.finish(); | ||
| } | ||
|
|
||
| } | ||
|
There was a problem hiding this comment. We could probably add a set of more / advanced examples in a docs directory, then link to it from there. (there, we would be able to use the entire OpenTracing API with some real examples, to which people can refer). |
||
| ``` | ||
|
|
||
| The method above is now instrumented. As you can see, the tracer is retrieved from a global registry, called `GlobalTracer`. | ||
|
There was a problem hiding this comment. This is more advanced, more especially if people run the Trace Agent it is not needed and might confuse them. |
||
|
|
||
| The last thing you have to do is providing a configured tracer. This can be easily done by using the `TracerFactory` or manually | ||
| in the bootstrap method (like the `main`). | ||
|
|
||
| ```java | ||
| public class Application { | ||
|
|
||
| public static void main(String[] args) { | ||
|
|
||
| // Init the tracer from the configuration file | ||
| Tracer tracer = DDTracerFactory.createFromConfigurationFile(); | ||
| io.opentracing.util.GlobalTracer.register(tracer); | ||
|
|
||
| // Init the tracer from the API | ||
| Writer writer = new com.datadoghq.trace.writer.DDAgentWriter(); | ||
| Sampler sampler = new com.datadoghq.trace.sampling.AllSampler(); | ||
| Tracer tracer = new com.datadoghq.trace.DDTracer(writer, sampler); | ||
| io.opentracing.util.GlobalTracer.register(tracer); | ||
|
|
||
| // ... | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| The factory looks for a `dd-trace.yaml` file in the classpath. | ||
|
|
||
| Finally, do not forget to add the corresponding dependencies to your project. | ||
|
|
||
|
|
||
|
|
||
| ``` | ||
| <!-- 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) --> | ||
| <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}' | ||
|
|
||
| ``` | ||
|
|
||
|
|
||
| ### <a name="annotation"></a>Custom instrumentations using Annotation | ||
|
|
||
| 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. | ||
|
|
||
| ```java | ||
| class InstrumentedClass { | ||
|
|
||
| @Trace(operationName = "operation-name-1") | ||
| void method1() { | ||
|
|
||
| //Do some thing here ... | ||
| Thread.sleep(1_000); | ||
| } | ||
|
|
||
| @Trace(operationName = "operation-name-2") | ||
| void method2() { | ||
|
|
||
| // You can get the current span and add tag as follow | ||
| Span current = io.opentracing.util.GlobalTracer.get().activeSpan(); | ||
| new io.opentracing.tag.StringTag("service-name").set(current, "new-service-name"); | ||
|
|
||
| //Do some thing here ... | ||
| Thread.sleep(1_000); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| In order to use annotations, the only required dependency is that package. | ||
| ``` | ||
| <!-- 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. | ||
|
|
||
| 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: | ||
|
|
||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"example of how Opentracing works"