Merge branch 'master' of https://github.com/Dynatrace/OneAgent-ADK-Java-Samples

Author: alramlechner

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" />
 
-## 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/).
+## Requirements
 
-A high level documentation/description of OneAgent SDK concepts is available at [https://github.com/Dynatrace/OneAgent-SDK/](https://github.com/Dynatrace/OneAgent-SDK/).
+- JRE 1.6 or higher
+- Dynatrace OneAgent (required versions see below)
 
-## Integrating into your application
+|OneAgent SDK for Java|Required OneAgent version|
+|:------|:--------|
+|1.1.0  |>=1.143  |
+|1.0.3  |>=1.135  |
+
+<a name="integration" />
+
+## Integration
+
+<a name="dependencies" />
 
 ### Dependencies
 If you want to integrate the OneAgent SDK into your application, just add the following maven dependency:
@@ -32,27 +59,28 @@ If you want to integrate the OneAgent SDK into your application, just add the fo
 	  <scope>compile</scope>
 	</dependency>
 
-If you prefer to integrate the SDK using plain jar file, just download them from mavenCentral - Dynatrace OneAgent SDK for Java [binary](https://search.maven.org/remotecontent?filepath=com/dynatrace/oneagent/sdk/java/oneagent-sdk/1.0.3/oneagent-sdk-1.0.3.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) and [javadoc](https://search.maven.org/remotecontent?filepath=com/dynatrace/oneagent/sdk/java/oneagent-sdk/1.0.3/oneagent-sdk-1.0.3-javadoc.jar)
+If you prefer to integrate the SDK using plain jar file, just download them from mavenCentral. You can find the download links for each version in the [Release notes](#releasenotes) section.
 
 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
+<a name="apiconcepts" />
 
-- JRE 1.6 or higher
-- Dynatrace OneAgent Java (supported versions see below)
+## API Concepts
 
-# API Concepts
+Common concepts of the Dynatrace OneAgent SDK are explained the [Dynatrace OneAgent SDK repository](https://github.com/Dynatrace/OneAgent-SDK#apiconcepts).
 
-Common concepts of the Dynatrace OneAgent SDK are explained the [Dynatrace OneAgent SDK repository](https://github.com/Dynatrace/OneAgent-SDK).
+<a name="oneagentsdkobject" />
 
-## Get an Api object
+### 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,22 @@ 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" />
+
+## 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#features).
+
+|Feature|Required OneAgent SDK for Java version|
+|:------|:--------|
+|Trace incoming and outgoing remote calls  |>=1.0.3  |
+|In process linking  |>=1.1.0  |
 
-## Using the Dynatrace OneAgent SDK to trace remote calls
+<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 +169,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 +195,43 @@ 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
+
+The Dynatrace OneAgent SDK for Java is an open source project, currently in beta status. The features are fully supported by Dynatrace. 
+
+**Get Help**
+* Ask a question in the <a href="https://answers.dynatrace.com/spaces/482/view.html" target="_blank">product forums</a>
+* Read the <a href="https://www.dynatrace.com/support/help/" target="_blank">product documentation</a>
+
+**Open a <a href="https://github.com/Dynatrace/OneAgent-SDK-for-Java/issues">GitHub issue</a> to:**
+* Report minor defects, minor items or typos
+* Ask for improvements or changes in the SDK API
+* Ask any questions related to the community effort
+
+SLAs don't apply for GitHub tickets
+
+**Customers can open a ticket on the <a href="https://support.dynatrace.com/supportportal/" target="_blank">Dynatrace support portal</a> to:**
+* Get support from the Dynatrace technical support engineering team
+* Manage and resolve product related technical issues
+
+SLAs apply according to the customer's support level.
+
+<a name="releasenotes" />
 
-## Feedback
+## Release notes
 
-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!
+see also https://github.com/Dynatrace/OneAgent-SDK-for-Java/releases
 
-## OneAgent SDK for Java 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)|