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

.travis.yml

@@ -59,7 +59,7 @@ matrix:
   - stage: linters
     env: LINTER="flake8"
     python: 3.6
-    script: pip install -U flake8 && flake8 elasticapm
+    script: pip install -U flake8 flake8-per-file-ignores && flake8 elasticapm
 
   - stage: linters
     script: make docs

CHANGELOG.asciidoc

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

docs/api.asciidoc

@@ -0,0 +1,191 @@
+[[api]]
+== Public API
+
+The Elastic APM Python agent has several public APIs.
+Most of the public API functionality is not needed when using one of our <<framework-support, supported frameworks>>,
+but they allow customized usage.
+
+[float]
+[[client-api]]
+=== Client API
+
+The public Client API consists of several methods on the `Client` class.
+This API can be used to track exceptions and log messages,
+as well as to mark the beginning and end of transactions.
+
+[float]
+[[client-api-init]]
+==== Instantiation
+
+To create a `Client` instance, import it and call its constructor:
+
+[source,python]
+----
+from elasticapm import Client
+
+client = Client({'APP_NAME': 'example'}, **defaults)
+----
+
+ * `config`: A dictionary, with key/value configuration. For the possible configuration keys, see <<configuration, Configuration>>.
+ * `**defaults`: default values for configuration. These can be omitted in most cases, and take the least precedence.
+
+NOTE: framework integrations like <<django-support, Django>> and <<flask-support, Flask>>
+instantiate the client automatically. 
+
+[float]
+[[error-api]]
+==== Errors
+
+[float]
+[[client-api-capture-exception]]
+===== `Client.capture_exception()`
+
+Captures an exception object:
+
+[source,python]
+----
+try:
+    x = int("five")
+except ValueError:
+    client.capture_exception()
+----
+
+ * `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.
+ * `date`: A `datetime.datetime` object representing the occurrence time of the error. If left empty, it defaults to `datetime.datetime.utcnow()`.
+ * `context`: A dictionary with contextual information. This dictionary must follow the 
+    https://www.elastic.co/guide/en/apm/server/current/error-api.html#error-context-schema[Context] schema definition.
+ * `custom`: A dictionary of custom data you want to attach to the event.
+
+Returns the id of the error as a string.
+
+[float]
+[[client-api-capture-message]]
+===== `Client.capture_message()`
+
+Captures a message with optional added contextual data. Example:
+
+[source,python]
+----
+client.capture_message('Billing process succeeded.')
+----
+
+ * `message`: The message as a string.
+ * `param_message`: Alternatively, a parametrized message as a dictionary.
+    The dictionary contains two values: `message`, and `params`.
+    This allows the APM server to group messages together that share the same
+    parametrized message. Example:
++
+[source,python]
+----
+client.capture_message(param_message={
+    'message': 'Billing process for %s succeeded. Amount: %s',
+    'params': (customer.id, order.total_amount),
+})
+----
++
+ * `stack`: If set to `True` (the default), a stacktrace from the call site will be captured.
+ * `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, if `capture_message()` was called in an `except` block.
+ * `date`: A `datetime.datetime` object representing the occurrence time of the error.
+   If left empty, it defaults to `datetime.datetime.utcnow()`.
+ * `context`: A dictionary with contextual information. This dictionary must follow the 
+    https://www.elastic.co/guide/en/apm/server/current/error-api.html#error-context-schema[Context] schema definition.
+ * `custom`: A dictionary of custom data you want to attach to the event.
+
+Returns the id of the message as a string.
+
+NOTE: Either the `message` or the `param_message` argument is required.
+
+[float]
+[[transaction-api]]
+==== Transactions
+
+[float]
+[[client-api-begin-transaction]]
+===== `Client.begin_transaction()`
+Begin tracking a transaction.
+Should be called e.g. at the beginning of a request or when starting a background task. Example:
+
+[source,python]
+----
+client.begin_transaction('processors')
+----
+
+ * `transaction_type`: (*required*) A string describing the type of the transaction, e.g. `'request'` or `'celery'`.
+
+[float]
+[[client-api-end-transaction]]
+===== `Client.end_transaction()`
+End tracking the transaction.
+Should be called e.g. at the end of a request or when ending a background task. Example:
+
+[source,python]
+----
+client.end_transaction('myapp.billing_process', processor.status)
+----
+
+ * `name`: (*required*) A string describing the name of the transaction, e.g. `process_order`.
+   This is typically the name of the view/controller that handles the request, or the route name.
+ * `result`: (*required*) A string describing the result of the transaction.
+   This is typically the HTTP status code, or e.g. `'success'` for a background task.
+
+
+[float]
+[[api-other]]
+=== Other APIs
+
+[float]
+[[api-elasticapm-instrument]]
+==== `elasticapm.instrument()`
+
+Instruments libraries automatically.
+This includes a wide range of standard library and 3rd party modules.
+A list of instrumented modules can be found in `elasticapm.intrumentation.register`.
+This function should be called as early as possibly in the startup of your application.
+For <<framework-support, supported frameworks>>, this is called automatically. Example:
+
+[source,python]
+----
+import elasticapm
+
+elasticapm.instrument()
+----
+
+[float]
+[[api-set-transaction-name]]
+==== `elasticapm.set_transaction_name()`
+
+Override the name of the current transaction.
+For supported frameworks, the transaction name is determined automatically,
+and can be overridden using this function. Example:
+
+[source,python]
+----
+import elasticapm
+
+elasticapm.set_transaction_name('myapp.billing_process')
+----
+
+ * `name`: (*required*) A string describing name of the transaction
+
+[float]
+[[api-set-transaction-data]]
+==== `elasticapm.set_transaction_data()`
+
+Attach custom contextual data to current transaction.
+Supported frameworks will automatically attach information about the HTTP request and the logged in user.
+You can attach further data using this function. Example:
+
+[source,python]
+----
+import elasticapm
+
+elasticapm.set_transaction_data({'billing_amount': product.price * item_count})
+----
+
+
+ * `data`: (*required*) A dictionary with the data to be attached. This should be a flat key/value `dict` object.
+ * `_key`: The key to use for this `dict` object. Defaults to `custom`.
++
+NOTE: This should only be overridden by framework integrations.

