|
| 1 | +--- |
| 2 | +mapped_pages: |
| 3 | + - https://www.elastic.co/guide/en/apm/agent/python/current/aiohttp-server-support.html |
| 4 | +--- |
| 5 | + |
| 6 | +# Aiohttp Server support [aiohttp-server-support] |
| 7 | + |
| 8 | +Getting Elastic APM set up for your Aiohttp Server project is easy, and there are various ways you can tweak it to fit to your needs. |
| 9 | + |
| 10 | + |
| 11 | +## Installation [aiohttp-server-installation] |
| 12 | + |
| 13 | +Install the Elastic APM agent using pip: |
| 14 | + |
| 15 | +```bash |
| 16 | +$ pip install elastic-apm |
| 17 | +``` |
| 18 | + |
| 19 | +or add `elastic-apm` to your project’s `requirements.txt` file. |
| 20 | + |
| 21 | + |
| 22 | +## Setup [aiohttp-server-setup] |
| 23 | + |
| 24 | +To set up the agent, you need to initialize it with appropriate settings. |
| 25 | + |
| 26 | +The settings are configured either via environment variables, the application’s settings, or as initialization arguments. |
| 27 | + |
| 28 | +You can find a list of all available settings in the [Configuration](/reference/configuration.md) page. |
| 29 | + |
| 30 | +To initialize the agent for your application using environment variables: |
| 31 | + |
| 32 | +```python |
| 33 | +from aiohttp import web |
| 34 | + |
| 35 | +from elasticapm.contrib.aiohttp import ElasticAPM |
| 36 | + |
| 37 | +app = web.Application() |
| 38 | + |
| 39 | +apm = ElasticAPM(app) |
| 40 | +``` |
| 41 | + |
| 42 | +To configure the agent using `ELASTIC_APM` in your application’s settings: |
| 43 | + |
| 44 | +```python |
| 45 | +from aiohttp import web |
| 46 | + |
| 47 | +from elasticapm.contrib.aiohttp import ElasticAPM |
| 48 | + |
| 49 | +app = web.Application() |
| 50 | + |
| 51 | +app['ELASTIC_APM'] = { |
| 52 | + 'SERVICE_NAME': '<SERVICE-NAME>', |
| 53 | + 'SECRET_TOKEN': '<SECRET-TOKEN>', |
| 54 | +} |
| 55 | +apm = ElasticAPM(app) |
| 56 | +``` |
| 57 | + |
| 58 | + |
| 59 | +## Usage [aiohttp-server-usage] |
| 60 | + |
| 61 | +Once you have configured the agent, it will automatically track transactions and capture uncaught exceptions within aiohttp. |
| 62 | + |
| 63 | +Capture an arbitrary exception by calling [`capture_exception`](/reference/api-reference.md#client-api-capture-exception): |
| 64 | + |
| 65 | +```python |
| 66 | +try: |
| 67 | + 1 / 0 |
| 68 | +except ZeroDivisionError: |
| 69 | + apm.client.capture_exception() |
| 70 | +``` |
| 71 | + |
| 72 | +Log a generic message with [`capture_message`](/reference/api-reference.md#client-api-capture-message): |
| 73 | + |
| 74 | +```python |
| 75 | +apm.client.capture_message('hello, world!') |
| 76 | +``` |
| 77 | + |
| 78 | + |
| 79 | +## Performance metrics [aiohttp-server-performance-metrics] |
| 80 | + |
| 81 | +If you’ve followed the instructions above, the agent has already installed our middleware. This will measure response times, as well as detailed performance data for all supported technologies. |
| 82 | + |
| 83 | +::::{note} |
| 84 | +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. |
| 85 | +:::: |
| 86 | + |
| 87 | + |
| 88 | + |
| 89 | +### Ignoring specific routes [aiohttp-server-ignoring-specific-views] |
| 90 | + |
| 91 | +You can use the [`TRANSACTIONS_IGNORE_PATTERNS`](/reference/configuration.md#config-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: |
| 92 | + |
| 93 | +```python |
| 94 | +app['ELASTIC_APM'] = { |
| 95 | + # ... |
| 96 | + 'TRANSACTIONS_IGNORE_PATTERNS': ['^OPTIONS ', '/api/'] |
| 97 | + # ... |
| 98 | +} |
| 99 | +``` |
| 100 | + |
| 101 | +This would ignore any requests using the `OPTIONS` method and any requests containing `/api/`. |
| 102 | + |
| 103 | + |
| 104 | +## Supported aiohttp and Python versions [supported-aiohttp-and-python-versions] |
| 105 | + |
| 106 | +A list of supported [aiohttp](/reference/supported-technologies.md#supported-aiohttp) and [Python](/reference/supported-technologies.md#supported-python) versions can be found on our [Supported Technologies](/reference/supported-technologies.md) page. |
| 107 | + |
| 108 | +::::{note} |
| 109 | +Elastic APM only supports `asyncio` when using Python 3.7+ |
| 110 | +:::: |
| 111 | + |
| 112 | + |
0 commit comments