added API functions for setting transaction outcome

Author: beniwohli

docs/api.asciidoc

@@ -234,6 +234,44 @@ elasticapm.set_transaction_result('SUCCESS')
  * `override`: if `True` (the default), overrides any previously set result.
     If `False`, only sets the result if the result hasn't already been set.
 
+[float]
+[[api-set-transaction-success]]
+==== `elasticapm.set_transaction_success()`
+
+Marks the current transaction as successful.
+This should only be called at the end of a transaction after the outcome is determined.
+For supported frameworks, the transaction outcome is set automatically if it has not been set yet. 
+
+This value is used for error rate calculations.
+
+Example:
+
+[source,python]
+----
+import elasticapm
+
+elasticapm.set_transaction_success()
+----
+
+[float]
+[[api-set-transaction-failure]]
+==== `elasticapm.set_transaction_failure()`
+
+Marks the current transaction as failed.
+This should only be called at the end of a transaction after the outcome is determined.
+For supported frameworks, the transaction outcome is set automatically if it has not been set yet. 
+
+This value is used for error rate calculations.
+
+Example:
+
+[source,python]
+----
+import elasticapm
+
+elasticapm.set_transaction_success()
+----
+
 
 [float]
 [[api-get-transaction-id]]

elasticapm/__init__.py

@@ -40,8 +40,10 @@
     label,
     set_context,
     set_custom_context,
+    set_transaction_failure,
     set_transaction_name,
     set_transaction_result,
+    set_transaction_success,
     set_user_context,
     tag,
 )

elasticapm/traces.py

@@ -729,6 +729,13 @@ def tag(**tags):
 
 
 def set_transaction_name(name, override=True):
+    """
+    Sets the name of the transaction
+
+    :param name: the name of the transaction
+    :param override: if set to False, the name is only set if no name has been set before
+    :return: None
+    """
     transaction = execution_context.get_transaction()
     if not transaction:
         return
@@ -737,13 +744,52 @@ def set_transaction_name(name, override=True):
 
 
 def set_transaction_result(result, override=True):
+    """
+    Sets the result of the transaction. The result could be e.g. the HTTP status class (e.g "HTTP 5xx") for
+    HTTP requests, or "success"/"fail" for background tasks.
+
+    :param name: the name of the transaction
+    :param override: if set to False, the name is only set if no name has been set before
+    :return: None
+    """
+
     transaction = execution_context.get_transaction()
     if not transaction:
         return
     if transaction.result is None or override:
         transaction.result = result
 
 
+def set_transaction_success():
+    """
+    Marks this transaction as successful. This should only be done at the end of a transaction
+    when the outcome is determined.
+
+    This value is used for error rate calculations.
+
+    :return: None
+    """
+    transaction = execution_context.get_transaction()
+    if not transaction:
+        return
+    transaction.set_success()
+
+
+def set_transaction_failure():
+    """
+    Marks this transaction as failed. This should only be done at the end of a transaction
+    when the outcome is determined.
+
+    This value is used for error rate calculations.
+
+    :return: None
+    """
+    transaction = execution_context.get_transaction()
+    if not transaction:
+        return
+    transaction.set_failure()
+
+
 def get_transaction_id():
     """
     Returns the current transaction ID