Documentation#29

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

No description provided.

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

dd-trace/README.md

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

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

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

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

dd-trace/README.md

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

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

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

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

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

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

dd-trace/README.md

"example of how Opentracing works"

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

dd-trace/README.md

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

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

dd-trace/README.md

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

"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

-Check the dedicated project and agent: [dd-java-agent](../dd-java-agent)
+In order to start to instrument your application, you need to:

+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

+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:


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

+        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 LotharSee, awang and tylerbenson July 3, 2017 13:01

LotharSee reviewed Jul 3, 2017

View reviewed changes

dd-trace/README.md Outdated

Copy link

LotharSee Jul 3, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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



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

Conversation

gpolaert commented Jul 3, 2017

Uh oh!

LotharSee Jul 3, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gpolaert Jul 4, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tylerbenson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tylerbenson commented Jul 3, 2017

Uh oh!

gpolaert commented Jul 4, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tylerbenson commented Jul 5, 2017

Uh oh!

gpolaert commented Jul 7, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

LotharSee Jul 3, 2017 •

edited

Loading

gpolaert Jul 4, 2017 •

edited

Loading