ddtrace_api

33    def set_exc_info(
34        self, exc_type: Type[BaseException], exc_val: BaseException, exc_tb: Optional[TracebackType]
35    ) -> None:
36        """
37        Tag the span with an error tuple as from ``sys.exc_info()``
38        """
39        retval = None
40
41        audit(_DD_HOOK_NAME, ([retval, self, "set_exc_info", exc_type, exc_val, exc_tb], {}))
42        return retval

44    def set_traceback(self, limit: Optional[int] = None) -> None:
45        """
46                "If the current stack has an exception, tag the span with the relevant error info. If not, tag
47        it with the current python stack."
48
49        """
50        retval = None
51
52        audit(_DD_HOOK_NAME, ([retval, self, "set_traceback"], {"limit": limit}))
53        return retval

55    def set_tags(self, tags: Dict[Union[Text, bytes], Any]) -> None:
56        """
57        Set a dictionary of tags on the given span. Keys and values must be strings (or stringable)
58        """
59        retval = None
60
61        audit(_DD_HOOK_NAME, ([retval, self, "set_tags", tags], {}))
62        return retval

64    def finish_with_ancestors(self) -> None:
65        """
66                "
67        Finish this span along with all (accessible) ancestors of this span.
68
69        This method is useful if a sudden program shutdown is required and finishing
70        the trace is desired.
71        "
72
73        """
74        retval = None
75
76        audit(_DD_HOOK_NAME, ([retval, self, "finish_with_ancestors"], {}))
77        return retval

79    def finish(self, finish_time: Optional[float] = None) -> None:
80        """
81                "Mark the end time of the span and submit it to the tracer.
82        If the span has already been finished don't do anything.
83        "
84
85        """
86        retval = None
87
88        audit(_DD_HOOK_NAME, ([retval, self, "finish"], {"finish_time": finish_time}))
89        return retval

 93    def flush(self) -> None:
 94        """
 95                "
 96        Flush the tracer's internal buffer, sending spans to Datadog's intake endpoint
 97        "
 98
 99        """
100        retval = None
101
102        audit(_DD_HOOK_NAME, ([retval, self, "flush"], {}))
103        return retval

105    def set_tags(self, tags: Dict[str, str]) -> None:
106        """
107                "
108        Set some tags at the tracer level. This will append those tags to each span created by
109        the tracer.
110        "
111
112        """
113        retval = None
114
115        audit(_DD_HOOK_NAME, ([retval, self, "set_tags", tags], {}))
116        return retval

118    def shutdown(self, timeout: Optional[float]) -> None:
119        """
120        "Shutdown the tracer and flush finished traces. Avoid calling shutdown multiple times."
121
122        """
123        retval = None
124
125        audit(_DD_HOOK_NAME, ([retval, self, "shutdown", timeout], {}))
126        return retval

128    def start_span(
129        self,
130        name: str,
131        child_of: Optional[Span] = None,
132        service: Optional[str] = None,
133        resource: Optional[str] = None,
134        span_type: Optional[str] = None,
135        activate: bool = False,
136    ) -> Span:
137        """
138                'Return a span that represents an operation called ``name``.
139
140        Note that the ``.trace`` method will almost always be preferred
141        over this method as it provides automatic span parenting. This method
142        should only be used if manual parenting is desired.
143
144        To start a new root span::
145
146            span = tracer.start_span("web.request")
147
148        To create a child for a root span::
149
150            root_span = tracer.start_span("web.request")
151            span = tracer.start_span("web.decoder", child_of=root_span)
152
153        Spans from ``start_span`` are not activated by default::
154
155            with tracer.start_span("parent") as parent:
156                assert tracer.current_span() is None
157                with tracer.start_span("child", child_of=parent):
158                    assert tracer.current_span() is None
159
160            new_parent = tracer.start_span("new_parent", activate=True)
161            assert tracer.current_span() is new_parent
162        '
163
164        """
165        retval = Span()
166
167        audit(
168            _DD_HOOK_NAME,
169            (
170                [retval, self, "start_span", name],
171                {
172                    "child_of": child_of,
173                    "service": service,
174                    "resource": resource,
175                    "span_type": span_type,
176                    "activate": activate,
177                },
178            ),
179        )
180        return retval

