Feature/git 521 sanic apm contrib

.ci/.jenkins_exclude.yml

@@ -187,7 +187,7 @@ exclude:
   - PYTHON_VERSION: python-3.10-rc
     FRAMEWORK: zerorpc-0.4
   # gevent
-  - PYTHON_VERSION: python-3.10-rc  # causes issues with PosixPath.__enter__, unsure why
+  - PYTHON_VERSION: python-3.10-rc # causes issues with PosixPath.__enter__, unsure why
     FRAMEWORK: gevent-newest
   # aiohttp client, only supported in Python 3.7+
   - PYTHON_VERSION: pypy-3
@@ -230,9 +230,19 @@ exclude:
     FRAMEWORK: asyncpg-newest
   - PYTHON_VERSION: python-3.6
     FRAMEWORK: asyncpg-newest
-  - PYTHON_VERSION: python-3.10-rc  # https://github.com/MagicStack/asyncpg/issues/699
+  - PYTHON_VERSION: python-3.10-rc # https://github.com/MagicStack/asyncpg/issues/699
     FRAMEWORK: asyncpg-newest
+  # sanic
   - PYTHON_VERSION: pypy-3
+    FRAMEWORK: sanic-newest
+  - PYTHON_VERSION: pypy-3
+    FRAMEWORK: sanic-20.12
+  - PYTHON_VERSION: python-3.6
+    FRAMEWORK: sanic-20.12
+  - PYTHON_VERSION: python-3.6
+    FRAMEWORK: sanic-newest
+  - PYTHON_VERSION: pypy-3
+  # aioredis
     FRAMEWORK: aioredis-newest
   - PYTHON_VERSION: python-3.6
     FRAMEWORK: aioredis-newest

.ci/.jenkins_framework.yml

@@ -48,4 +48,5 @@ FRAMEWORK:
   - httpx-newest
   - httplib2-newest
   - prometheus_client-newest
+  - sanic-newest
   - aiomysql-newest

.ci/.jenkins_framework_full.yml

@@ -79,3 +79,5 @@ FRAMEWORK:
   - httpx-0.14
   - httpx-newest
   - httplib2-newest
+  - sanic-20.12
+  - sanic-newest

CHANGELOG.asciidoc

@@ -29,6 +29,18 @@ endif::[]
 //[float]
 //===== Bug fixes
 
+=== Unreleased
+
+// Unreleased changes go here
+// When the next release happens, nest these changes under the "Python Agent version 6.x" heading
+[float]
+===== Features
+
+* Add support for Sanic framework {pull}1390[#1390]
+
+//[float]
+//===== Bug fixes
+
 [[release-notes-6.x]]
 === Python Agent version 6.x
 

conftest.py

@@ -63,6 +63,7 @@
     "django": "tests.contrib.django.fixtures",
     "flask": "tests.contrib.flask.fixtures",
     "aiohttp": "aiohttp.pytest_plugin",
+    "sanic": "tests.contrib.sanic.fixtures",
 }.items():
     try:
         importlib.import_module(module)

docs/sanic.asciidoc