docs/configuration.asciidoc

@@ -14,7 +14,7 @@ To configure Django, add an `ELASTIC_APM` dictionary to your `settings.py`:
 ----
 ELASTIC_APM = {
     'APP_NAME': 'my-app',
-    'SECRET_TOKEN': 'changeme,
+    'SECRET_TOKEN': 'changeme',
 }
 ----
 
@@ -28,7 +28,7 @@ To configure Flask, add an `ELASTIC_APM` dictonary to your `app.config`:
 ----
 app.config['ELASTIC_APM'] = {
     'APP_NAME': 'my-app',
-    'SECRET_TOKEN': 'changeme,
+    'SECRET_TOKEN': 'changeme',
 }
 
 apm = ElasticAPM(app)

docs/django.asciidoc

@@ -56,6 +56,8 @@ ELASTIC_APM_SECRET_TOKEN=<SECRET-TOKEN>
 
 You now have basic error logging set up, and everything resulting in a 500 HTTP status code will be reported to the APM Server.
 
+You can find a list of all available settings in the <<configuration, Configuration>> page.
+
 [float]
 [[django-performance-metrics]]
 === Performance Metrics

docs/index.asciidoc

@@ -1,5 +1,6 @@
 = APM Python Agent Reference (Experimental)
 
+[[getting-started]]
 == Getting started
 
 Welcome to the APM Python agent docs.
@@ -17,6 +18,16 @@ ifdef::env-github[]
 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]
 endif::[]
 
+[[framework-support]]
+The Elastic APM Python Agent comes with support for the following frameworks:
+
+ * <<django-support,Django>> 1.8 - 2.0
+ * <<flask-support,Flask>> 0.10+
+
+For other frameworks and custom Python code, the agent exposes a set of <<api,APIs>> for integration.
+
+NOTE: The Elastic APM Python agent does currently not support asynchronous frameworks like Twisted or Tornado.
+
 include::./configuration.asciidoc[Configuration]
 
 include::./django.asciidoc[Django support]
@@ -28,3 +39,5 @@ include::./flask.asciidoc[Flask support]
 include::./custom-instrumentation.asciidoc[Custom Instrumentation]
 include::./sanitizing-data.asciidoc[Sanitizing Data]
 include::./run-tests-locally.asciidoc[Run Tests Locally]
+
+include::./api.asciidoc[API documentation]

elasticapm/__init__.py

@@ -17,8 +17,8 @@
 except Exception as e:
     VERSION = 'unknown'
 
-from elasticapm.base import *  # noqa E403
-from elasticapm.conf import *  # noqa E403
-from elasticapm.instrumentation.control import instrument  # noqa E403
-from elasticapm.instrumentation.control import uninstrument  # noqa E403
-from elasticapm.traces import *  # noqa E403
+from elasticapm.base import Client
+from elasticapm.conf import setup_logging
+from elasticapm.instrumentation.control import instrument, uninstrument
+from elasticapm.traces import (set_transaction_data, set_transaction_name, tag,
+                               trace)