|
| 1 | +r""" |
| 2 | +The Tornado integration traces all ``RequestHandler`` defined in a Tornado web application. |
| 3 | +Auto instrumentation is available using the ``patch`` function that **must be called before** |
| 4 | +importing the tornado library. |
| 5 | +
|
| 6 | +The following is an example:: |
| 7 | +
|
| 8 | + # patch before importing tornado and concurrent.futures |
| 9 | + from ddtrace.trace import tracer, patch |
| 10 | + patch(tornado=True) |
| 11 | +
|
| 12 | + import tornado.web |
| 13 | + import tornado.gen |
| 14 | + import tornado.ioloop |
| 15 | +
|
| 16 | + # create your handlers |
| 17 | + class MainHandler(tornado.web.RequestHandler): |
| 18 | + @tornado.gen.coroutine |
| 19 | + def get(self): |
| 20 | + self.write("Hello, world") |
| 21 | +
|
| 22 | + # create your application |
| 23 | + app = tornado.web.Application([ |
| 24 | + (r'/', MainHandler), |
| 25 | + ]) |
| 26 | +
|
| 27 | + # and run it as usual |
| 28 | + app.listen(8888) |
| 29 | + tornado.ioloop.IOLoop.current().start() |
| 30 | +
|
| 31 | +When any type of ``RequestHandler`` is hit, a request root span is automatically created. If |
| 32 | +you want to trace more parts of your application, you can use the ``wrap()`` decorator and |
| 33 | +the ``trace()`` method as usual:: |
| 34 | +
|
| 35 | + class MainHandler(tornado.web.RequestHandler): |
| 36 | + @tornado.gen.coroutine |
| 37 | + def get(self): |
| 38 | + yield self.notify() |
| 39 | + yield self.blocking_method() |
| 40 | + with tracer.trace('tornado.before_write') as span: |
| 41 | + # trace more work in the handler |
| 42 | +
|
| 43 | + @tracer.wrap('tornado.executor_handler') |
| 44 | + @tornado.concurrent.run_on_executor |
| 45 | + def blocking_method(self): |
| 46 | + # do something expensive |
| 47 | +
|
| 48 | + @tracer.wrap('tornado.notify', service='tornado-notification') |
| 49 | + @tornado.gen.coroutine |
| 50 | + def notify(self): |
| 51 | + # do something |
| 52 | +
|
| 53 | +If you are overriding the ``on_finish`` or ``log_exception`` methods on a |
| 54 | +``RequestHandler``, you will need to call the super method to ensure the |
| 55 | +tracer's patched methods are called:: |
| 56 | +
|
| 57 | + class MainHandler(tornado.web.RequestHandler): |
| 58 | + @tornado.gen.coroutine |
| 59 | + def get(self): |
| 60 | + self.write("Hello, world") |
| 61 | +
|
| 62 | + def on_finish(self): |
| 63 | + super(MainHandler, self).on_finish() |
| 64 | + # do other clean-up |
| 65 | +
|
| 66 | + def log_exception(self, typ, value, tb): |
| 67 | + super(MainHandler, self).log_exception(typ, value, tb) |
| 68 | + # do other logging |
| 69 | +
|
| 70 | +Tornado settings can be used to change some tracing configuration, like:: |
| 71 | +
|
| 72 | + settings = { |
| 73 | + 'datadog_trace': { |
| 74 | + 'default_service': 'my-tornado-app', |
| 75 | + 'tags': {'env': 'production'}, |
| 76 | + 'distributed_tracing': False, |
| 77 | + }, |
| 78 | + } |
| 79 | +
|
| 80 | + app = tornado.web.Application([ |
| 81 | + (r'/', MainHandler), |
| 82 | + ], **settings) |
| 83 | +
|
| 84 | +The available settings are: |
| 85 | +
|
| 86 | +* ``default_service`` (default: `tornado-web`): set the service name used by the tracer. Usually |
| 87 | + this configuration must be updated with a meaningful name. Can also be configured via the |
| 88 | + ``DD_SERVICE`` environment variable. |
| 89 | +* ``tags`` (default: `{}`): set global tags that should be applied to all spans. |
| 90 | +* ``enabled`` (default: `True`): define if the tracer is enabled or not. If set to `false`, the |
| 91 | + code is still instrumented but no spans are sent to the APM agent. |
| 92 | +* ``distributed_tracing`` (default: `None`): enable distributed tracing if this is called |
| 93 | + remotely from an instrumented application. Overrides the integration config which is configured via the |
| 94 | + ``DD_TORNADO_DISTRIBUTED_TRACING`` environment variable. |
| 95 | + We suggest to enable it only for internal services where headers are under your control. |
| 96 | +* ``agent_hostname`` (default: `localhost`): define the hostname of the APM agent. |
| 97 | +* ``agent_port`` (default: `8126`): define the port of the APM agent. |
| 98 | +* ``settings`` (default: ``{}``): Tracer extra settings used to change, for instance, the filtering behavior. |
| 99 | +""" |
0 commit comments