You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+62-38Lines changed: 62 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,8 @@
2
2
3
3
# Dynatrace OneAgent SDK for Java
4
4
5
-
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.
5
+
This SDK allows Dynatrace customers to instrument java applications. This is useful to enhance the visibility for proprietary frameworks or
6
+
custom frameworks not directly supported by Dynatrace OneAgent out-of-the-box.
6
7
7
8
This is the official Java implementation of the [Dynatrace OneAgent SDK](https://github.com/Dynatrace/OneAgent-SDK).
8
9
@@ -17,12 +18,12 @@ This is the official Java implementation of the [Dynatrace OneAgent SDK](https:/
17
18
* [OneAgentSDK object](#oneagentsdkobject)
18
19
* [Tracers](#tracers)
19
20
*[Features](#features)
20
-
* [Trace incoming and outgoing remote calls](#remoting)
21
-
* [In process linking](#inprocess)
22
-
* [Add custom request attributes](#scav)
23
-
* [Trace web requests](#webrequests)
24
-
* [Trace incoming web requests](#inwebrequests)
25
-
* [Trace outgoing web requests](#outwebrequests)
21
+
* [Trace incoming and outgoing remote calls](#remoting)
22
+
* [In process linking](#inprocess)
23
+
* [Add custom request attributes](#scav)
24
+
* [Trace web requests](#webrequests)
25
+
* [Trace incoming web requests](#inwebrequests)
26
+
* [Trace outgoing web requests](#outwebrequests)
26
27
* [Trace messaging](#messaging)
27
28
*[Further reading](#furtherreading)
28
29
*[Help & Support](#help)
@@ -64,22 +65,25 @@ If you want to integrate the OneAgent SDK into your application, just add the fo
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.
72
+
If you prefer to integrate the SDK using plain jar file, just download them from mavenCentral. You can find the download links for each
73
+
version in the [Release notes](#releasenotes) section.
72
74
73
75
The Dynatrace OneAgent SDK for Java has no further dependencies.
74
76
75
77
<aname="troubleshooting" />
76
78
77
79
### Troubleshooting
78
-
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:
80
+
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,
81
+
you can set the following system property to print debug information to standard out:
79
82
80
83
-Dcom.dynatrace.oneagent.sdk.debug=true
81
84
82
-
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).
85
+
Additionally you should/have to ensure, that you have set a `LoggingCallback`. For usage see class `StdErrLoggingCallback` in
86
+
`remotecall-server` module (in samples/remotecall folder).
83
87
84
88
<aname="apiconcepts" />
85
89
@@ -108,13 +112,16 @@ default:
108
112
}
109
113
```
110
114
111
-
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).
115
+
It is good practice to check the SDK state regularly as it may change at every point of time (except PERMANENTLY_INACTIVE never
116
+
changes over JVM lifetime).
112
117
113
118
<aname="tracers" />
114
119
115
120
### Tracers
116
121
117
-
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.
122
+
To trace any kind of call you first need to create a Tracer. The Tracer object represents the logical and physical endpoint that
123
+
you want to call. A Tracer serves two purposes. First to time the call (duraction, cpu and more) and report errors. That is why
124
+
each Tracer has these three methods. The error method must be called only once, and it must be in between start and end.
118
125
119
126
```Java
120
127
void start();
@@ -123,13 +130,16 @@ void error(String message);
123
130
124
131
void end();
125
132
```
126
-
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.
133
+
The second purpose of a Tracer is to allow tracing across process boundaries. To achieve that these kind of traces supply so called
134
+
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
135
+
that you need to transport across these calls yourselfs.
127
136
128
137
<aname="features" />
129
138
130
139
## Features
131
140
132
-
The feature sets differ slightly with each language implementation. More functionality will be added over time, see <ahref="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.
141
+
The feature sets differ slightly with each language implementation. More functionality will be added over time, see <ahref="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>
142
+
for details on upcoming features.
133
143
134
144
A more detailed specification of the features can be found in [Dynatrace OneAgent SDK](https://github.com/Dynatrace/OneAgent-SDK#features).
135
145
@@ -146,12 +156,16 @@ A more detailed specification of the features can be found in [Dynatrace OneAgen
146
156
147
157
### Trace incoming and outgoing remote calls
148
158
149
-
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.
159
+
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
160
+
and Smartscape topology for remoting technologies that Dynatrace is not aware of.
150
161
151
-
To trace any kind of remote call you first need to create a Tracer. The Tracer object represents the endpoint that you want to call, as such you need to supply the name of the remote service and remote method. In addition you need to transport the tag in your remote call to the server side if you want to trace it end to end.
162
+
To trace any kind of remote call you first need to create a Tracer. The Tracer object represents the endpoint that you want to call, as such you
163
+
need to supply the name of the remote service and remote method. In addition you need to transport the tag in your remote call to the server side
On the server side you need to wrap the handling and processing of your remote call as well. This will not only trace the server side call and everything that happens, it will also connect it to the calling side.
181
+
On the server side you need to wrap the handling and processing of your remote call as well. This will not only trace the server side call and
182
+
everything that happens, it will also connect it to the calling side.
You can use the SDK to add custom request attributes to the current traced service. Custom request attributes allow you to do advanced filtering of your requests in Dynatrace.
230
+
You can use the SDK to add custom request attributes to the current traced service. Custom request attributes allow you to do advanced filtering of
231
+
your requests in Dynatrace.
216
232
217
233
Adding custom request attributes to the currently traced service call is simple. Just call one of the addCustomRequestAttribute methods with your key and value:
218
234
@@ -231,18 +247,21 @@ When no service call is being traced, the custom request attributes are dropped.
231
247
232
248
#### Trace incoming web requests
233
249
234
-
You can use the SDK to trace incoming web requests. This might be useful if Dynatrace does not support the respective web server framework or language processing the incoming web requests.
250
+
You can use the SDK to trace incoming web requests. This might be useful if Dynatrace does not support the respective web server framework or language
251
+
processing the incoming web requests.
235
252
236
-
To trace an incoming web request you first need to create a WebServerInfo object. The info object represents the endpoint of your web server (web server name, application name and context root). This object should be reused for all traced web requests within for the same application.
253
+
To trace an incoming web request you first need to create a WebServerInfo object. The info object represents the endpoint of your web server (web server
254
+
name, application name and context root). This object should be reused for all traced web requests within for the same application.
To trace a specific incoming web request you then need to create a Tracer object. Make sure you provide all http headers from the request to the SDK by calling addRequestHeader(...). This ensures that tagging with our built-in sensor will work.
260
+
To trace a specific incoming web request you then need to create a Tracer object. Make sure you provide all http headers from the request to the SDK by
261
+
calling addRequestHeader(...). This ensures that tagging with our built-in sensor will work.
You can use the SDK to trace outgoing web requests. This might be useful if Dynatrace does not support the respective http library or language sending the request.
295
+
You can use the SDK to trace outgoing web requests. This might be useful if Dynatrace does not support the respective http library or
296
+
language sending the request.
277
297
278
-
To trace an outgoing web request you need to create a Tracer object. It is important to send the Dynatrace Header. This ensures that tagging with our built-in sensor will work.
298
+
To trace an outgoing web request you need to create a Tracer object. It is important to send the Dynatrace Header. This ensures that
for (Entry<String, List<String>> entry : yourHttpClient.getHeaderFields().entrySet()) {
@@ -341,7 +363,8 @@ try {
341
363
}
342
364
```
343
365
344
-
On the incoming side, we need to differentiate between the blocking receiving part and processing the received message. Therefore two different tracers are being used: ``ReceivingMessageTracer`` and ``ProcessingMessageTracer``.
366
+
On the incoming side, we need to differentiate between the blocking receiving part and processing the received message. Therefore two
367
+
different tracers are being used: ``ReceivingMessageTracer`` and ``ProcessingMessageTracer``.
In case of non-blocking receive (e. g. via eventhandler), there is no need to use ``ReceivingMessageTracer`` - just trace processing of the message by using the ``ProcessingMessageTracer``:
405
+
In case of non-blocking receive (e. g. via eventhandler), there is no need to use ``ReceivingMessageTracer`` - just trace processing
406
+
of the message by using the ``ProcessingMessageTracer``:
0 commit comments