{
    "info": {
        "author": "Carlos Alberto Cortez",
        "author_email": "calberto.cortez@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "Environment :: Web Environment",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: BSD License",
            "Operating System :: OS Independent",
            "Programming Language :: Python",
            "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
            "Topic :: Software Development :: Libraries :: Python Modules"
        ],
        "description": "###################\nTornado Opentracing\n###################\n\nThis package enables distributed tracing in Tornado projects via `The OpenTracing Project`_. Once a production system contends with real concurrency or splits into many services, crucial (and formerly easy) tasks become difficult: user-facing latency optimization, root-cause analysis of backend errors, communication about distinct pieces of a now-distributed system, etc. Distributed tracing follows a request on its journey from inception to completion from mobile/browser all the way to the microservices.\n\nAs core services and libraries adopt OpenTracing, the application builder is no longer burdened with the task of adding basic tracing instrumentation to their own code. In this way, developers can build their applications with the tools they prefer and benefit from built-in tracing instrumentation. OpenTracing implementations exist for major distributed tracing systems and can be bound or swapped with a one-line configuration change.\n\nIf you want to learn more about the underlying python API, visit the python `source code`_.\n\n.. _The OpenTracing Project: http://opentracing.io/\n.. _source code: https://github.com/opentracing/opentracing-python\n\nInstallation\n============\n\nRun the following command::\n\n    $ pip install tornado_opentracing\n\nSetting up Tracing for All Requests\n===================================\n\nIn order to implement tracing in your system (for all the requests), add the following lines of code to your site's ``Application`` constructor to enable tracing:\n\n.. code-block:: python\n\n    from opentracing.scope_managers.tornado import TornadoScopeManager\n    import tornado_opentracing\n\n    # Create your opentracing tracer using TornadoScopeManager for active Span handling.\n    tracer = SomeOpenTracingTracer(scope_manager=TornadoScopeManager())\n\n    # Initialize tracing before creating the Application object\n    tornado_opentracing.init_tracing()\n\n    # And either ONE of these possible values:\n\n    # 1. Specify a TornadoTracing object.\n    app = Application(\n        ''' Other parameters here '''\n        opentracing_tracing=tornado_opentracing.TornadoTracing(tracer),\n    )\n\n    # 2. Pass a module-level callable, invoked once,\n    # returning an opentracing compliant Tracer with optional parameters.\n    app = Application(\n        ''' Other parameters here '''\n        opentracing_tracer_callable='opentracing.mocktracer.MockTracer',\n        opentracing_tracer_parameters={\n            'scope_manager': opentracing.scope_managers.TornadoScopeManager(),\n        },\n    )\n\nIt is possible to set additional settings, for advanced usage:\n\n.. code-block:: python\n\n    app = Application(\n        ''' Other parameters here '''\n        opentracing_tracing=tornado_opentracing.TornadoTracing(tracer),\n        opentracing_trace_all=True, # defaults to True.\n        opentracing_trace_client=True, # AsyncHTTPClient tracing, defaults to True\n        opentracing_traced_attributes=['method'], # only valid if trace_all==True\n        opentracing_start_span_cb=my_start_span_cb, # optional start Span callback.\n    )\n\n\n**Note:** Valid request attributes to trace are listed `here <http://www.tornadoweb.org/en/stable/httputil.html#tornado.httputil.HTTPServerRequest>`_. When you trace an attribute, this means that created spans will have tags with the attribute name and the request's value.\n\nTracing All Requests\n====================\n\nIn order to trace all requests, set ``opentracing_trace_all=True`` when creating ``Application`` (this is the default value). If you want to record any attributes (as tags) for all requests, then add them to ``opentracing_traced_attributes``. For example, if you wanted to trace the uri and method, then set ``opentracing_traced_attributes = ['uri', 'method']``.\n\n``opentracing_start_span_cb`` is a callback invoked after a new ``Span`` has been created, and it must have two parameters: the new ``Span`` and the ``request`` object.\n\nTracing requires ``init_tracing()`` to be called before ``Application`` is created (which will patch the ``RequestHandler``, ``Application`` and other **Tornado** components).\n\nTracing Individual Requests\n===========================\n\nIf you don't want to trace all requests to your site, then you can use function decorators to trace individual functions. This can be done by managing a globally unique ``TornadoTracing`` object yourself, and adding the following lines of code to any get/post/put/delete function of your ``RequestHandler`` sub-classes:\n\n.. code-block:: python\n\n    tracing = TornadoTracing(some_opentracing_tracer)\n\n    class MyRequestHandler(tornado.web.RequestHandler):\n        # put the decorator before @tornado.gen.coroutine, if used\n        @tracing.trace(['uri', 'method']) # optionally pass a list of traced attributes\n        def get(self):\n            ... # do some stuff\n\nThis tracing usage doesn't consume any ``opentracing_*`` setting defined in ``Application``, and there is not need to call ``init_tracing``.\n\nThe optional arguments allow for tracing of request attributes.\n\nTracing HTTP Client Requests\n============================\n\nWhen tracing all requests, tracing for ``AsyncHTTPClient`` is enabled by default, but this can be disabled by setting ``opentracing_trace_client=False``.\n\nFor applications tracing individual requests, or using only the http client (no ``tornado.web`` usage), client tracing can be enabled like this:\n\n.. code-block:: python\n\n    tornado_opentracing.init_client_tracing(some_opentracing_tracer)\n\n\n``init_client_tracing`` takes an OpenTracing-compatible tracer, and can optionally take a ``start_span_cb`` parameter as callback. Observe this call **is not** required when required when using ``trace_all`` with the ``init_tracing`` initialization.\n\n**Note**: A current limitation of ``TornadoScopeManager`` prevents scheduling more than one coroutine with active ``Span`` at a time (see the **Active Span Handling** section below). And since it's a common pattern to use ``AsyncHTTPClient`` to fetch multiple urls at a time, newly created ``Span`` for client requests will not be set as active through ``ScopeManager``.\n\nActive Span handling\n====================\n\nFor active ``Span`` handling and propagation, your ``Tracer`` should use ``opentracing.scope_managers.tornado.TornadoScopeManager``. Tracing both all requests and individual requests will set up a proper stack context automatically, and the active ``Span`` will be propagated from parent coroutines to their children. In any other case, code needs to be run under ``tracer_stack_context()`` explicitly:\n\n.. code-block:: python\n\n    from opentracing.scope_managers.tornado import tracer_stack_context\n\n    with tracer_stack_context():\n        ioloop.IOLoop.current().run_sync(main_func)\n\n\n**Note**: Currently ``TornadoScopeManager`` does not support scheduling more than one coroutine setting the active ``Span`` at a time, as the given context is shared, and thus can be messed up:\n\n.. code-block:: python\n\n    @tornado.gen.coroutine\n    def child_coroutine(name, input_data):\n        # Cannot set Span as active.\n        # However, the parent active Span will still be set,\n        # thus no need to specify it with child_of=\n        with tracer.start_span('child-%s' % name) as span:\n            ...\n\n    @tornado.gen.corotuine\n    def parent_coroutine():\n        with tracer.start_active_span('parent'):\n          a = child_coroutine('A', input_a)\n          b = child_coroutine('B', input_b)\n          yield [a, b]\n\nExamples\n========\n\nHere is a `simple example`_ of a **Tornado** application that log all requests:\n\n.. _simple example: https://github.com/carlosalberto/python-tornado/tree/master/examples/simple/\n\nOther examples are included under the examples directrory.\n\nFurther Information\n===================\n\nIf you\u2019re interested in learning more about the OpenTracing standard, please visit `opentracing.io`_ or `join the mailing list`_. If you would like to implement OpenTracing in your project and need help, feel free to send us a note at `community@opentracing.io`_.\n\n.. _opentracing.io: http://opentracing.io/\n.. _join the mailing list: http://opentracing.us13.list-manage.com/subscribe?u=180afe03860541dae59e84153&id=19117aa6cd\n.. _community@opentracing.io: community@opentracing.io\n\n",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "https://github.com/opentracing-contrib/python-tornado/tarball/1.0.1",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/opentracing-contrib/python-tornado/",
        "keywords": "",
        "license": "Apache License 2.0",
        "maintainer": "",
        "maintainer_email": "",
        "name": "tornado_opentracing",
        "package_url": "https://pypi.org/project/tornado_opentracing/",
        "platform": "any",
        "project_url": "https://pypi.org/project/tornado_opentracing/",
        "project_urls": {
            "Download": "https://github.com/opentracing-contrib/python-tornado/tarball/1.0.1",
            "Homepage": "https://github.com/opentracing-contrib/python-tornado/"
        },
        "release_url": "https://pypi.org/project/tornado_opentracing/1.0.1/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "OpenTracing support for Tornado applications",
        "version": "1.0.1"
    },
    "last_serial": 4482158,
    "releases": {
        "0.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "db987ea4f61dd411762f2fac7e3731e5",
                    "sha256": "2091630f1751337a1fff11e465a9bfeffcb267dc18f4f89f6b9dd92ade30d209"
                },
                "downloads": -1,
                "filename": "tornado_opentracing-0.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "db987ea4f61dd411762f2fac7e3731e5",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 12889,
                "upload_time": "2018-05-24T03:10:43",
                "url": "https://files.pythonhosted.org/packages/54/b8/c67b0a8f972c83fe46c0e061c6914ad933827f30120d45950cd3bc88bc8a/tornado_opentracing-0.1.0.tar.gz"
            }
        ],
        "1.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "f45a5cf13292a87bba5b0b48cbf1e54b",
                    "sha256": "12225a16ad643c6ea440ded7af7408733ae3743ee481eeff3103d322c501f6fd"
                },
                "downloads": -1,
                "filename": "tornado_opentracing-1.0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "f45a5cf13292a87bba5b0b48cbf1e54b",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 15154,
                "upload_time": "2018-07-27T18:37:44",
                "url": "https://files.pythonhosted.org/packages/bc/28/702593fe9b4cef3840b9f32ce54ba4ea18d6aa853f84e469483eaa8bfb3f/tornado_opentracing-1.0.0.tar.gz"
            }
        ],
        "1.0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "8ec5756715f0a37292f09f17fa1d6113",
                    "sha256": "6e45d7700fdc84578adb2bcd49bdb213916a1cbf0e7eb3639b8f80325bb5481b"
                },
                "downloads": -1,
                "filename": "tornado_opentracing-1.0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "8ec5756715f0a37292f09f17fa1d6113",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 15794,
                "upload_time": "2018-11-13T15:35:02",
                "url": "https://files.pythonhosted.org/packages/08/8c/782d88e3b3ff105eb142769e3fc8a309ade0491e8e90b3889da9cda84e97/tornado_opentracing-1.0.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "8ec5756715f0a37292f09f17fa1d6113",
                "sha256": "6e45d7700fdc84578adb2bcd49bdb213916a1cbf0e7eb3639b8f80325bb5481b"
            },
            "downloads": -1,
            "filename": "tornado_opentracing-1.0.1.tar.gz",
            "has_sig": false,
            "md5_digest": "8ec5756715f0a37292f09f17fa1d6113",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 15794,
            "upload_time": "2018-11-13T15:35:02",
            "url": "https://files.pythonhosted.org/packages/08/8c/782d88e3b3ff105eb142769e3fc8a309ade0491e8e90b3889da9cda84e97/tornado_opentracing-1.0.1.tar.gz"
        }
    ]
}