182    def current_root_span(self) -> Span:
183        """
184                "Returns the local root span of the current execution/process.
185
186        Note - This cannot be used to access the true root span of the trace
187        in a distributed tracing setup if the actual root span occurred in
188        another execution/process.
189
190        This is useful for attaching information to the local root span
191        of the current execution/process, which is often also service
192        entry span.
193
194        For example::
195
196            # get the local root span
197            local_root_span = tracer.current_root_span()
198            # set the host just once on the root span
199            if local_root_span:
200                local_root_span.set_tag('host', '127.0.0.1')
201        "
202
203        """
204        retval = Span()
205
206        audit(_DD_HOOK_NAME, ([retval, self, "current_root_span"], {}))
207        return retval

209    def current_span(self) -> Span:
210        """
211                'Return the active span in the current execution context.
212
213        Note that there may be an active span from a distributed trace which will not
214        be returned by this method.
215        '
216
217        """
218        retval = Span()
219
220        audit(_DD_HOOK_NAME, ([retval, self, "current_span"], {}))
221        return retval

223    def trace(
224        self, name: str, service: Optional[str] = None, resource: Optional[str] = None, span_type: Optional[str] = None
225    ) -> Span:
226        """
227                '
228        Activate and return a new span that inherits from the current active span.
229
230        The returned span *must* be ``finish``ed or it will remain in memory
231        indefinitely::
232
233            >>> span = tracer.trace("web.request")
234                try:
235                    # do something
236                finally:
237                    span.finish()
238
239            >>> with tracer.trace("web.request") as span:
240                    # do something
241
242        Example of the automatic parenting::
243
244            parent = tracer.trace("parent")     # has no parent span
245            assert tracer.current_span() is parent
246
247            child  = tracer.trace("child")
248            assert child.parent_id == parent.span_id
249            assert tracer.current_span() is child
250            child.finish()
251
252            # parent is now the active span again
253            assert tracer.current_span() is parent
254            parent.finish()
255
256            assert tracer.current_span() is None
257
258            parent2 = tracer.trace("parent2")
259            assert parent2.parent_id is None
260            parent2.finish()
261        '
262
263        """
264        retval = Span()
265
266        audit(
267            _DD_HOOK_NAME,
268            ([retval, self, "trace", name], {"service": service, "resource": resource, "span_type": span_type}),
269        )
270        return retval

12def _Tracer_wrap(
13    self,  # this will be bound to a Tracer instance
14    name: Optional[str] = None,
15    service: Optional[str] = None,
16    resource: Optional[str] = None,
17    span_type: Optional[str] = None,
18):
19    # type: (...) -> Callable[[VarArg(Any), KwArg(Any)], Any]
20    """
21    A function returning a decorator used to trace an entire function. If the traced function
22    is a coroutine, it traces the coroutine execution when is awaited.
23    If a ``wrap_executor`` callable has been provided in the ``Tracer.configure()``
24    method, it will be called instead of the default one when the function
25    decorator is invoked.
26
27    >>> @tracer.wrap("my.wrapped.function", service="my.service")
28        def run():
29            return "run"
30
31    >>> # name will default to "execute" if unset
32        @tracer.wrap()
33        def execute():
34            return "executed"
35
36    >>> # or use it in asyncio coroutines
37        @tracer.wrap()
38        async def coroutine():
39            return "executed"
40
41    >>> @tracer.wrap()
42        @asyncio.coroutine
43        def coroutine():
44            return "executed"
45
46    You can access the current span using `tracer.current_span()` to set
47    tags:
48
49    >>> @tracer.wrap()
50        def execute():
51            span = tracer.current_span()
52            span.set_tag("a", "b")
53    """
54
55    def wrap_decorator(f: AnyCallable):
56        # type: (...) -> Callable[[VarArg(Any), KwArg(Any)], Any]
57        @functools.wraps(f)
58        def func_wrapper(*args, **kwargs):
59            with self.trace(
60                name or "%s.%s" % (f.__module__, f.__name__),
61                service=service,
62                resource=resource,
63                span_type=span_type,
64            ):
65                return f(*args, **kwargs)
66
67        return func_wrapper
68
69    return wrap_decorator