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
> Read the latest version of this README, with working internal links, at [GitHub](https://github.com/Dynatrace/OneAgent-SDK-for-Python#readme).
5
4
6
5
# Dynatrace OneAgent SDK for Python
7
6
8
-
This SDK enables Dynatrace customers to extend request level visibility into
9
-
Python applications. It provides the Python implementation of the [Dynatrace OneAgent
10
-
SDK](https://github.com/Dynatrace/OneAgent-SDK).
7
+
This SDK enables Dynatrace customers to extend request level visibility into Python applications. It provides the Python implementation of the [Dynatrace OneAgent SDK](https://github.com/Dynatrace/OneAgent-SDK).
11
8
12
9
<!-- Generate with https://github.com/jonschlinkert/markdown-toc -->
The SDK supports Python 2 ≥ 2.7 and Python 3 ≥ 3.4. Only the official CPython
39
-
(that is, the "normal" Python, i.e. the Python implementation from
40
-
<https://python.org>) is supported.
35
+
The SDK supports Python 2 ≥ 2.7 and Python 3 ≥ 3.4. Only the official CPython (that is, the "normal" Python, i.e. the Python implementation from <https://python.org>) is supported.
41
36
42
-
The Dynatrace OneAgent SDK for Python is a wrapper of the [Dynatrace OneAgent SDK for C/C++](https://github.com/Dynatrace/OneAgent-SDK-for-C) and therefore the SDK for C/C++ is required and included into the Python SDK. See [here](https://github.com/Dynatrace/OneAgent-SDK-for-C#dynatrace-oneagent-sdk-for-cc-requirements) for its requirements, which also apply to the SDK for Python.
37
+
The Dynatrace OneAgent SDK for Python is a wrapper of the [Dynatrace OneAgent SDK for C/C++](https://github.com/Dynatrace/OneAgent-SDK-for-C) and therefore the SDK for C/C++ is required and delivered with the Python SDK. See [here](https://github.com/Dynatrace/OneAgent-SDK-for-C#dynatrace-oneagent-sdk-for-cc-requirements) for its requirements, which also apply to the SDK for Python.
43
38
44
-
The version of the SDK for C/C++ that is included in each version of the SDK for Python is shown in the following table. The SDK for C/C++'s requirement for the Dynatrace OneAgent is also shown here, for your convenience (it is the same as [listed in the OneAgent SDK for C/C++'s documentation](https://github.com/Dynatrace/OneAgent-SDK-for-C/blob/master/README.md#compatibility-of-dynatrace-oneagent-sdk-for-cc-releases-with-oneagent-releases)).
39
+
The version of the SDK for C/C++ that is included in each version of the SDK for Python is shown in the following table. required Dynatrace OneAgent version is also shown here (it is the same as [listed in the OneAgent SDK for C/C++'s documentation](https://github.com/Dynatrace/OneAgent-SDK-for-C/blob/master/README.md#compatibility-of-dynatrace-oneagent-sdk-for-cc-releases-with-oneagent-releases)).
45
40
46
41
|OneAgent SDK for Python|OneAgent SDK for C/C++|Dynatrace OneAgent|
If everything worked, you should get some output ending with
69
-
`InitResult(status=0, error=None)`. Otherwise, see
70
-
[Troubleshooting](#troubleshooting).
63
+
If the installation was successful, you should get an output ending with `InitResult(status=0, error=None)`. Otherwise, see the [Troubleshooting](#troubleshooting) section.
71
64
72
-
You then need to load the SDK into the application and add code that traces your
73
-
application using the SDK. For a quick “Hello World” that should give you a Path
74
-
in the Dynatrace UI, try this:
65
+
To load the OneAgent SDK into your application, just add the following lines of code at the top of your script:
66
+
67
+
```python
68
+
import oneagent
69
+
from oneagent.sdk importSDK
70
+
```
71
+
72
+
Here is a quick "Hello World" that will produce a service call in Dynatrace:
75
73
76
74
```python
77
75
import oneagent
@@ -88,16 +86,18 @@ input('Please wait...')
88
86
oneagent.shutdown()
89
87
```
90
88
91
-
A more detailed [sample application](https://github.com/Dynatrace/OneAgent-SDK-for-Python/blob/master/samples/basic-sdk-sample/basic_sdk_sample.py) is available. See also Quickstart section in the [API documentation](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/quickstart.html).
89
+
A more detailed [sample application is available here](https://github.com/Dynatrace/OneAgent-SDK-for-Python/blob/master/samples/basic-sdk-sample/basic_sdk_sample.py). See also the Quickstart section in the [API documentation](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/quickstart.html).
92
90
93
91
94
92
<aname="api-concepts"></a>
95
93
## API Concepts
96
94
95
+
Common concepts of the Dynatrace OneAgent SDK are explained the [Dynatrace OneAgent SDK repository](https://github.com/Dynatrace/OneAgent-SDK#apiconcepts).
96
+
97
97
<aname="initialization-and-sdk-objects"></a>
98
98
### Initialization and SDK objects
99
99
100
-
Before first using any other SDK functions, you should initialize the SDK.
100
+
Before first using any other SDK functions, you need to initialize the SDK.
101
101
102
102
```python
103
103
init_result = oneagent.try_init()
@@ -108,22 +108,13 @@ if not init_result:
108
108
print('SDK will definitely not work (i.e. functions will be no-ops).')
See the API documentation for the [`try_init` function](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.try_init) and the [`InitResult` class](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.InitResult) for more information.
property to the [`oneagent.common.AgentState`](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.common.AgentState) constants.
127
118
128
119
```python
129
120
import oneagent.sdk
@@ -173,18 +164,22 @@ strings. Byte strings must always use the UTF-8 encoding!
173
164
<aname="features-and-how-to-use-them"></a>
174
165
## Features and how to use them
175
166
167
+
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.
168
+
169
+
A more detailed specification of the features can be found in [Dynatrace OneAgent SDK](https://github.com/Dynatrace/OneAgent-SDK#features).
170
+
171
+
|Feature|Required OneAgent SDK for Python version|
172
+
|:------|:--------|
173
+
|Trace incoming and outgoing remote calls |>=1.0.0 |
174
+
|SQL database requests |>=1.0.0 |
175
+
|Incoming web requests |>=1.0.0 |
176
+
176
177
<aname="remote-calls"></a>
177
178
### Remote calls
178
179
179
-
You can use the SDK to trace communication from one process to another. This
180
-
will enable you to see full Service Flow, PurePath and Smartscape topology for
181
-
remoting technologies that Dynatrace is not aware of.
180
+
You can use the SDK to trace communication from one process to another. This will enable you to see full Service Flow, PurePath and Smartscape topology for remoting technologies that Dynatrace is not aware of.
182
181
183
-
To trace any kind of remote call you first need to create a Tracer. The Tracer
184
-
object represents the endpoint that you want to call, thus you need to supply
185
-
the name of the remote service and method. In addition, you need to transport
186
-
a tag in your remote call from the client side to the server side if you want
187
-
to trace it end to end.
182
+
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, thus you need to supply the name of the remote service and method. In addition, you need to transport a tag in your remote call from the client side to the server side if you want to trace it end to end.
188
183
189
184
On the client side, you would trace the outgoing remote call like this:
190
185
@@ -221,10 +216,7 @@ See the documentation for more information:
221
216
<aname="sql-database-requests"></a>
222
217
### SQL database requests
223
218
224
-
To trace database requests you need a database info object which stores the
225
-
information about your database which does not change between individual
226
-
requests. This will typically be created somewhere in your initialization code
227
-
(after initializing the SDK):
219
+
To trace database requests you need a database info object which stores the information about your database which does not change between individual requests. This will typically be created somewhere in your initialization code (after initializing the SDK):
228
220
229
221
```python
230
222
@@ -242,8 +234,7 @@ with sdk.trace_sql_database_request(dbinfo, 'SELECT foo FROM bar;') as tracer:
242
234
tracer.set_round_trip_count(3) # Optional
243
235
```
244
236
245
-
Note that you need to release the database info object. You can do this by
246
-
calling `close()` on it or using it in a `with` block.
237
+
Note that you need to release the database info object. You can do this by calling `close()` on it or using it in a `with` block.
247
238
248
239
See the documentation for more information:
249
240
@@ -254,9 +245,7 @@ See the documentation for more information:
254
245
<aname="incoming-web-requests"></a>
255
246
### Incoming web requests
256
247
257
-
[Like for database infos](#sql-database-requests), to trace incoming web
258
-
requests you need a web application info object which stores the information
259
-
about your web application which does not change:
248
+
[Like for database infos](#sql-database-requests), to trace incoming web requests you need a web application info object which stores the information about your web application which does not change:
260
249
261
250
```python
262
251
wappinfo = sdk.create_web_application_info(
@@ -283,24 +272,20 @@ with wreq:
283
272
wreq.set_status_code(200) # OK
284
273
```
285
274
286
-
Note that you need to release the web application info object. You can do this
287
-
by calling `close()` on it or using it in a `with` block.
275
+
Note that you need to release the web application info object. You can do this by calling `close()` on it or using it in a `with` block.
288
276
289
-
Incoming web request tracers support some more features not shown here. Be sure
290
-
to check out the documentation:
277
+
Incoming web request tracers support some more features not shown here. Be sure to check out the documentation:
If you get output containing `InitResult=InitResult(status=0, error=None)`, your
313
-
installation should be fine.
314
-
315
-
Otherwise, hopefully the output is helpful in determining the issue.
297
+
If you get output containing `InitResult=InitResult(status=0, error=None)`, your installation should be fine. Otherwise, the output is helpful in determining the issue.
316
298
317
299
Known gotchas:
318
300
319
-
*`ImportError` or `ModuleNotFoundError` in line 1 that says that there is no
320
-
module named `oneagent`.
301
+
*`ImportError` or `ModuleNotFoundError` in line 1 that says that there is no module named `oneagent`.
321
302
322
-
Make sure that the `pip install` or equivalent succeeded (see
323
-
[here](#installation)). Also make sure you use the `pip` corresponding to your
324
-
`python` (if in doubt, use `python -m pip` instead of `pip` for installing).
303
+
Make sure that the `pip install` or equivalent succeeded (see [here](#installation)). Also make sure you use the `pip` corresponding to your `python` (if in doubt, use `python -m pip` instead of `pip` for installing).
0 commit comments