Skip to content

Commit 98a702d

Browse files
majorgreysmajorgreys
committed
Add documentation for trace search
1 parent e8793da commit 98a702d

File tree

4 files changed

+137
-56
lines changed

4 files changed

+137
-56
lines changed

‎ddtrace/contrib/requests/connection.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ def _wrap_send(func, instance, args, kwargs):
7373
span.service = _extract_service_name(instance, span, hostname=hostname)
7474

7575
# Configure trace search sample rate
76-
# DEV: Not enabled by default when global analytics config is enabled
76+
# DEV: analytics enabled on per-session basis
7777
cfg = config.get_from(instance)
7878
analytics_enabled = cfg.get('analytics_enabled')
7979
if analytics_enabled:

‎docs/advanced_usage.rst‎

Lines changed: 135 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -32,27 +32,27 @@ Some web framework integrations support distributed tracing out of the box.
3232
Supported web frameworks:
3333

3434

35-
+-------------------+-----------------+
36-
| Framework/Library | Enabled |
37-
+===================+=================+
38-
| :ref:`aiohttp` | True |
39-
+-------------------+-----------------+
40-
| :ref:`bottle` | True |
41-
+-------------------+-----------------+
42-
| :ref:`django` | True |
43-
+-------------------+-----------------+
44-
| :ref:`falcon` | True |
45-
+-------------------+-----------------+
46-
| :ref:`flask` | True |
47-
+-------------------+-----------------+
48-
| :ref:`pylons` | True |
49-
+-------------------+-----------------+
50-
| :ref:`pyramid` | True |
51-
+-------------------+-----------------+
52-
| :ref:`requests` | True |
53-
+-------------------+-----------------+
54-
| :ref:`tornado` | True |
55-
+-------------------+-----------------+
35+
+-------------------+---------+
36+
| Framework/Library | Enabled |
37+
+===================+=========+
38+
| :ref:`aiohttp` | True |
39+
+-------------------+---------+
40+
| :ref:`bottle` | True |
41+
+-------------------+---------+
42+
| :ref:`django` | True |
43+
+-------------------+---------+
44+
| :ref:`falcon` | True |
45+
+-------------------+---------+
46+
| :ref:`flask` | True |
47+
+-------------------+---------+
48+
| :ref:`pylons` | True |
49+
+-------------------+---------+
50+
| :ref:`pyramid` | True |
51+
+-------------------+---------+
52+
| :ref:`requests` | True |
53+
+-------------------+---------+
54+
| :ref:`tornado` | True |
55+
+-------------------+---------+
5656

5757

5858
HTTP Client
@@ -177,6 +177,101 @@ The ``RateSampler`` randomly samples a percentage of traces::
177177
tracer.sampler = RateSampler(sample_rate)
178178

179179

