Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# Copyright The OpenTelemetry 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.
15"""
16The OpenTelemetry tracing API describes the classes used to generate
17distributed traces.
19The :class:`.Tracer` class controls access to the execution context, and
20manages span creation. Each operation in a trace is represented by a
21:class:`.Span`, which records the start, end time, and metadata associated with
22the operation.
24This module provides abstract (i.e. unimplemented) classes required for
25tracing, and a concrete no-op :class:`.NonRecordingSpan` that allows applications
26to use the API package alone without a supporting implementation.
28To get a tracer, you need to provide the package name from which you are
29calling the tracer APIs to OpenTelemetry by calling `TracerProvider.get_tracer`
30with the calling module name and the version of your package.
32The tracer supports creating spans that are "attached" or "detached" from the
33context. New spans are "attached" to the context in that they are
34created as children of the currently active span, and the newly-created span
35can optionally become the new active span::
37 from opentelemetry import trace
39 tracer = trace.get_tracer(__name__)
41 # Create a new root span, set it as the current span in context
42 with tracer.start_as_current_span("parent"):
43 # Attach a new child and update the current span
44 with tracer.start_as_current_span("child"):
45 do_work():
46 # Close child span, set parent as current
47 # Close parent span, set default span as current
49When creating a span that's "detached" from the context the active span doesn't
50change, and the caller is responsible for managing the span's lifetime::
52 # Explicit parent span assignment is done via the Context
53 from opentelemetry.trace import set_span_in_context
55 context = set_span_in_context(parent)
56 child = tracer.start_span("child", context=context)
58 try:
59 do_work(span=child)
60 finally:
61 child.end()
63Applications should generally use a single global TracerProvider, and use
64either implicit or explicit context propagation consistently throughout.
66.. versionadded:: 0.1.0
67.. versionchanged:: 0.3.0
68 `TracerProvider` was introduced and the global ``tracer`` getter was
69 replaced by ``tracer_provider``.
70.. versionchanged:: 0.5.0
71 ``tracer_provider`` was replaced by `get_tracer_provider`,
72 ``set_preferred_tracer_provider_implementation`` was replaced by
73 `set_tracer_provider`.
74"""
76import os
77import typing
78from abc import ABC, abstractmethod
79from enum import Enum
80from logging import getLogger
81from typing import Iterator, Optional, Sequence, cast
83from typing_extensions import deprecated
85from opentelemetry import context as context_api
86from opentelemetry.attributes import BoundedAttributes
87from opentelemetry.context.context import Context
88from opentelemetry.environment_variables import OTEL_PYTHON_TRACER_PROVIDER
89from opentelemetry.trace.propagation import (
90 _SPAN_KEY,
91 get_current_span,
92 set_span_in_context,
93)
94from opentelemetry.trace.span import (
95 DEFAULT_TRACE_OPTIONS,
96 DEFAULT_TRACE_STATE,
97 INVALID_SPAN,
98 INVALID_SPAN_CONTEXT,
99 INVALID_SPAN_ID,
100 INVALID_TRACE_ID,
101 NonRecordingSpan,
102 Span,
103 SpanContext,
104 TraceFlags,
105 TraceState,
106 format_span_id,
107 format_trace_id,
108)
109from opentelemetry.trace.status import Status, StatusCode
110from opentelemetry.util import types
111from opentelemetry.util._decorator import _agnosticcontextmanager
112from opentelemetry.util._once import Once
113from opentelemetry.util._providers import _load_provider
115logger = getLogger(__name__)
118class _LinkBase(ABC):
119 def __init__(self, context: "SpanContext") -> None:
120 self._context = context
122 @property
123 def context(self) -> "SpanContext":
124 return self._context
126 @property
127 @abstractmethod
128 def attributes(self) -> types.Attributes:
129 pass
132class Link(_LinkBase):
133 """A link to a `Span`. The attributes of a Link are immutable.
135 Args:
136 context: `SpanContext` of the `Span` to link to.
137 attributes: Link's attributes.
138 """
140 def __init__(
141 self,
142 context: "SpanContext",
143 attributes: types.Attributes = None,
144 ) -> None:
145 super().__init__(context)
146 self._attributes = attributes
148 @property
149 def attributes(self) -> types.Attributes:
150 return self._attributes
152 @property
153 def dropped_attributes(self) -> int:
154 if isinstance(self._attributes, BoundedAttributes):
155 return self._attributes.dropped
156 return 0
159_Links = Optional[Sequence[Link]]
162class SpanKind(Enum):
163 """Specifies additional details on how this span relates to its parent span.
165 Note that this enumeration is experimental and likely to change. See
166 https://github.com/open-telemetry/opentelemetry-specification/pull/226.
167 """
169 #: Default value. Indicates that the span is used internally in the
170 # application.
171 INTERNAL = 0
173 #: Indicates that the span describes an operation that handles a remote
174 # request.
175 SERVER = 1
177 #: Indicates that the span describes a request to some remote service.
178 CLIENT = 2
180 #: Indicates that the span describes a producer sending a message to a
181 #: broker. Unlike client and server, there is usually no direct critical
182 #: path latency relationship between producer and consumer spans.
183 PRODUCER = 3
185 #: Indicates that the span describes a consumer receiving a message from a
186 #: broker. Unlike client and server, there is usually no direct critical
187 #: path latency relationship between producer and consumer spans.
188 CONSUMER = 4
191class TracerProvider(ABC):
192 @abstractmethod
193 def get_tracer(
194 self,
195 instrumenting_module_name: str,
196 instrumenting_library_version: typing.Optional[str] = None,
197 schema_url: typing.Optional[str] = None,
198 attributes: typing.Optional[types.Attributes] = None,
199 ) -> "Tracer":
200 """Returns a `Tracer` for use by the given instrumentation library.
202 For any two calls it is undefined whether the same or different
203 `Tracer` instances are returned, even for different library names.
205 This function may return different `Tracer` types (e.g. a no-op tracer
206 vs. a functional tracer).
208 Args:
209 instrumenting_module_name: The uniquely identifiable name for instrumentation
210 scope, such as instrumentation library, package, module or class name.
211 ``__name__`` should be avoided as this can result in
212 different tracer names if the tracers are in different files.
213 It is better to use a fixed string that can be imported where
214 needed and used consistently as the name of the tracer.
216 This should *not* be the name of the module that is
217 instrumented but the name of the module doing the instrumentation.
218 E.g., instead of ``"requests"``, use
219 ``"opentelemetry.instrumentation.requests"``.
221 instrumenting_library_version: Optional. The version string of the
222 instrumenting library. Usually this should be the same as
223 ``importlib.metadata.version(instrumenting_library_name)``.
225 schema_url: Optional. Specifies the Schema URL of the emitted telemetry.
226 attributes: Optional. Specifies the attributes of the emitted telemetry.
227 """
230class NoOpTracerProvider(TracerProvider):
231 """The default TracerProvider, used when no implementation is available.
233 All operations are no-op.
234 """
236 def get_tracer(
237 self,
238 instrumenting_module_name: str,
239 instrumenting_library_version: typing.Optional[str] = None,
240 schema_url: typing.Optional[str] = None,
241 attributes: typing.Optional[types.Attributes] = None,
242 ) -> "Tracer":
243 # pylint:disable=no-self-use,unused-argument
244 return NoOpTracer()
247@deprecated(
248 "You should use NoOpTracerProvider. Deprecated since version 1.9.0."
249)
250class _DefaultTracerProvider(NoOpTracerProvider):
251 """The default TracerProvider, used when no implementation is available.
253 All operations are no-op.
254 """
257class ProxyTracerProvider(TracerProvider):
258 def get_tracer(
259 self,
260 instrumenting_module_name: str,
261 instrumenting_library_version: typing.Optional[str] = None,
262 schema_url: typing.Optional[str] = None,
263 attributes: typing.Optional[types.Attributes] = None,
264 ) -> "Tracer":
265 if _TRACER_PROVIDER:
266 return _TRACER_PROVIDER.get_tracer(
267 instrumenting_module_name,
268 instrumenting_library_version,
269 schema_url,
270 attributes,
271 )
272 return ProxyTracer(
273 instrumenting_module_name,
274 instrumenting_library_version,
275 schema_url,
276 attributes,
277 )
280class Tracer(ABC):
281 """Handles span creation and in-process context propagation.
283 This class provides methods for manipulating the context, creating spans,
284 and controlling spans' lifecycles.
285 """
287 @abstractmethod
288 def start_span(
289 self,
290 name: str,
291 context: Optional[Context] = None,
292 kind: SpanKind = SpanKind.INTERNAL,
293 attributes: types.Attributes = None,
294 links: _Links = None,
295 start_time: Optional[int] = None,
296 record_exception: bool = True,
297 set_status_on_exception: bool = True,
298 ) -> "Span":
299 """Starts a span.
301 Create a new span. Start the span without setting it as the current
302 span in the context. To start the span and use the context in a single
303 method, see :meth:`start_as_current_span`.
305 By default the current span in the context will be used as parent, but an
306 explicit context can also be specified, by passing in a `Context` containing
307 a current `Span`. If there is no current span in the global `Context` or in
308 the specified context, the created span will be a root span.
310 The span can be used as a context manager. On exiting the context manager,
311 the span's end() method will be called.
313 Example::
315 # trace.get_current_span() will be used as the implicit parent.
316 # If none is found, the created span will be a root instance.
317 with tracer.start_span("one") as child:
318 child.add_event("child's event")
320 Args:
321 name: The name of the span to be created.
322 context: An optional Context containing the span's parent. Defaults to the
323 global context.
324 kind: The span's kind (relationship to parent). Note that is
325 meaningful even if there is no parent.
326 attributes: The span's attributes.
327 links: Links span to other spans
328 start_time: Sets the start time of a span
329 record_exception: Whether to record any exceptions raised within the
330 context as error event on the span.
331 set_status_on_exception: Only relevant if the returned span is used
332 in a with/context manager. Defines whether the span status will
333 be automatically set to ERROR when an uncaught exception is
334 raised in the span with block. The span status won't be set by
335 this mechanism if it was previously set manually.
337 Returns:
338 The newly-created span.
339 """
341 @_agnosticcontextmanager
342 @abstractmethod
343 def start_as_current_span(
344 self,
345 name: str,
346 context: Optional[Context] = None,
347 kind: SpanKind = SpanKind.INTERNAL,
348 attributes: types.Attributes = None,
349 links: _Links = None,
350 start_time: Optional[int] = None,
351 record_exception: bool = True,
352 set_status_on_exception: bool = True,
353 end_on_exit: bool = True,
354 ) -> Iterator["Span"]:
355 """Context manager for creating a new span and set it
356 as the current span in this tracer's context.
358 Exiting the context manager will call the span's end method,
359 as well as return the current span to its previous value by
360 returning to the previous context.
362 Example::
364 with tracer.start_as_current_span("one") as parent:
365 parent.add_event("parent's event")
366 with tracer.start_as_current_span("two") as child:
367 child.add_event("child's event")
368 trace.get_current_span() # returns child
369 trace.get_current_span() # returns parent
370 trace.get_current_span() # returns previously active span
372 This is a convenience method for creating spans attached to the
373 tracer's context. Applications that need more control over the span
374 lifetime should use :meth:`start_span` instead. For example::
376 with tracer.start_as_current_span(name) as span:
377 do_work()
379 is equivalent to::
381 span = tracer.start_span(name)
382 with opentelemetry.trace.use_span(span, end_on_exit=True):
383 do_work()
385 This can also be used as a decorator::
387 @tracer.start_as_current_span("name")
388 def function():
389 ...
391 function()
393 Args:
394 name: The name of the span to be created.
395 context: An optional Context containing the span's parent. Defaults to the
396 global context.
397 kind: The span's kind (relationship to parent). Note that is
398 meaningful even if there is no parent.
399 attributes: The span's attributes.
400 links: Links span to other spans
401 start_time: Sets the start time of a span
402 record_exception: Whether to record any exceptions raised within the
403 context as error event on the span.
404 set_status_on_exception: Only relevant if the returned span is used
405 in a with/context manager. Defines whether the span status will
406 be automatically set to ERROR when an uncaught exception is
407 raised in the span with block. The span status won't be set by
408 this mechanism if it was previously set manually.
409 end_on_exit: Whether to end the span automatically when leaving the
410 context manager.
412 Yields:
413 The newly-created span.
414 """
417class ProxyTracer(Tracer):
418 # pylint: disable=W0222,signature-differs
419 def __init__(
420 self,
421 instrumenting_module_name: str,
422 instrumenting_library_version: typing.Optional[str] = None,
423 schema_url: typing.Optional[str] = None,
424 attributes: typing.Optional[types.Attributes] = None,
425 ):
426 self._instrumenting_module_name = instrumenting_module_name
427 self._instrumenting_library_version = instrumenting_library_version
428 self._schema_url = schema_url
429 self._attributes = attributes
430 self._real_tracer: Optional[Tracer] = None
431 self._noop_tracer = NoOpTracer()
433 @property
434 def _tracer(self) -> Tracer:
435 if self._real_tracer:
436 return self._real_tracer
438 if _TRACER_PROVIDER:
439 self._real_tracer = _TRACER_PROVIDER.get_tracer(
440 self._instrumenting_module_name,
441 self._instrumenting_library_version,
442 self._schema_url,
443 self._attributes,
444 )
445 return self._real_tracer
446 return self._noop_tracer
448 def start_span(self, *args, **kwargs) -> Span: # type: ignore
449 return self._tracer.start_span(*args, **kwargs) # type: ignore
451 @_agnosticcontextmanager # type: ignore
452 def start_as_current_span(self, *args, **kwargs) -> Iterator[Span]:
453 with self._tracer.start_as_current_span(*args, **kwargs) as span: # type: ignore
454 yield span
457class NoOpTracer(Tracer):
458 """The default Tracer, used when no Tracer implementation is available.
460 All operations are no-op.
461 """
463 def start_span(
464 self,
465 name: str,
466 context: Optional[Context] = None,
467 kind: SpanKind = SpanKind.INTERNAL,
468 attributes: types.Attributes = None,
469 links: _Links = None,
470 start_time: Optional[int] = None,
471 record_exception: bool = True,
472 set_status_on_exception: bool = True,
473 ) -> "Span":
474 current_span = get_current_span(context)
475 if isinstance(current_span, NonRecordingSpan):
476 return current_span
477 parent_span_context = current_span.get_span_context()
478 if parent_span_context is not None and not isinstance(
479 parent_span_context, SpanContext
480 ):
481 logger.warning(
482 "Invalid span context for %s: %s",
483 current_span,
484 parent_span_context,
485 )
486 return INVALID_SPAN
488 return NonRecordingSpan(context=parent_span_context)
490 @_agnosticcontextmanager
491 def start_as_current_span(
492 self,
493 name: str,
494 context: Optional[Context] = None,
495 kind: SpanKind = SpanKind.INTERNAL,
496 attributes: types.Attributes = None,
497 links: _Links = None,
498 start_time: Optional[int] = None,
499 record_exception: bool = True,
500 set_status_on_exception: bool = True,
501 end_on_exit: bool = True,
502 ) -> Iterator["Span"]:
503 span = self.start_span(
504 name=name,
505 context=context,
506 kind=kind,
507 attributes=attributes,
508 links=links,
509 start_time=start_time,
510 record_exception=record_exception,
511 set_status_on_exception=set_status_on_exception,
512 )
513 with use_span(
514 span,
515 end_on_exit=end_on_exit,
516 record_exception=record_exception,
517 set_status_on_exception=set_status_on_exception,
518 ) as span:
519 yield span
522@deprecated("You should use NoOpTracer. Deprecated since version 1.9.0.")
523class _DefaultTracer(NoOpTracer):
524 """The default Tracer, used when no Tracer implementation is available.
526 All operations are no-op.
527 """
530_TRACER_PROVIDER_SET_ONCE = Once()
531_TRACER_PROVIDER: Optional[TracerProvider] = None
532_PROXY_TRACER_PROVIDER = ProxyTracerProvider()
535def get_tracer(
536 instrumenting_module_name: str,
537 instrumenting_library_version: typing.Optional[str] = None,
538 tracer_provider: Optional[TracerProvider] = None,
539 schema_url: typing.Optional[str] = None,
540 attributes: typing.Optional[types.Attributes] = None,
541) -> "Tracer":
542 """Returns a `Tracer` for use by the given instrumentation library.
544 This function is a convenience wrapper for
545 opentelemetry.trace.TracerProvider.get_tracer.
547 If tracer_provider is omitted the current configured one is used.
548 """
549 if tracer_provider is None:
550 tracer_provider = get_tracer_provider()
551 return tracer_provider.get_tracer(
552 instrumenting_module_name,
553 instrumenting_library_version,
554 schema_url,
555 attributes,
556 )
559def _set_tracer_provider(tracer_provider: TracerProvider, log: bool) -> None:
560 def set_tp() -> None:
561 global _TRACER_PROVIDER # pylint: disable=global-statement
562 _TRACER_PROVIDER = tracer_provider
564 did_set = _TRACER_PROVIDER_SET_ONCE.do_once(set_tp)
566 if log and not did_set:
567 logger.warning("Overriding of current TracerProvider is not allowed")
570def set_tracer_provider(tracer_provider: TracerProvider) -> None:
571 """Sets the current global :class:`~.TracerProvider` object.
573 This can only be done once, a warning will be logged if any further attempt
574 is made.
575 """
576 _set_tracer_provider(tracer_provider, log=True)
579def get_tracer_provider() -> TracerProvider:
580 """Gets the current global :class:`~.TracerProvider` object."""
581 if _TRACER_PROVIDER is None:
582 # if a global tracer provider has not been set either via code or env
583 # vars, return a proxy tracer provider
584 if OTEL_PYTHON_TRACER_PROVIDER not in os.environ:
585 return _PROXY_TRACER_PROVIDER
587 tracer_provider: TracerProvider = _load_provider(
588 OTEL_PYTHON_TRACER_PROVIDER, "tracer_provider"
589 )
590 _set_tracer_provider(tracer_provider, log=False)
591 # _TRACER_PROVIDER will have been set by one thread
592 return cast("TracerProvider", _TRACER_PROVIDER)
595@_agnosticcontextmanager
596def use_span(
597 span: Span,
598 end_on_exit: bool = False,
599 record_exception: bool = True,
600 set_status_on_exception: bool = True,
601) -> Iterator[Span]:
602 """Takes a non-active span and activates it in the current context.
604 Args:
605 span: The span that should be activated in the current context.
606 end_on_exit: Whether to end the span automatically when leaving the
607 context manager scope.
608 record_exception: Whether to record any exceptions raised within the
609 context as error event on the span.
610 set_status_on_exception: Only relevant if the returned span is used
611 in a with/context manager. Defines whether the span status will
612 be automatically set to ERROR when an uncaught exception is
613 raised in the span with block. The span status won't be set by
614 this mechanism if it was previously set manually.
615 """
616 try:
617 token = context_api.attach(context_api.set_value(_SPAN_KEY, span))
618 try:
619 yield span
620 finally:
621 context_api.detach(token)
623 # Record only exceptions that inherit Exception class but not BaseException, because
624 # classes that directly inherit BaseException are not technically errors, e.g. GeneratorExit.
625 # See https://github.com/open-telemetry/opentelemetry-python/issues/4484
626 except Exception as exc: # pylint: disable=broad-exception-caught
627 if isinstance(span, Span) and span.is_recording():
628 # Record the exception as an event
629 if record_exception:
630 span.record_exception(exc)
632 # Set status in case exception was raised
633 if set_status_on_exception:
634 span.set_status(
635 Status(
636 status_code=StatusCode.ERROR,
637 description=f"{type(exc).__name__}: {exc}",
638 )
639 )
641 # This causes parent spans to set their status to ERROR and to record
642 # an exception as an event if a child span raises an exception even if
643 # such child span was started with both record_exception and
644 # set_status_on_exception attributes set to False.
645 raise
647 finally:
648 if end_on_exit:
649 span.end()
652__all__ = [
653 "DEFAULT_TRACE_OPTIONS",
654 "DEFAULT_TRACE_STATE",
655 "INVALID_SPAN",
656 "INVALID_SPAN_CONTEXT",
657 "INVALID_SPAN_ID",
658 "INVALID_TRACE_ID",
659 "NonRecordingSpan",
660 "Link",
661 "Span",
662 "SpanContext",
663 "SpanKind",
664 "TraceFlags",
665 "TraceState",
666 "TracerProvider",
667 "Tracer",
668 "format_span_id",
669 "format_trace_id",
670 "get_current_span",
671 "get_tracer",
672 "get_tracer_provider",
673 "set_tracer_provider",
674 "set_span_in_context",
675 "use_span",
676 "Status",
677 "StatusCode",
678]