@@ -0,0 +1,179 @@
+[[sanic-support]]
+=== Sanic Support
+
+Incorporating Elastic APM into your Sanic project only requires a few easy
+steps.
+
+[float]
+[[sanic-installation]]
+==== Installation
+
+Install the Elastic APM agent using pip:
+
+[source,bash]
+----
+$ pip install elastic-apm
+----
+
+or add `elastic-apm` to your project's `requirements.txt` file.
+
+
+[float]
+[[sanic-setup]]
+==== Setup
+
+To set up the agent, you need to initialize it with appropriate settings.
+
+The settings are configured either via environment variables, or as
+initialization arguments.
+
+You can find a list of all available settings in the
+<<configuration, Configuration>> page.
+
+To initialize the agent for your application using environment variables:
+
+[source,python]
+----
+from sanic import Sanic
+from elasticapm.contrib.sanic import ElasticAPM
+
+app = Sanic(name="elastic-apm-sample")
+apm = ElasticAPM(app=app)
+----
+
+To configure the agent using initialization arguments and Sanic's Configuration infrastructure:
+
+[source,python]
+----
+# Create a file named external_config.py in your application
+# If you want this module based configuration to be used for APM, prefix them with ELASTIC_APM_
+ELASTIC_APM_SERVER_URL = "https://serverurl.apm.com:443"
+ELASTIC_APM_SECRET_TOKEN = "sometoken"
+----
+
+[source,python]
+----
+from sanic import Sanic
+from elasticapm.contrib.sanic import ElasticAPM
+
+app = Sanic(name="elastic-apm-sample")
+app.config.update_config("path/to/external_config.py")
+apm = ElasticAPM(app=app)
+----
+
+[float]
+[[sanic-usage]]
+==== Usage
+
+Once you have configured the agent, it will automatically track transactions
+and capture uncaught exceptions within sanic.
+
+Capture an arbitrary exception by calling
+<<client-api-capture-exception,`capture_exception`>>:
+
+[source,python]
+----
+from sanic import Sanic
+from elasticapm.contrib.sanic import ElasticAPM
+
+app = Sanic(name="elastic-apm-sample")
+apm = ElasticAPM(app=app)
+
+try:
+    1 / 0
+except ZeroDivisionError:
+    apm.capture_exception()
+----
+
+Log a generic message with <<client-api-capture-message,`capture_message`>>:
+
+[source,python]
+----
+from sanic import Sanic
+from elasticapm.contrib.sanic import ElasticAPM
+
+app = Sanic(name="elastic-apm-sample")
+apm = ElasticAPM(app=app)
+
+apm.capture_message('hello, world!')
+----
+
+[float]
+[[sanic-performance-metrics]]
+==== Performance metrics
+
+If you've followed the instructions above, the agent has installed our
+instrumentation middleware which will process all requests through your app.
+This will measure response times, as well as detailed performance data for
+all supported technologies.
+
+NOTE: Due to the fact that `asyncio` drivers are usually separate from their
+synchronous counterparts, specific instrumentation is needed for all drivers.
+The support for asynchronous drivers is currently quite limited.
+
+[float]
+[[sanic-ignoring-specific-views]]
+===== Ignoring specific routes
+
+You can use the
+<<config-transactions-ignore-patterns,`TRANSACTIONS_IGNORE_PATTERNS`>>
+configuration option to ignore specific routes. The list given should be a
+list of regular expressions which are matched against the transaction name:
+
+[source,python]
+----
+from sanic import Sanic
+from elasticapm.contrib.sanic import ElasticAPM
+
+app = Sanic(name="elastic-apm-sample")
+apm = ElasticAPM(app=app, config={
+    'TRANSACTIONS_IGNORE_PATTERNS': ['^GET /secret', '/extra_secret'],
+})
+----
+
+This would ignore any requests using the `GET /secret` route
+and any requests containing `/extra_secret`.
+
+[float]
+[[extended-sanic-usage]]
+==== Extended Sanic APM Client Usage
+
+Sanic's contributed APM client also provides a few extendable way to configure selective behaviors to enhance the
+information collected as part of the transactions being tracked by the APM.
+
+In order to enable this behavior, the APM Client middleware provides a few callback functions that you can leverage
+in order to simplify the process of generating additional contexts into the traces being collected.
+[cols="1,1,1,1"]
+|===
+| Callback Name | Callback Invocation Format | Expected Return Format | Is Async
+
+| transaction_name_callback
+| transaction_name_callback(request)
+| string
+| false
+
+| user_context_callback
+| user_context_callback(request)
+| (username_string, user_email_string, userid_string)
+| true
+
+| custom_context_callback
+| custom_context_callback(request) or custom_context_callback(response)
+| dict(str=str)
+| true
+
+| label_info_callback
+| label_info_callback()
+| dict(str=str)
+| true
+|===
+
+[float]
+[[supported-stanic-and-python-versions]]
+==== Supported Sanic and Python versions
+
+A list of supported <<supported-sanic,Sanic>> and
+<<supported-python,Python>> versions can be found on our
+<<supported-technologies,Supported Technologies>> page.
+
+NOTE: Elastic APM only supports `asyncio` when using Python 3.7+

docs/set-up.asciidoc

@@ -8,6 +8,7 @@ To get you off the ground, we’ve prepared guides for setting up the Agent with
  * <<aiohttp-server-support,aiohttp>>
  * <<tornado-support,Tornado>>
  * <<starlette-support,Starlette/FastAPI>>
+ * <<sanic-support,Sanic>>
  * <<lambda-support,AWS Lambda>>
 
 For custom instrumentation, see <<instrumenting-custom-code, Instrumenting Custom Code>>.
@@ -22,4 +23,6 @@ include::./tornado.asciidoc[]
 
 include::./starlette.asciidoc[]
 
-include::./serverless.asciidoc[]
+include::./sanic.asciidoc[]
+
+include::./serverless.asciidoc[]

docs/supported-technologies.asciidoc

@@ -9,6 +9,7 @@ The Elastic APM Python Agent comes with support for the following frameworks:
  * <<supported-aiohttp,Aiohttp Server>>
  * <<supported-tornado,Tornado>>
  * <<supported-starlette,Starlette/FastAPI>>
+ * <<supported-sanic,Sanic>>
 
 For other frameworks and custom Python code, the agent exposes a set of <<api,APIs>> for integration.
 
@@ -71,6 +72,15 @@ We support these tornado versions:
  * 6.0+
 
 
+[float]
+[[supported-sanic]]
+=== Sanic
+
+We support these sanic versions:
+
+ * 20.12.2+
+
+
 [float]
 [[supported-starlette]]
 === Starlette/FastAPI