Merge pull request #2 from Dynatrace/doc

Doc update

Author: Sonja Chèvre

README.md

@@ -4,23 +4,50 @@
 
 This SDK allows Dynatrace customers to instrument java applications. This is useful to enhance the visibility for proprietary frameworks or custom frameworks not directly supported by Dynatrace OneAgent out-of-the-box.
 
-It provides the Java implementation of the [Dynatrace OneAgent SDK](https://github.com/Dynatrace/OneAgent-SDK). 
+This is the official Java implementation of the [Dynatrace OneAgent SDK](https://github.com/Dynatrace/OneAgent-SDK). 
+
+#### Table of Contents
+
+* [Package contents](#package)  
+* [Requirements](#requirements)
+* [Integration](#integration)
+	* [Dependencies](#dependencies)
+	* [Troubleshooting](#troubleshooting)
+* [API Concepts](#apiconcepts)
+	* [OneAgentSDK object](#oneagentsdkobject)
+	* [Tracers](#tracers)
+* [Features](#features)
+ 	* [Trace incoming and outgoing remote calls](#remoting)
+ 	* [In process linking](#inprocess)
+* [Further reading](#furtherreading)
+* [Help & Support](#help)
+* [Release notes](#releasenotes)
+
+<a name="package" />
 
 ## Package contents
 
 - `samples`: contains sample application, which demonstrates the usage of the SDK. see readme inside the samples directory for more details
+- `docs`: contains the reference documentation (javadoc). The most recent version is also available online at [https://dynatrace.github.io/OneAgent-SDK-for-Java/](https://dynatrace.github.io/OneAgent-SDK-for-Java/).
 - `LICENSE`: license under which the whole SDK and sample applications are published
 
-## Features
-Dynatrace OneAgent SDK for Java currently implements support for the following features (corresponding to features specified in [Dynatrace OneAgent SDK](https://github.com/Dynatrace/OneAgent-SDK)):
--  outgoing and incoming remote calls
+<a name="requirements" />
+
+## Requirements
+
+- JRE 1.6 or higher
+- Dynatrace OneAgent (required versions see below)
 
-## Documentation
-The reference documentation is included in this package. The most recent version is also available online at [https://dynatrace.github.io/OneAgent-SDK-for-Java/](https://dynatrace.github.io/OneAgent-SDK-for-Java/).
+|OneAgent SDK for Java|Required OneAgent version|
+|:------|:--------|
+|1.1.0  |>=1.143  |
+|1.0.3  |>=1.135  |
 
-A high level documentation/description of OneAgent SDK concepts is available at [https://github.com/Dynatrace/OneAgent-SDK/](https://github.com/Dynatrace/OneAgent-SDK/).
+<a name="integration" />
 
-## Integrating into your application
+## Integration
+
+<a name="dependencies" />
 
 ### Dependencies
 If you want to integrate the OneAgent SDK into your application, just add the following maven dependency:
@@ -36,23 +63,24 @@ If you prefer to integrate the SDK using plain jar file, just download them from
 
 The Dynatrace OneAgent SDK for Java has no further dependencies.
 
+<a name="troubleshooting" />
+
 ### Troubleshooting
 If the SDK can't connect to the OneAgent (see usage of SDKState in samples) or you you don't see the desired result in the Dynatrace UI, you can set the following system property to print debug information to standard out:
 
 	-Dcom.dynatrace.oneagent.sdk.debug=true
 
 Additionally you should/have to ensure, that you have set a `LoggingCallback`. For usage see class `StdErrLoggingCallback` in `remotecall-server` module (in samples/remotecall folder).
 
-## OneAgent SDK for Java Requirements
-
-- JRE 1.6 or higher
-- Dynatrace OneAgent Java (supported versions see below)
+<a name="apiconcepts" />
 
-# API Concepts
+## API Concepts
 
 Common concepts of the Dynatrace OneAgent SDK are explained the [Dynatrace OneAgent SDK repository](https://github.com/Dynatrace/OneAgent-SDK).
 
-## Get an Api object
+<a name="oneagentsdkobject" />
+
+### OneAgentSDK object
 
 Use OneAgentSDKFactory.createInstance() to obtain an OneAgentSDK instance. You should reuse this object over the whole application 
 and if possible JVM lifetime:
@@ -73,7 +101,9 @@ default:
 
 It is good practice to check the SDK state regularly as it may change at every point of time (except PERMANENTLY_INACTIVE never changes over JVM lifetime).
 
-## Common concepts: Tracers
+<a name="tracers" />
+
+### Tracers
 
 To trace any kind of call you first need to create a Tracer. The Tracer object represents the logical and physical endpoint that you want to call. A Tracer serves two purposes. First to time the call (duraction, cpu and more) and report errors. That is why each Tracer has these three methods. The error method must be called only once, and it must be in between start and end.
 
@@ -86,8 +116,17 @@ void end();
 ```
 The second purpose of a Tracer is to allow tracing across process boundaries. To achieve that these kind of traces supply so called tags. Tags are strings or byte arrays that enable Dynatrace to trace a transaction end to end. As such the tag is the one information that you need to transport across these calls yourselfs.
 
+<a name="features" />
 
-## Using the Dynatrace OneAgent SDK to trace remote calls
+## Features
+
+The feature sets differ slightly with each language implementation. More functionality will be added over time, see <a href="https://answers.dynatrace.com/spaces/483/dynatrace-product-ideas/idea/198106/planned-features-for-oneagent-sdk.html" target="_blank">Planned features for OneAgent SDK</a> for details on upcoming features.
+
+A more detailed specification of the features can be found in [Dynatrace OneAgent SDK](https://github.com/Dynatrace/OneAgent-SDK).
+
+<a name="remoting" />
+
+### Trace incoming and outgoing remote calls
 
 You can use the SDK to trace proprietary IPC communication from one process to the other. This will enable you to see full Service Flow, PurePath and Smartscape topology for remoting technologies that Dynatrace is not aware of.
 
@@ -125,7 +164,9 @@ try {
 }
 ```
 
-## Using the Dynatrace OneAgent SDK for in-process-linking
+<a name="inprocess" />
+
+### In process linking
 
 You can use the SDK to link inside a single process. To link for eg. an asynchronous execution, you need the following code:
 ```Java
@@ -149,17 +190,23 @@ try {
 }
 ```
 
-### Compatibility OneAgent SDK for Java releases with OneAgent for Java releases
-|OneAgent SDK for Java|Dynatrace OneAgent Java|
-|:------|:--------|
-|1.1.0  |>=1.143  |
-|1.0.3  |>=1.135  |
+<a name="furtherreading" />
+
+## Further readings
+
+* <a href="https://www.dynatrace.com/support/help/extend-dynatrace/oneagent-sdk/what-is-oneagent-sdk/" target="_blank">What is the OneAgent SDK?</a> in the Dynatrace documentation
+* <a href="https://answers.dynatrace.com/spaces/483/dynatrace-product-ideas/idea/198106/planned-features-for-oneagent-sdk.html" target="_blank">Feedback & Roadmap thread in AnswerHub</a>
+* <a href="https://www.dynatrace.com/news/blog/dynatrace-oneagent-sdk-for-java-end-to-end-monitoring-for-proprietary-java-frameworks/" target="_blank">Blog: Dynatrace OneAgent SDK for Java: End-to-end monitoring for proprietary Java frameworks</a>
+
+<a name="help" />
+
+## Help & Support
 
-## Feedback
+The Dynatrace OneAgent SDK is an open source project, in beta status. Feedback and feature requests can be filed directly on GitHub or on the <a href="https://answers.dynatrace.com/spaces/483/dynatrace-product-ideas/idea/198106/planned-features-for-oneagent-sdk.html" target="_blank">Feedback & Roadmap thread in AnswerHub</a>.
 
-In case of questions, issues or feature requests feel free to contact the maintainer by dynatrace.oneagent.sdk(at)dynatrace(dot)com or file an issue. Your feedback is welcome!
+<a name="releasenotes" />
 
-## OneAgent SDK for Java release notes
+## Release notes
 |Version|Description|Links|
 |:------|:--------------------------------------|:----------------------------------------|
 |1.1.0  |Added support for in-process-linking   |[binary](https://search.maven.org/remotecontent?filepath=com/dynatrace/oneagent/sdk/java/oneagent-sdk/1.1.0/oneagent-sdk-1.1.0.jar) [source](https://search.maven.org/remotecontent?filepath=com/dynatrace/oneagent/sdk/java/oneagent-sdk/1.0.3/oneagent-sdk-1.0.3-sources.jar) [javadoc](https://search.maven.org/remotecontent?filepath=com/dynatrace/oneagent/sdk/java/oneagent-sdk/1.0.3/oneagent-sdk-1.1.0-javadoc.jar)|