Skip to content

Commit ed83d9c

Browse files
Oberon00Oberon00
committed
Version 1.0rc1.
1 parent 90e7b34 commit ed83d9c

File tree

4 files changed

+305
-35
lines changed

4 files changed

+305
-35
lines changed

‎README.md‎

Lines changed: 281 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -7,16 +7,29 @@ This SDK enables Dynatrace customers to extend request level visibility into
77
Python applications. It provides the Python implementation of the [Dynatrace OneAgent
88
SDK](https://github.com/Dynatrace/OneAgent-SDK).
99

10-
## Features
11-
12-
The Dynatrace OneAgent SDK for Python currently supports the following features
13-
(corresponding to features specified in [Dynatrace OneAgent
14-
SDK](https://github.com/Dynatrace/OneAgent-SDK)):
15-
16-
- Outgoing and incoming remote calls
17-
- SQL Database requests
18-
- Incoming web requests
19-
10+
<!-- Generate with https://github.com/jonschlinkert/markdown-toc -->
11+
12+
<!-- toc -->
13+
14+
- [Requirements](#requirements)
15+
- [Using the OneAgent SDK for Python in your application](#using-the-oneagent-sdk-for-python-in-your-application)
16+
- [API Concepts](#api-concepts)
17+
* [Initialization and SDK objects](#initialization-and-sdk-objects)
18+
* [Tracers](#tracers)
19+
- [Features and how to use them](#features-and-how-to-use-them)
20+
* [Remote calls](#remote-calls)
21+
* [SQL database requests](#sql-database-requests)
22+
* [Incoming web requests](#incoming-web-requests)
23+
- [Troubleshooting](#troubleshooting)
24+
- [Repository contents](#repository-contents)
25+
- [Help & Support](#help--support)
26+
* [Read the manual](#read-the-manual)
27+
* [Let us help you](#let-us-help-you)
28+
- [Release notes](#release-notes)
29+
30+
<!-- tocstop -->
31+
32+
<a name="requirements"></a>
2033
## Requirements
2134

2235
The SDK supports Python 2 ≥ 2.7 and Python 3 ≥ 3.4. Only the official CPython
@@ -37,14 +50,19 @@ documentation](https://github.com/Dynatrace/OneAgent-SDK-for-C/blob/master/READM
3750
|OneAgent SDK for Python|OneAgent SDK for C/C++|Dynatrace OneAgent|
3851
|:----------------------|:---------------------|:-----------------|
3952
|0.1 |1.1.0 |≥1.141 |
53+
|1.0 |1.1.0 |≥1.141 |
4054

55+
<a name="#using-the-oneagent-sdk-for-python-in-your-application"></a>
4156
## Using the OneAgent SDK for Python in your application
4257

43-
<a id="installation"></a>
58+
<a name="installation"></a>
4459

60+
To install the latest version of the OneAgent SDK for Python, use the PyPI package
61+
`oneagent-sdk`:
4562

46-
Just do `python -m pip install --upgrade oneagent-sdk`, to install the latest
47-
version of the OneAgent SDK for Python.
63+
```bash
64+
python -m pip install --upgrade oneagent-sdk
65+
```
4866

4967
To verify your installation, execute
5068

@@ -56,8 +74,6 @@ If everything worked, you should get some output ending with
5674
`InitResult(status=0, error=None)`. Otherwise, see
5775
[Troubleshooting](#troubleshooting).
5876

59-
The output should end with `InitResult(status=0, error=None)`.
60-
6177
You then need to load the SDK into the application and add code that traces your
6278
application using the SDK. For a quick “Hello World” that should give you a Path
6379
in the Dynatrace UI, try this:
@@ -77,21 +93,222 @@ input('Please wait...')
7793
oneagent.shutdown()
7894
```
7995

80-
For this, follow the [tests/onesdksamplepy.py](test/onesdksamplepy.py) example
81-
(see also the
82-
[documentation](https://dynatrace.github.io/OneAgent-SDK-for-Python/quickstart.html)).
96+
For this, follow the
97+
[https://github.com/Dynatrace/OneAgent-SDK-for-Python/blob/master/test/onesdksamplepy.py](test/onesdksamplepy.py)
98+
example (see also Quickstart section in the
99+
[documentation](https://dynatrace.github.io/OneAgent-SDK-for-Python/)).
83100

84-
## Documentation
85101

86-
The most recent version of the documentation can be viewed at
87-
<https://dynatrace.github.io/OneAgent-SDK-for-Python/>.
102+
<a name="api-concepts"></a>
103+
## API Concepts
88104

89-
A high level documentation/description of OneAgent SDK concepts is available at
90-
<https://github.com/Dynatrace/OneAgent-SDK/>.
105+
<a name="initialization-and-sdk-objects"></a>
106+
### Initialization and SDK objects
107+
108+
Before first using any other SDK functions, you should initialize the SDK.
109+
110+
```python
111+
init_result = oneagent.try_init()
112+
print('OneAgent SDK initialization result' + repr(init_result))
113+
if init_result:
114+
print('SDK should work (but agent might be inactive).')
115+
if not init_result:
116+
print('SDK will definitely not work (i.e. functions will be no-ops).')
117+
```
118+
119+
See the documentation for the [`try_init`
120+
function](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.try_init)
121+
and the [`InitResult`
122+
class](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.InitResult)
123+
for more information.
124+
125+
To then use the SDK, get a reference to the
126+
[`SDK`](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.sdk.SDK)
127+
singleton by calling its static
128+
[`get`](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.sdk.SDK.get)
129+
static method. The first thing you may want to do with this object, is checking
130+
if the agent is active by comparing the value of the
131+
[`agent_state`](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.sdk.SDK.agent_state)
132+
property to the
133+
[`oneagent.common.AgentState`](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.common.AgentState)
134+
constants.
135+
136+
```python
137+
import oneagent.sdk
138+
from oneagent.common import AgentState
139+
# Initialize oneagent, as above
140+
141+
sdk = oneagent.sdk.SDK.get()
142+
if sdk.agent_state not in (AgentState.ACTIVE,
143+
AgentState.TEMPORARILY_INACTIVE):
144+
print('Too bad, you will not see data from this process.')
145+
```
146+
147+
<a name="tracers"></a>
148+
### Tracers
149+
150+
To trace any kind of call you first need to create a
151+
[Tracer](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.sdk.tracers.Tracer),
152+
using one of the various `trace_*` methods of the
153+
[`SDK`](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.sdk.SDK)
154+
object. The Tracer object controls the “life cycle” of a trace: Entering a
155+
`with`-block with a tracer starts the trace, exiting it ends it. Exiting the
156+
`with` block with an exception causes the trace to be marked as failed with the
157+
exception message (if you do not want or need this behavior, tracers have
158+
explicit methods for starting, ending and attaching error information too; see
159+
the
160+
[documentation](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.sdk.tracers.Tracer)).
161+
162+
There are different tracer types requiring different information for creation.
163+
As an example, to trace an incoming remote call, this would be the most simple
164+
way to trace it:
165+
166+
```python
167+
from oneagent.sdk import SDK
168+
169+
with SDK.get().trace_incoming_remote_call('method', 'service', 'endpoint'):
170+
pass # Here you would do the actual work that is timed
171+
```
172+
173+
See the section on [remote calls](#remote-calls) for more information.
174+
175+
Some tracers also support attaching additional information before ending it.
176+
177+
**Important:** In Python 2, tracers accept both byte (“normal”) and unicode
178+
strings. Byte strings must always use the UTF-8 encoding!
179+
180+
181+
<a name="features-and-how-to-use-them"></a>
182+
## Features and how to use them
183+
184+
<a name="remote-calls"></a>
185+
### Remote calls
186+
187+
You can use the SDK to trace communication from one process to another. This
188+
will enable you to see full Service Flow, PurePath and Smartscape topology for
189+
remoting technologies that Dynatrace is not aware of.
190+
191+
To trace any kind of remote call you first need to create a Tracer. The Tracer
192+
object represents the endpoint that you want to call, thus you need to supply
193+
the name of the remote service and method. In addition, you need to transport
194+
a tag in your remote call from the client side to the server side if you want
195+
to trace it end to end.
196+
197+
On the client side, you would trace the outgoing remote call like this:
198+
199+
```python
200+
outcall = sdk.trace_outgoing_remote_call(
201+
'remoteMethodToCall', 'RemoteServiceName', 'rmi://Endpoint/service',
202+
oneagent.sdk.Channel(oneagent.sdk.ChannelType.TCP_IP, 'remoteHost:1234'),
203+
protocol_name='RMI/custom')
204+
with outcall:
205+
# Note: You can access outgoing_dynatrace_*_tag only after the trace
206+
# has started!
207+
strtag = outcall.outgoing_dynatrace_string_tag
208+
do_actual_remote_call(extra_headers={'X-dynaTrace': strtag})
209+
```
210+
211+
On the server side, you would trace it like this:
212+
213+
```python
214+
incall = sdk.trace_incoming_remote_call(
215+
'remoteMethodToCall', 'RemoteServiceName', 'rmi://Endpoint/service',
216+
protocol_name='RMI/custom',
217+
str_tag=my_remote_message.get_header_optional('X-dynaTrace'))
218+
with incall:
219+
pass # Here you would do the actual work that is timed
220+
```
221+
222+
See the documentation for more information:
91223

224+
* [`trace_incoming_remote_call`](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.sdk.SDK.trace_incoming_remote_call)
225+
* [`trace_outgoing_remote_call`](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.sdk.tracers.trace_outgoing_remote_call)
226+
* [General information on
227+
tagging](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/tagging.html)
228+
229+
<a name="sql-database-requests"></a>
230+
### SQL database requests
231+
232+
To trace database requests you need a database info object which stores the
233+
information about your database which does not change between individual
234+
requests. This will typically be created somewhere in your initialization code
235+
(after initializing the SDK):
236+
237+
```python
238+
239+
dbinfo = sdk.create_database_info(
240+
'Northwind', oneagent.sdk.DatabaseVendor.SQLSERVER,
241+
oneagent.sdk.Channel(oneagent.sdk.ChannelType.TCP_IP, '10.0.0.42:6666'))
242+
```
243+
244+
Then you can trace the SQL database requests:
245+
246+
```python
247+
with sdk.trace_sql_database_request(dbinfo, 'SELECT foo FROM bar;') as tracer:
248+
# Do actual DB request
249+
tracer.set_rows_returned(42) # Optional
250+
tracer.set_round_trip_count(3) # Optional
251+
```
252+
253+
Note that you need to release the database info object. You can do this by
254+
calling `close()` on it or using it in a `with` block.
255+
256+
See the documentation for more information:
257+
258+
* [`create_database_info`](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.sdk.SDK.create_database_info)
259+
* [`trace_sql_database_request`](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.sdk.SDK.trace_sql_database_request)
260+
* [`DatabaseRequestTracer`](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.sdk.tracers.DatabaseRequestTracer)
261+
262+
<a name="incoming-web-requests"></a>
263+
### Incoming web requests
264+
265+
[Like for database infos](#sql-database-requests), to trace incoming web
266+
requests you need a web application info object which stores the information
267+
about your web application which does not change:
268+
269+
```python
270+
wappinfo = sdk.create_web_application_info(
271+
virtual_host='example.com',
272+
application_id='MyWebApplication',
273+
context_root='/my-web-app/')
274+
```
275+
276+
Then you can trace incoming web requests:
277+
278+
```python
279+
280+
wreq = sdk.trace_incoming_web_request(
281+
wappinfo,
282+
'http://example.com/my-web-app/foo?bar=baz',
283+
'GET',
284+
headers={'Host': 'example.com', 'X-foo': 'bar'},
285+
remote_address='127.0.0.1:12345')
286+
287+
with wreq:
288+
wreq.add_parameter('my_form_field', '1234')
289+
# Process web request
290+
wreq.add_response_headers({'Content-Length': '1234'})
291+
wreq.set_status_code(200) # OK
292+
```
293+
294+
Note that you need to release the web application info object. You can do this
295+
by calling `close()` on it or using it in a `with` block.
296+
297+
Incoming web request tracers support some more features not shown here. Be sure
298+
to check out the documentation:
299+
300+
* [`create_web_application_info`](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.sdk.SDK.create_web_application_info)
301+
* [`trace_incoming_web_request`](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.sdk.SDK.trace_incoming_web_request)
302+
* [`IncomingWebRequestTracer`](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.sdk.tracers.IncomingWebRequestTracer)
303+
304+
There is currently no explicit support for tracing outgoing web requests. You
305+
can use an [outgoing remote call tracer](#remote-calls) instead.
306+
307+
<a name="troubleshooting"></a>
92308
## Troubleshooting
93309

94-
To debug your OneSDK installation, execute the following Python code:
310+
To debug your OneAgent SDK for Python installation, execute the following
311+
Python code:
95312

96313
```python
97314
import oneagent
@@ -114,6 +331,7 @@ Known gotchas:
114331
[here](#installation)). Also make sure you use the `pip` corresponding to your
115332
`python` (if in doubt, use `python -m pip` instead of `pip` for installing).
116333

334+
<a name="repository-contents"></a>
117335
## Repository contents
118336

119337
If you are viewing the [GitHub
@@ -124,10 +342,48 @@ repository](https://github.com/Dynatrace/OneAgent-SDK-for-Python), you will see:
124342
- `src/`: Actual source code of the Python OneAgent SDK.
125343
- `docs/`: Source files for the ([Sphinx](https://sphinx-doc.org)-based) HTML
126344
documentation. For the actual, readable documentation, see
127-
[here](#documenation).
345+
[here](#documentation).
128346
- `tests/`, `test-util-src/`: Contains tests and test support files that are
129347
useful (only) for developers wanting contribute to the SDK itself.
130348
- `setup.py`, `setup.cfg`, `MANIFEST.in`, `project.toml`: Development files
131349
required for creating e.g. the PyPI package for the Python OneAgent SDK.
132350
- `tox.ini`, `pylintrc`: Supporting files for developing the SDK itself. See
133351
<https://tox.readthedocs.io/en/latest/> and <https://www.pylint.org/>.
352+
353+
<a name="help--support"></a>
354+
## Help & Support
355+
356+
<a name="documentation"></a>
357+
<a name="read-the-manual"></a>
358+
### Read the manual
359+
360+
* The most recent version of the documentation for the Python SDK can be viewed at
361+
<https://dynatrace.github.io/OneAgent-SDK-for-Python/>.
362+
* A high level documentation/description of OneAgent SDK concepts is available at
363+
<https://github.com/Dynatrace/OneAgent-SDK/>.
364+
* Of course, [this README](#) also contains lots of useful information.
365+
366+
<a name="let-us-help-you"></a>
367+
### Let us help you
368+
369+
Make sure your issue is not already solved in the [available
370+
documentation](#documenation) before you ask for help. Especially the
371+
[troubleshooting section in this README](#troubleshooting) may prove helpful.
372+
373+
374+
* Ask a question in the [product
375+
forums](https://answers.dynatrace.com/spaces/482/view.html).
376+
* Open a [GitHub
377+
issue](https://github.com/Dynatrace/OneAgent-SDK-for-Python/issues) to:
378+
* Report minor defects or typos.
379+
* Ask for improvements or changes in the SDK API.
380+
* Ask any questions related to the community effort.
381+
382+
SLAs don't apply for GitHub tickets.
383+
384+
## Release notes
385+
386+
Please see the [GitHub
387+
releases page](https://github.com/Dynatrace/OneAgent-SDK-for-Python/releases),
388+
and the [PyPI release
389+
history](https://pypi.org/project/oneagent-sdk/#history).

‎docs/index.rst‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
1-
Welcome to the documentation for Dynatrace OneAgent and SDK for Python
2-
======================================================================
1+
Welcome to the documentation for Dynatrace OneAgent SDK for Python
2+
==================================================================
3+
4+
If you are new to the Dynatrace OneAgent SDK for Python, please consult the
5+
`README on GitHub
6+
<https://github.com/Dynatrace/OneAgent-SDK-for-Python/blob/master/README.md#readme>`_
7+
It also contains installation instructions.
38

49
.. toctree::
510
:maxdepth: 2

0 commit comments

Comments
 (0)