180+
Trace Search & Analytics
181+
------------------------
182+
183+
Use `Trace Search & Analytics <https://docs.datadoghq.com/tracing/visualization/search/>`_ to filter application performance metrics and APM Events by user-defined tags. An APM event is generated every time a trace is generated.
184+
185+
Enabling APM events for all web frameworks can be accomplished by setting the environment variable ``DD_ANALYTICS_ENABLED=true``:
186+
187+
* :ref:`aiohttp`
188+
* :ref:`bottle`
189+
* :ref:`django`
190+
* :ref:`falcon`
191+
* :ref:`flask`
192+
* :ref:`molten`
193+
* :ref:`pylons`
194+
* :ref:`pyramid`
195+
* :ref:`requests`
196+
* :ref:`tornado`
197+
198+
199+
For most libraries, APM events can be enabled with the environment variable ``DD_{INTEGRATION}_ANALYTICS_ENABLED=true``:
200+
201+
+----------------------+----------------------------------------+
202+
| Library | Environment Variable |
203+
+======================+========================================+
204+
| :ref:`aiobotocore` | ``DD_AIOBOTOCORE_ANALYTICS_ENABLED`` |
205+
+----------------------+----------------------------------------+
206+
| :ref:`aiopg` | ``DD_AIOPG_ANALYTICS_ENABLED`` |
207+
+----------------------+----------------------------------------+
208+
| :ref:`boto` | ``DD_BOTO_ANALYTICS_ENABLED`` |
209+
+----------------------+----------------------------------------+
210+
| :ref:`botocore` | ``DD_BOTOCORE_ANALYTICS_ENABLED`` |
211+
+----------------------+----------------------------------------+
212+
| :ref:`bottle` | ``DD_BOTTLE_ANALYTICS_ENABLED`` |
213+
+----------------------+----------------------------------------+
214+
| :ref:`cassandra` | ``DD_CASSANDRA_ANALYTICS_ENABLED`` |
215+
+----------------------+----------------------------------------+
216+
| :ref:`elasticsearch` | ``DD_ELASTICSEARCH_ANALYTICS_ENABLED`` |
217+
+----------------------+----------------------------------------+
218+
| :ref:`falcon` | ``DD_FALCON_ANALYTICS_ENABLED`` |
219+
+----------------------+----------------------------------------+
220+
| :ref:`flask` | ``DD_FLASK_ANALYTICS_ENABLED`` |
221+
+----------------------+----------------------------------------+
222+
| :ref:`flask_cache` | ``DD_FLASK_CACHE_ANALYTICS_ENABLED`` |
223+
+----------------------+----------------------------------------+
224+
| :ref:`grpc` | ``DD_GRPC_ANALYTICS_ENABLED`` |
225+
+----------------------+----------------------------------------+
226+
| :ref:`httplib` | ``DD_HTTPLIB_ANALYTICS_ENABLED`` |
227+
+----------------------+----------------------------------------+
228+
| :ref:`kombu` | ``DD_KOMBU_ANALYTICS_ENABLED`` |
229+
+----------------------+----------------------------------------+
230+
| :ref:`molten` | ``DD_MOLTEN_ANALYTICS_ENABLED`` |
231+
+----------------------+----------------------------------------+
232+
| :ref:`pylibmc` | ``DD_PYLIBMC_ANALYTICS_ENABLED`` |
233+
+----------------------+----------------------------------------+
234+
| :ref:`pylons` | ``DD_PYLONS_ANALYTICS_ENABLED`` |
235+
+----------------------+----------------------------------------+
236+
| :ref:`pymemcache` | ``DD_PYMEMCACHE_ANALYTICS_ENABLED`` |
237+
+----------------------+----------------------------------------+
238+
| :ref:`pymongo` | ``DD_PYMONGO_ANALYTICS_ENABLED`` |
239+
+----------------------+----------------------------------------+
240+
| :ref:`redis` | ``DD_REDIS_ANALYTICS_ENABLED`` |
241+
+----------------------+----------------------------------------+
242+
| :ref:`rediscluster` | ``DD_REDISCLUSTER_ANALYTICS_ENABLED`` |
243+
+----------------------+----------------------------------------+
244+
| :ref:`sqlalchemy` | ``DD_SQLALCHEMY_ANALYTICS_ENABLED`` |
245+
+----------------------+----------------------------------------+
246+
| :ref:`vertica` | ``DD_VERTICA_ANALYTICS_ENABLED`` |
247+
+----------------------+----------------------------------------+
248+
249+
For datastore libraries that extend another, use the setting for the underlying library:
250+
251+
+------------------------+----------------------------------+
252+
| Library | Environment Variable |
253+
+========================+==================================+
254+
| :ref:`mongoengine` | ``DD_PYMONGO_ANALYTICS_ENABLED`` |
255+
+------------------------+----------------------------------+
256+
| :ref:`mysql-connector` | ``DD_DBAPI2_ANALYTICS_ENABLED`` |
257+
+------------------------+----------------------------------+
258+
| :ref:`mysqldb` | ``DD_DBAPI2_ANALYTICS_ENABLED`` |
259+
+------------------------+----------------------------------+
260+
| :ref:`psycopg2` | ``DD_DBAPI2_ANALYTICS_ENABLED`` |
261+
+------------------------+----------------------------------+
262+
| :ref:`pymysql` | ``DD_DBAPI2_ANALYTICS_ENABLED`` |
263+
+------------------------+----------------------------------+
264+
| :ref:`sqllite` | ``DD_DBAPI2_ANALYTICS_ENABLED`` |
265+
+------------------------+----------------------------------+
266+
267+
Where environment variables are not used for configuring the tracer, the instructions for configuring trace analytics is provided in the library documentation:
268+
269+
* :ref:`aiohttp`
270+
* :ref:`django`
271+
* :ref:`pyramid`
272+
* :ref:`requests`
273+
* :ref:`tornado`
274+
180275
Resolving deprecation warnings
181276
------------------------------
182277
Before upgrading, it’s a good idea to resolve any deprecation warnings raised by your project.
@@ -312,25 +407,25 @@ The Datadog opentracer can be configured via the ``config`` dictionary
312407
parameter to the tracer which accepts the following described fields. See below
313408
for usage.
314409

