PKG-INFO 9.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187
  1. Metadata-Version: 2.1
  2. Name: django_opentracing
  3. Version: 1.1.0
  4. Summary: OpenTracing support for Django applications
  5. Home-page: https://github.com/opentracing-contrib/python-django/
  6. Author: Kathy Camenzind
  7. Author-email: kcamenzind@lightstep.com
  8. License: BSD
  9. Download-URL: https://github.com/opentracing-contrib/python-django/tarball/1.1.0
  10. Description: ##################
  11. Django Opentracing
  12. ##################
  13. .. image:: https://travis-ci.org/opentracing-contrib/python-django.svg?branch=master
  14. :target: https://travis-ci.org/opentracing-contrib/python-django
  15. .. image:: https://img.shields.io/pypi/v/django_opentracing.svg
  16. :target: https://pypi.org/project/django_opentracing/
  17. .. image:: https://img.shields.io/pypi/pyversions/django_opentracing.svg
  18. :target: https://pypi.org/project/django_opentracing/
  19. .. image:: https://img.shields.io/pypi/dm/django_opentracing.svg
  20. :target: https://pypi.org/project/django_opentracing/
  21. This package enables distributed tracing in Django 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.
  22. As 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.
  23. If you want to learn more about the underlying python API, visit the python `source code`_.
  24. If you are migrating from the 0.x series, you may want to read the list of `breaking changes`_.
  25. .. _The OpenTracing Project: http://opentracing.io/
  26. .. _source code: https://github.com/opentracing/opentracing-python
  27. .. _breaking changes: #breaking-changes-from-0-x
  28. Installation
  29. ============
  30. Run the following command::
  31. $ pip install django_opentracing
  32. Setting up Tracing
  33. ==================
  34. In order to implement tracing in your system, add the following lines of code to your site's settings.py file:
  35. .. code-block:: python
  36. import django_opentracing
  37. # OpenTracing settings
  38. # if not included, defaults to True.
  39. # has to come before OPENTRACING_TRACING setting because python...
  40. OPENTRACING_TRACE_ALL = True
  41. # defaults to []
  42. # only valid if OPENTRACING_TRACE_ALL == True
  43. OPENTRACING_TRACED_ATTRIBUTES = ['arg1', 'arg2']
  44. # Callable that returns an `opentracing.Tracer` implementation.
  45. OPENTRACING_TRACER_CALLABLE = 'opentracing.Tracer'
  46. # Parameters for the callable (Depending on the tracer implementation chosen)
  47. OPENTRACING_TRACER_PARAMETERS = {
  48. 'example-parameter-host': 'collector',
  49. }
  50. If you want to directly override the ``DjangoTracing`` used, you can use the following. This may cause import loops (See #10)
  51. .. code-block:: python
  52. # some_opentracing_tracer can be any valid OpenTracing tracer implementation
  53. OPENTRACING_TRACING = django_opentracing.DjangoTracing(some_opentracing_tracer)
  54. **Note:** Valid request attributes to trace are listed `here`_. When you trace an attribute, this means that created spans will have tags with the attribute name and the request's value.
  55. .. _here: https://docs.djangoproject.com/en/1.11/ref/request-response/#django.http.HttpRequest
  56. Tracing All Requests
  57. ====================
  58. In order to trace all requests, ``OPENTRACING_TRACE_ALL`` needs to be set to ``True`` (the default). If you want to trace any attributes for all requests, then add them to ``OPENTRACING_TRACED_ATTRIBUTES``. For example, if you wanted to trace the path and method, then set ``OPENTRACING_TRACED_ATTRIBUTES = ['path', 'method']``.
  59. Tracing all requests uses the middleware django_opentracing.OpenTracingMiddleware, so add this to your settings.py file's ``MIDDLEWARE_CLASSES`` at the top of the stack.
  60. .. code-block:: python
  61. MIDDLEWARE_CLASSES = [
  62. 'django_opentracing.OpenTracingMiddleware',
  63. ... # other middleware classes
  64. ]
  65. Tracing Individual Requests
  66. ===========================
  67. If you don't want to trace all requests to your site, set ``OPENTRACING_TRACE_ALL`` to ``False``. Then you can use function decorators to trace individual view functions. This can be done by adding the following lines of code to views.py (or any other file that has url handler functions):
  68. .. code-block:: python
  69. from django.conf import settings
  70. tracing = settings.OPENTRACING_TRACING
  71. @tracing.trace(optional_args)
  72. def some_view_func(request):
  73. ... # do some stuff
  74. This tracing method doesn't use middleware, so there's no need to add it to your settings.py file.
  75. The optional arguments allow for tracing of request attributes. For example, if you want to trace metadata, you could pass in ``@tracing.trace('META')`` and ``request.META`` would be set as a tag on all spans for this view function.
  76. **Note:** If ``OPENTRACING_TRACE_ALL`` is set to ``True``, this decorator will be ignored, including any traced request attributes.
  77. Accessing Spans Manually
  78. ========================
  79. In order to access the span for a request, we've provided an method ``DjangoTracing.get_span(request)`` that returns the span for the request, if it is exists and is not finished. This can be used to log important events to the span, set tags, or create child spans to trace non-RPC events.
  80. Tracing an RPC
  81. ==============
  82. If you want to make an RPC and continue an existing trace, you can inject the current span into the RPC. For example, if making an http request, the following code will continue your trace across the wire:
  83. .. code-block:: python
  84. @tracing.trace()
  85. def some_view_func(request):
  86. new_request = some_http_request
  87. current_span = tracing.get_span(request)
  88. text_carrier = {}
  89. opentracing_tracer.inject(span, opentracing.Format.TEXT_MAP, text_carrier)
  90. for k, v in text_carrier.items():
  91. request.add_header(k,v)
  92. ... # make request
  93. Example
  94. =======
  95. Here is an `example`_ of a Django application that acts as both a client and server,
  96. with integrated OpenTracing tracers.
  97. .. _example: https://github.com/opentracing-contrib/python-django/tree/master/example
  98. Breaking changes from 0.x
  99. =========================
  100. Starting with the 1.0 version, a few changes have taken place from previous versions:
  101. * ``DjangoTracer`` has been renamed to ``DjangoTracing``, although ``DjangoTracer``
  102. can be used still as a deprecated name. Likewise for
  103. ``OPENTRACING_TRACER`` being renamed to ``OPENTRACING_TRACING``.
  104. * When using the middleware layer, ``OPENTRACING_TRACE_ALL`` defaults to ``True``.
  105. * When no ``opentracing.Tracer`` is provided, ``DjangoTracing`` will rely on the
  106. global tracer.
  107. Further Information
  108. ===================
  109. If you’re 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`_.
  110. .. _opentracing.io: http://opentracing.io/
  111. .. _join the mailing list: http://opentracing.us13.list-manage.com/subscribe?u=180afe03860541dae59e84153&id=19117aa6cd
  112. .. _community@opentracing.io: community@opentracing.io
  113. Platform: any
  114. Classifier: Environment :: Web Environment
  115. Classifier: Intended Audience :: Developers
  116. Classifier: License :: OSI Approved :: BSD License
  117. Classifier: Operating System :: OS Independent
  118. Classifier: Framework :: Django :: 1.11
  119. Classifier: Framework :: Django :: 2.1
  120. Classifier: Framework :: Django :: 2.2
  121. Classifier: Programming Language :: Python
  122. Classifier: Programming Language :: Python :: 2.7
  123. Classifier: Programming Language :: Python :: 3.5
  124. Classifier: Programming Language :: Python :: 3.6
  125. Classifier: Programming Language :: Python :: 3.7
  126. Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
  127. Classifier: Topic :: Software Development :: Libraries :: Python Modules
  128. Provides-Extra: tests