Skip to content

Commit eb657ee

Browse files
beniwohlibeniwohli
committed
API docs and API simplifications (#112)
 * documents large parts of the public API * changed API of `capture_exception`, `capture_message`. Instead of an opaque `data` argument, they now have keyword arguments for `context`, `custom`, etc. * removed special handling of template errors in Django. This only ever worked with `TEMPLATE_DEBUG` enabled, and the data was never shown. closes #112
1 parent c8a0099 commit eb657ee

File tree

25 files changed

+502
-551
lines changed

25 files changed

+502
-551
lines changed

‎.travis.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ matrix:
5959
- stage: linters
6060
env: LINTER="flake8"
6161
python: 3.6
62-
script: pip install -U flake8 && flake8 elasticapm
62+
script: pip install -U flake8 flake8-per-file-ignores && flake8 elasticapm
6363

6464
- stage: linters
6565
script: make docs

‎CHANGELOG.asciidoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ https://github.com/elastic/apm-agent-python/compare/v1.0.0.dev3\...master[Check
1818
* added setting to disable SSL certificate verification ({pull}108[#108])
1919
* BREAKING: renamed `server` configuration variable to `server_url` to better align with other language agents ({pull}105[#105])
2020
* BREAKING: removed the old and unused urllib2-based HTTP transport, and renamed the urllib3 transport ({pull}107[#107])
21+
* BREAKING: several API changes to `capture_exception`, `capture_message`, and added documentation for these and other APIs ({pull}112[#112])
2122

2223
[[release-v1.0.0.dev3]]
2324
[float]

‎docs/api.asciidoc‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
[[api]]
2+
== Public API
3+
4+
The Elastic APM Python agent has several public APIs.
5+
Most of the public API functionality is not needed when using one of our <<framework-support, supported frameworks>>,
6+
but they allow customized usage.
7+
8+
[float]
9+
[[client-api]]
10+
=== Client API
11+
12+
The public Client API consists of several methods on the `Client` class.
13+
This API can be used to track exceptions and log messages,
14+
as well as to mark the beginning and end of transactions.
15+
16+
[float]
17+
[[client-api-init]]
18+
==== Instantiation
19+
20+
To create a `Client` instance, import it and call its constructor:
21+
22+
[source,python]
23+
----
24+
from elasticapm import Client
25+
26+
client = Client({'APP_NAME': 'example'}, **defaults)
27+
----
28+
29+
* `config`: A dictionary, with key/value configuration. For the possible configuration keys, see <<configuration, Configuration>>.
30+
* `**defaults`: default values for configuration. These can be omitted in most cases, and take the least precedence.
31+
32+
NOTE: framework integrations like <<django-support, Django>> and <<flask-support, Flask>>
33+
instantiate the client automatically.
34+
35+
[float]
36+
[[error-api]]
37+
==== Errors
38+
39+
[float]
40+
[[client-api-capture-exception]]
41+
===== `Client.capture_exception()`
42+
43+
Captures an exception object:
44+
45+
[source,python]
46+
----
47+
try:
48+
x = int("five")
49+
except ValueError:
50+
client.capture_exception()
51+
----
52+
53+
* `exc_info`: A `(type, value, traceback)` tuple as returned by https://docs.python.org/3/library/sys.html#sys.exc_info[`sys.exc_info()`]. If not provided, it will be captured automatically.
54+
* `date`: A `datetime.datetime` object representing the occurrence time of the error. If left empty, it defaults to `datetime.datetime.utcnow()`.
55+
* `context`: A dictionary with contextual information. This dictionary must follow the
56+
https://www.elastic.co/guide/en/apm/server/current/error-api.html#error-context-schema[Context] schema definition.
57+
* `custom`: A dictionary of custom data you want to attach to the event.
58+
59+
Returns the id of the error as a string.
60+
61+
[float]
62+
[[client-api-capture-message]]
63+
===== `Client.capture_message()`
64+
65+
Captures a message with optional added contextual data. Example:
66+
67+
[source,python]
68+
----
69+
client.capture_message('Billing process succeeded.')
70+
----
71+
72+
* `message`: The message as a string.
73+
* `param_message`: Alternatively, a parametrized message as a dictionary.
74+
The dictionary contains two values: `message`, and `params`.
75+
This allows the APM server to group messages together that share the same
76+
parametrized message. Example:
77+
+
78+
[source,python]
79+
----
80+
client.capture_message(param_message={
81+
'message': 'Billing process for %s succeeded. Amount: %s',
82+
'params': (customer.id, order.total_amount),
83+
})
84+
----
85+
+
86+
* `stack`: If set to `True` (the default), a stacktrace from the call site will be captured.
87+
* `exc_info`: A `(type, value, traceback)` tuple as returned by
88+
https://docs.python.org/3/library/sys.html#sys.exc_info[`sys.exc_info()`].
89+
If not provided, it will be captured automatically, if `capture_message()` was called in an `except` block.
90+
* `date`: A `datetime.datetime` object representing the occurrence time of the error.
91+
If left empty, it defaults to `datetime.datetime.utcnow()`.
92+
* `context`: A dictionary with contextual information. This dictionary must follow the
93+
https://www.elastic.co/guide/en/apm/server/current/error-api.html#error-context-schema[Context] schema definition.
94+
* `custom`: A dictionary of custom data you want to attach to the event.
95+
96+
Returns the id of the message as a string.
97+
98+
NOTE: Either the `message` or the `param_message` argument is required.
99+
100+
[float]
101+
[[transaction-api]]
102+
==== Transactions
103+
104+
[float]
105+
[[client-api-begin-transaction]]
106+
===== `Client.begin_transaction()`
107+
Begin tracking a transaction.
108+
Should be called e.g. at the beginning of a request or when starting a background task. Example:
109+
110+
[source,python]
111+
----
112+
client.begin_transaction('processors')
113+
----
114+
115+
* `transaction_type`: (*required*) A string describing the type of the transaction, e.g. `'request'` or `'celery'`.
116+
117+
[float]
118+
[[client-api-end-transaction]]
119+
===== `Client.end_transaction()`
120+
End tracking the transaction.
121+
Should be called e.g. at the end of a request or when ending a background task. Example:
122+
123+
[source,python]
124+
----
125+
client.end_transaction('myapp.billing_process', processor.status)
126+
----
127+
128+
* `name`: (*required*) A string describing the name of the transaction, e.g. `process_order`.
129+
This is typically the name of the view/controller that handles the request, or the route name.
130+
* `result`: (*required*) A string describing the result of the transaction.
131+
This is typically the HTTP status code, or e.g. `'success'` for a background task.
132+
133+
134+
[float]
135+
[[api-other]]
136+
=== Other APIs
137+
138+
[float]
139+
[[api-elasticapm-instrument]]
140+
==== `elasticapm.instrument()`
141+
142+
Instruments libraries automatically.
143+
This includes a wide range of standard library and 3rd party modules.
144+
A list of instrumented modules can be found in `elasticapm.intrumentation.register`.
145+
This function should be called as early as possibly in the startup of your application.
146+
For <<framework-support, supported frameworks>>, this is called automatically. Example:
147+
148+
[source,python]
149+
----
150+
import elasticapm
151+
152+
elasticapm.instrument()
153+
----
154+
155+
[float]
156+
[[api-set-transaction-name]]
157+
==== `elasticapm.set_transaction_name()`
158+
159+
Override the name of the current transaction.
160+
For supported frameworks, the transaction name is determined automatically,
161+
and can be overridden using this function. Example:
162+
163+
[source,python]
164+
----
165+
import elasticapm
166+
167+
elasticapm.set_transaction_name('myapp.billing_process')
168+
----
169+
170+
* `name`: (*required*) A string describing name of the transaction
171+
172+
[float]
173+
[[api-set-transaction-data]]
174+
==== `elasticapm.set_transaction_data()`
175+
176+
Attach custom contextual data to current transaction.
177+
Supported frameworks will automatically attach information about the HTTP request and the logged in user.
178+
You can attach further data using this function. Example:
179+
180+
[source,python]
181+
----
182+
import elasticapm
183+
184+
elasticapm.set_transaction_data({'billing_amount': product.price * item_count})
185+
----
186+
187+
188+
* `data`: (*required*) A dictionary with the data to be attached. This should be a flat key/value `dict` object.
189+
* `_key`: The key to use for this `dict` object. Defaults to `custom`.
190+
+
191+
NOTE: This should only be overridden by framework integrations.

‎docs/configuration.asciidoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ To configure Django, add an `ELASTIC_APM` dictionary to your `settings.py`:
1414
----
1515
ELASTIC_APM = {
1616
'APP_NAME': 'my-app',
17-
'SECRET_TOKEN': 'changeme,
17+
'SECRET_TOKEN': 'changeme',
1818
}
1919
----
2020

@@ -28,7 +28,7 @@ To configure Flask, add an `ELASTIC_APM` dictonary to your `app.config`:
2828
----
2929
app.config['ELASTIC_APM'] = {
3030
'APP_NAME': 'my-app',
31-
'SECRET_TOKEN': 'changeme,
31+
'SECRET_TOKEN': 'changeme',
3232
}
3333
3434
apm = ElasticAPM(app)

‎docs/django.asciidoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,8 @@ ELASTIC_APM_SECRET_TOKEN=<SECRET-TOKEN>
5656

5757
You now have basic error logging set up, and everything resulting in a 500 HTTP status code will be reported to the APM Server.
5858

59+
You can find a list of all available settings in the <<configuration, Configuration>> page.
60+
5961
[float]
6062
[[django-performance-metrics]]
6163
=== Performance Metrics

‎docs/index.asciidoc‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
= APM Python Agent Reference (Experimental)
22

3+
[[getting-started]]
34
== Getting started
45

56
Welcome to the APM Python agent docs.
@@ -17,6 +18,16 @@ ifdef::env-github[]
1718
NOTE: For the best reading experience, please head over to this document at https://www.elastic.co/guide/en/apm/agent/python/current/index.html[elastic.co]
1819
endif::[]
1920

21+
[[framework-support]]
22+
The Elastic APM Python Agent comes with support for the following frameworks:
23+
24+
* <<django-support,Django>> 1.8 - 2.0
25+
* <<flask-support,Flask>> 0.10+
26+
27+
For other frameworks and custom Python code, the agent exposes a set of <<api,APIs>> for integration.
28+
29+
NOTE: The Elastic APM Python agent does currently not support asynchronous frameworks like Twisted or Tornado.
30+
2031
include::./configuration.asciidoc[Configuration]
2132

2233
include::./django.asciidoc[Django support]
@@ -28,3 +39,5 @@ include::./flask.asciidoc[Flask support]
2839
include::./custom-instrumentation.asciidoc[Custom Instrumentation]
2940
include::./sanitizing-data.asciidoc[Sanitizing Data]
3041
include::./run-tests-locally.asciidoc[Run Tests Locally]
42+
43+
include::./api.asciidoc[API documentation]

‎elasticapm/__init__.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,8 @@
1717
except Exception as e:
1818
VERSION = 'unknown'
1919

20-
from elasticapm.base import * # noqa E403
21-
from elasticapm.conf import * # noqa E403
22-
from elasticapm.instrumentation.control import instrument # noqa E403
23-
from elasticapm.instrumentation.control import uninstrument # noqa E403
24-
from elasticapm.traces import * # noqa E403
20+
from elasticapm.base import Client
21+
from elasticapm.conf import setup_logging
22+
from elasticapm.instrumentation.control import instrument, uninstrument
23+
from elasticapm.traces import (set_transaction_data, set_transaction_name, tag,
24+
trace)

0 commit comments

Comments
 (0)