315-
+---------------------+---------------------------------------------------------+---------------+
316-
| Configuration Key | Description | Default Value |
317-
+=====================+=========================================================+===============+
318-
| `enabled` | enable or disable the tracer | `True` |
319-
+---------------------+---------------------------------------------------------+---------------+
320-
| `debug` | enable debug logging | `False` |
321-
+---------------------+---------------------------------------------------------+---------------+
322-
| `agent_hostname` | hostname of the Datadog agent to use | `localhost` |
323-
+---------------------+---------------------------------------------------------+---------------+
324-
| `agent_port` | port the Datadog agent is listening on | `8126` |
325-
+---------------------+---------------------------------------------------------+---------------+
326-
| `global_tags` | tags that will be applied to each span | `{}` |
327-
+---------------------+---------------------------------------------------------+---------------+
328-
| `sampler` | see `Sampling`_ | `AllSampler` |
329-
+---------------------+---------------------------------------------------------+---------------+
330-
| `priority_sampling` | see `Priority Sampling`_ | `True` |
331-
+---------------------+---------------------------------------------------------+---------------+
332-
| `settings` | see `Advanced Usage`_ | `{}` |
333-
+---------------------+---------------------------------------------------------+---------------+
410+
+---------------------+----------------------------------------+---------------+
411+
| Configuration Key | Description | Default Value |
412+
+=====================+========================================+===============+
413+
| `enabled` | enable or disable the tracer | `True` |
414+
+---------------------+----------------------------------------+---------------+
415+
| `debug` | enable debug logging | `False` |
416+
+---------------------+----------------------------------------+---------------+
417+
| `agent_hostname` | hostname of the Datadog agent to use | `localhost` |
418+
+---------------------+----------------------------------------+---------------+
419+
| `agent_port` | port the Datadog agent is listening on | `8126` |
420+
+---------------------+----------------------------------------+---------------+
421+
| `global_tags` | tags that will be applied to each span | `{}` |
422+
+---------------------+----------------------------------------+---------------+
423+
| `sampler` | see `Sampling`_ | `AllSampler` |
424+
+---------------------+----------------------------------------+---------------+
425+
| `priority_sampling` | see `Priority Sampling`_ | `True` |
426+
+---------------------+----------------------------------------+---------------+
427+
| `settings` | see `Advanced Usage`_ | `{}` |
428+
+---------------------+----------------------------------------+---------------+
334429

335430

336431
Usage

‎docs/db_integrations.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ mysql-connector
7676

7777
.. _mysqlclient:
7878
.. _MySQL-python:
79+
.. _mysqldb:
7980

8081
mysqlclient/MySQL-python
8182
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

‎tests/contrib/psycopg/test_psycopg.py‎

Lines changed: 0 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,6 @@
99
from unittest import skipIf
1010

1111
# project
12-
from ddtrace.constants import ANALYTICS_SAMPLE_RATE_KEY
1312
from ddtrace.contrib.psycopg import connection_factory
1413
from ddtrace.contrib.psycopg.patch import patch, unpatch, PSYCOPG2_VERSION
1514
from ddtrace import Pin
@@ -105,7 +104,6 @@ def assert_conn_is_traced(self, db, service):
105104
assert start <= root.start <= end
106105
assert root.duration <= end - start
107106
# confirm analytics disabled by default
108-
self.assertIsNone(root.get_metric(ANALYTICS_SAMPLE_RATE_KEY))
109107
self.reset()
110108

111109
# run a query with an error and ensure all is well
@@ -287,19 +285,6 @@ def test_composed_query(self):
287285
dict(name='postgres.query', resource=query.as_string(db)),
288286
)
289287

290-
def test_analytics_with_rate(self):
291-
with self.override_config(
292-
'dbapi2',
293-
dict(analytics_enabled=True, analytics_sample_rate=0.5)
294-
):
295-
conn = self._get_conn()
296-
conn.cursor().execute("""select 'blah'""")
297-
298-
spans = self.get_spans()
299-
self.assertEqual(len(spans), 1)
300-
span = spans[0]
301-
self.assertEqual(span.get_metric(ANALYTICS_SAMPLE_RATE_KEY), 0.5, span)
302-
303288

304289
def test_backwards_compatibilty_v3():
305290
tracer = DummyTracer()

0 commit comments

Comments
 (0)