Remove log shipping from Flask docs, start deprecation (#1918)

Author: basepi

CHANGELOG.asciidoc

@@ -36,6 +36,7 @@ endif::[]
 [float]
 ===== Features
 
+* Add Python 3.12 support
 * Collect the `configured_hostname` and `detected_hostname` separately, and switch to FQDN for the `detected_hostname`. {pull}1891[#1891]
 * Improve postgres dollar-quote detection to be much faster {pull}1905[#1905]
 
@@ -45,7 +46,13 @@ endif::[]
 * Fix url argument fetching in aiohttp_client instrumentation {pull}1890[#1890]
 * Fix a bug in the AWS Lambda instrumentation when `event["headers"] is None` {pull}1907[#1907]
 * Fix a bug in AWS Lambda where metadata could be incomplete, causing validation errors with the APM Server {pull}1914[#1914]
-* Fix a bug in AWS Lambda where sending the partial transaction would be recorded as an extra span {pull}1914[#1914]
+* Fix a bug in AWS Lambda where sending the partial transaction would be
+recorded as an extra span {pull}1914[#1914]
+
+[float]
+===== Pending Deprecations
+
+* The log shipping feature in the Flask instrumentation will be removed in version 7.0.0 of the agent.
 
 
 

docs/flask.asciidoc

@@ -138,75 +138,27 @@ apm.capture_message('hello, world!')
 [[flask-logging]]
 ==== Shipping Logs to Elasticsearch
 
-Enable automatic log shipping by passing `logging=LEVEL` to the ElasticAPM
-constructor. The agent will then ship all log messages with the given
-log-level or higher, from Python's built-in `logging` module to
-Elasticsearch. `LEVEL` must be one of the levels defined in the
-https://docs.python.org/3/library/logging.html#logging-levels[`logging`]
-module.
+This feature has been deprecated and will be removed in a future version.
 
-[source,python]
-----
-import logging
+Please see our <<logs,Logging>> documentation for other supported ways to ship
+logs to Elasticsearch.
 
-from elasticapm.contrib.flask import ElasticAPM
-
-apm = ElasticAPM(app, logging=logging.ERROR)
-----
-
-To ship all log messages independent of log levels to Elastic APM, pass
-`logging=True` to the constructor:
+Note that you can always send exceptions and messages to the APM Server with
+<<client-api-capture-exception,`capture_exception`>> and and
+<<client-api-capture-message,`capture_message`>>.
 
 [source,python]
 ----
-from elasticapm.contrib.flask import ElasticAPM
-
-apm = ElasticAPM(app, logging=True)
-----
-
-NOTE: using `logging=True` can lead to high number of logs being sent to Elastic APM.
-We recommend to always limit logging with Elastic APM to a high level (`WARNING` or `ERROR`).
-For shipping of less urgent logs, we recommend to use {filebeat-ref}[filebeat].
-
-For fine-grained control, you can initialize a logging handler and add it,
-just as you would with any other handler.
+from elasticapm import get_client
 
-For information on how to increase the log verbosity from the APM agent, see
-<<agent-logging,troubleshooting agent logging>>.
-
-[source,python]
-----
-from flask import Flask
-
-from elasticapm.contrib.flask import ElasticAPM
-from elasticapm.handlers.logging import LoggingHandler
-
-app = Flask(__name__)
-
-apm = ElasticAPM(app)
-
-if __name__ == '__main__':
-    # Create a logging handler and attach it.
-    handler = LoggingHandler(client=apm.client)
-    handler.setLevel(logging.WARN)
-    app.logger.addHandler(handler)
-----
-
-You can also capture exceptions and send them explicitly:
-
-[source,python]
-----
 @app.route('/')
 def bar():
     try:
         1 / 0
     except ZeroDivisionError:
-        app.logger.error( 'I cannot math', exc_info=True)
+        get_client().capture_exception()
 ----
 
-NOTE: `exc_info=True` adds the exception info to the data that gets sent to the APM Server.
-Without it, only the message is sent.
-
 [float]
 [[flask-extra-data]]
 ===== Extra data

elasticapm/contrib/flask/__init__.py

@@ -32,6 +32,7 @@
 from __future__ import absolute_import
 
 import logging
+import warnings
 
 import flask
 from flask import request, signals
@@ -68,10 +69,6 @@ class ElasticAPM(object):
 
     >>> elasticapm = ElasticAPM(app, client=client)
 
-    Automatically configure logging::
-
-    >>> elasticapm = ElasticAPM(app, logging=True)
-
     Capture an exception::
 
     >>> try:
@@ -87,6 +84,11 @@ class ElasticAPM(object):
     def __init__(self, app=None, client=None, client_cls=Client, logging=False, **defaults) -> None:
         self.app = app
         self.logging = logging
+        if self.logging:
+            warnings.warn(
+                "Flask log shipping is deprecated. See the Flask docs for more info and alternatives.",
+                PendingDeprecationWarning,
+            )
         self.client = client or get_client()
         self.client_cls = client_cls