propagation.py 3.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293
  1. # Copyright The OpenTracing Authors
  2. #
  3. # Licensed under the Apache License, Version 2.0 (the "License");
  4. # you may not use this file except in compliance with the License.
  5. # You may obtain a copy of the License at
  6. #
  7. # http://www.apache.org/licenses/LICENSE-2.0
  8. #
  9. # Unless required by applicable law or agreed to in writing, software
  10. # distributed under the License is distributed on an "AS IS" BASIS,
  11. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. # See the License for the specific language governing permissions and
  13. # limitations under the License.
  14. from __future__ import absolute_import
  15. class UnsupportedFormatException(Exception):
  16. """UnsupportedFormatException should be used when the provided format
  17. value is unknown or disallowed by the :class:`Tracer`.
  18. See :meth:`Tracer.inject()` and :meth:`Tracer.extract()`.
  19. """
  20. pass
  21. class InvalidCarrierException(Exception):
  22. """InvalidCarrierException should be used when the provided carrier
  23. instance does not match what the `format` argument requires.
  24. See :meth:`Tracer.inject()` and :meth:`Tracer.extract()`.
  25. """
  26. pass
  27. class SpanContextCorruptedException(Exception):
  28. """SpanContextCorruptedException should be used when the underlying
  29. :class:`SpanContext` state is seemingly present but not well-formed.
  30. See :meth:`Tracer.inject()` and :meth:`Tracer.extract()`.
  31. """
  32. pass
  33. class Format(object):
  34. """A namespace for builtin carrier formats.
  35. These static constants are intended for use in the :meth:`Tracer.inject()`
  36. and :meth:`Tracer.extract()` methods. E.g.::
  37. tracer.inject(span.context, Format.BINARY, binary_carrier)
  38. """
  39. BINARY = 'binary'
  40. """
  41. The BINARY format represents SpanContexts in an opaque bytearray carrier.
  42. For both :meth:`Tracer.inject()` and :meth:`Tracer.extract()` the carrier
  43. should be a bytearray instance. :meth:`Tracer.inject()` must append to the
  44. bytearray carrier (rather than replace its contents).
  45. """
  46. TEXT_MAP = 'text_map'
  47. """
  48. The TEXT_MAP format represents :class:`SpanContext`\\ s in a python
  49. ``dict`` mapping from strings to strings.
  50. Both the keys and the values have unrestricted character sets (unlike the
  51. HTTP_HEADERS format).
  52. NOTE: The TEXT_MAP carrier ``dict`` may contain unrelated data (e.g.,
  53. arbitrary gRPC metadata). As such, the :class:`Tracer` implementation
  54. should use a prefix or other convention to distinguish tracer-specific
  55. key:value pairs.
  56. """
  57. HTTP_HEADERS = 'http_headers'
  58. """
  59. The HTTP_HEADERS format represents :class:`SpanContext`\\ s in a python
  60. ``dict`` mapping from character-restricted strings to strings.
  61. Keys and values in the HTTP_HEADERS carrier must be suitable for use as
  62. HTTP headers (without modification or further escaping). That is, the
  63. keys have a greatly restricted character set, casing for the keys may not
  64. be preserved by various intermediaries, and the values should be
  65. URL-escaped.
  66. NOTE: The HTTP_HEADERS carrier ``dict`` may contain unrelated data (e.g.,
  67. arbitrary gRPC metadata). As such, the :class:`Tracer` implementation
  68. should use a prefix or other convention to distinguish tracer-specific
  69. key:value pairs.
  70. """