Documentation #29

gpolaert · 2017-07-03T13:00:43Z

No description provided.

LotharSee · 2017-07-03T14:22:56Z

dd-trace/README.md

+
+The method above is now instrumented. As you can see, the tracer is retrieved from a global registry, called `GlobalTracer`.
+
+The last thing you have to do is providing a configured tracer. This can be easily done by using the `TracerFactory`.


Are we still automatically configuring the tracer when running the Agent?
If yes, we should certainly state it (and even explain it as the default/simple what it should be done/move this manual configuration of the Tracer is an advanced section).

LotharSee · 2017-07-03T14:23:50Z

dd-trace/README.md

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


As part of the example, let's should how, from inside methodSDK, you can access the span generated from the annotation, set its resource, set tags, etc...

LotharSee · 2017-07-03T14:24:46Z

dd-trace/README.md

 ```
+The annotations are resolved at the runtime by the autotracing agent. If you want to use the annotations,


s/so have to provide the agent/you must run the Java Agent

LotharSee · 2017-07-03T14:25:36Z

dd-trace/README.md


+To attach the agent to the JVM, you simply have to declare the provided `jar` file in your 


This explanation of the Agent shouldn't live here, it should go with the first section "Use the autotracing agent for well-known framework". Here, you just link to it.

LotharSee · 2017-07-03T14:26:19Z

dd-trace/README.md


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


It is good to have here the bare minimum to run the javaagent without having the user jumping to the other page (a bit like what you did at the end of the file).

LotharSee · 2017-07-03T14:50:15Z

dd-trace/README.md

-### How the Datadog Tracer (DDTrace) is loaded in the project?
+### <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.


I suggest a different approach.

To add instrumentation to your own code, you can use the OpenTracing API.

Then add a complete example: setting service, resource, tags, ...

Document here the API (so that they don't have to jump to the OT doc). At the same time, we can properly document our special fields (service, resource).

Link to the OT documentation at the end for further documentation.

I'd suggest also including the gradle/maven string to add to your project to add as a compile time dependency.

Should we add a new page for documented the API.

If we add the API, could it be verbose?

tylerbenson

I think we need to replace mentions of "autotracing". After discussing with @LotharSee, I feel it's probably best for now to not rename that project, but leave it as is. Are you ok leaving that project name alone?

tylerbenson · 2017-07-03T14:53:55Z

dd-trace/README.md


-The Datadog Java Tracer is an OpenTracing-compatible tracer. It provides all resources needed to instrument your code.
+The Datadog Tracer is an Opentracing compatible tracer. It provides all resources needed to instrument your code


When mentioning Opentracing the first time, I suggest either adding a link to either https://github.com/opentracing/opentracing-java or http://opentracing.io/.

tylerbenson · 2017-07-03T14:54:38Z

dd-trace/README.md


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


"each operations, each traces" -> "each operation and each trace"

tylerbenson · 2017-07-03T14:58:19Z

dd-trace/README.md

@@ -31,25 +32,80 @@ 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 process for instance.
+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/).


"example of how Opentracing works"

tylerbenson · 2017-07-03T15:03:06Z

dd-trace/README.md

+
+### <a name="framework"></a>Use the autotracing agent for well-known framework
+
+Datadog instruments many frameworks and libraries by default: SpringBoot, JDBC, Mongo, JMS, Tomcat, etc.


"Datadog uses instrumentation contributed by the community to instrument many frameworks..."

tylerbenson · 2017-07-03T15:06:27Z

dd-trace/README.md

-### How the Datadog Tracer (DDTrace) is loaded in the project?
+### <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.


I'd suggest also including the gradle/maven string to add to your project to add as a compile time dependency.

tylerbenson · 2017-07-03T15:08:57Z

dd-trace/README.md

+            <version>${opentracing.version}</version>
+        </dependency>
+
+        <!-- Datadog Tracer (only useful if you do not use the Datadog autotracing agent) -->


"only useful" -> "only needed"

tylerbenson · 2017-07-03T17:48:12Z

As with the other branch, I just force pushed to this branch to make sure the new maven settings are populated everywhere. Please let me know if you have troubles with this force push.

gpolaert · 2017-07-04T15:27:22Z

@LotharSee @tylerbenson updated!

LotharSee · 2017-07-05T07:38:30Z

dd-trace/README.md



-### How to instrument well-known framework?
+## How to instrument your application?


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

LotharSee · 2017-07-05T07:39:30Z

dd-trace/README.md


+1. [Configure the Datadog Tracer](#config)


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).

LotharSee · 2017-07-05T07:43:18Z

dd-trace/README.md


+1. [Configure the Datadog Tracer](#config)
+2. Choose one of the 3 ways to instrument an application:


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:

Run the auto tracing agent

Extend it with your own instrumentation (then in this section we document the Tracer/Span/annotation API).

LotharSee · 2017-07-05T08:11:01Z

dd-trace/README.md


        //Do some thing here ...
        Thread.sleep(1_000);

        // Close the span, the trace will automatically reported to the writer configured
-        span.close();   
+        span.finish();   
    }	

 }


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).

LotharSee · 2017-07-05T08:12:08Z

dd-trace/README.md

    }	

 }
+``` 
+
+The method above is now instrumented. As you can see, the tracer is retrieved from a global registry, called `GlobalTracer`.


This is more advanced, more especially if people run the Trace Agent it is not needed and might confuse them.
We could put that with other advanced examples.

LotharSee · 2017-07-05T08:12:38Z

dd-trace/README.md

-see traces directly to your Datadog account.
+The factory looks for a `dd-trace.yaml` file in the classpath. 
+
+Finally, do not forget to add the corresponding dependencies to your project.


Maybe we should start with that?

tylerbenson · 2017-07-05T15:57:24Z

I agree with @LotharSee's suggestions. I'll approve, but I suggest you adopt his suggestions.

gpolaert · 2017-07-07T10:21:02Z

Sure, I'm still continuing on that PR

gpolaert requested review from awang, tylerbenson and LotharSee July 3, 2017 13:01

LotharSee reviewed Jul 3, 2017

View reviewed changes

tylerbenson suggested changes Jul 3, 2017

View reviewed changes

Documentation

58c9cba

tylerbenson force-pushed the gpolaert/documentation branch from b488134 to 58c9cba Compare July 3, 2017 17:46

gpolaert added 5 commits July 4, 2017 11:18

WIP - according the PR comments

478e032

WIP - adding minimal stuff for DD Java agent

6655369

WIP - manual initialisation of the tracer

09b4b25

WIP - refactor config file

5e9cb89

WIP - adding gradle string

a0b7517

LotharSee reviewed Jul 5, 2017

View reviewed changes

tylerbenson approved these changes Jul 5, 2017

View reviewed changes

Improving Spring Boot documentation

4b9d5f4

Opentracing API documentation

b4739fe

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation #29

Documentation #29

gpolaert commented Jul 3, 2017

LotharSee Jul 3, 2017 •

edited

Loading

LotharSee Jul 3, 2017

LotharSee Jul 3, 2017

LotharSee Jul 3, 2017

LotharSee Jul 3, 2017

LotharSee Jul 3, 2017

tylerbenson Jul 3, 2017

gpolaert Jul 4, 2017 •

edited

Loading

tylerbenson left a comment

tylerbenson Jul 3, 2017

tylerbenson Jul 3, 2017

tylerbenson Jul 3, 2017

tylerbenson Jul 3, 2017

tylerbenson Jul 3, 2017

tylerbenson Jul 3, 2017

tylerbenson commented Jul 3, 2017

gpolaert commented Jul 4, 2017

LotharSee Jul 5, 2017

LotharSee Jul 5, 2017

LotharSee Jul 5, 2017

LotharSee Jul 5, 2017

LotharSee Jul 5, 2017

LotharSee Jul 5, 2017

tylerbenson commented Jul 5, 2017

gpolaert commented Jul 7, 2017


		The method above is now instrumented. As you can see, the tracer is retrieved from a global registry, called `GlobalTracer`.

		The last thing you have to do is providing a configured tracer. This can be easily done by using the `TracerFactory`.

		```
		The annotations are resolved at the runtime by the autotracing agent. If you want to use the annotations,


		To attach the agent to the JVM, you simply have to declare the provided `jar` file in your


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


		The Datadog Java Tracer is an OpenTracing-compatible tracer. It provides all resources needed to instrument your code.
		The Datadog Tracer is an Opentracing compatible tracer. It provides all resources needed to instrument your code


		### <a name="framework"></a>Use the autotracing agent for well-known framework

		Datadog instruments many frameworks and libraries by default: SpringBoot, JDBC, Mongo, JMS, Tomcat, etc.



		### How to instrument well-known framework?
		## How to instrument your application?


		1. [Configure the Datadog Tracer](#config)
		2. Choose one of the 3 ways to instrument an application:

Documentation #29

Documentation #29

Conversation

gpolaert commented Jul 3, 2017

LotharSee Jul 3, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gpolaert Jul 4, 2017 • edited Loading

Choose a reason for hiding this comment

tylerbenson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tylerbenson commented Jul 3, 2017

gpolaert commented Jul 4, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tylerbenson commented Jul 5, 2017

gpolaert commented Jul 7, 2017

LotharSee Jul 3, 2017 •

edited

Loading

gpolaert Jul 4, 2017 •

edited

Loading