Base

Tracing utility

Usage Documentation

Tracer

CLASS	DESCRIPTION
BaseProvider
BaseSegment	Holds common properties and methods on segment and subsegment.

BaseProvider

Bases: ABC

METHOD	DESCRIPTION
in_subsegment	Return a subsegment context manger.
in_subsegment_async	Return a subsegment async context manger.
patch	Instrument a set of supported libraries
patch_all	Instrument all supported libraries
put_annotation	Annotate current active trace entity with a key-value pair.
put_metadata	Add metadata to the current active trace entity.

in_subsegment abstractmethod

in_subsegment(
    name=None, **kwargs
) -> Generator[BaseSegment, None, None]

Return a subsegment context manger.

PARAMETER	DESCRIPTION
name	Subsegment name DEFAULT: None
kwargs	Optional parameters to be propagated to segment DEFAULT: {}

Source code in aws_lambda_powertools/tracing/base.py

@abc.abstractmethod
@contextmanager
def in_subsegment(self, name=None, **kwargs) -> Generator[BaseSegment, None, None]:
    """Return a subsegment context manger.

    Parameters
    ----------
    name: str
        Subsegment name
    kwargs: dict | None
        Optional parameters to be propagated to segment
    """

in_subsegment_async abstractmethod

in_subsegment_async(
    name=None, **kwargs
) -> Generator[BaseSegment, None, None]

Return a subsegment async context manger.

PARAMETER	DESCRIPTION
name	Subsegment name DEFAULT: None
kwargs	Optional parameters to be propagated to segment DEFAULT: {}

Source code in aws_lambda_powertools/tracing/base.py

@abc.abstractmethod
@contextmanager
def in_subsegment_async(self, name=None, **kwargs) -> Generator[BaseSegment, None, None]:
    """Return a subsegment async context manger.

    Parameters
    ----------
    name: str
        Subsegment name
    kwargs: dict | None
        Optional parameters to be propagated to segment
    """

patch abstractmethod

patch(modules: Sequence[str]) -> None

Instrument a set of supported libraries

PARAMETER	DESCRIPTION
modules	Set of modules to be patched TYPE: Sequence[str]

Source code in aws_lambda_powertools/tracing/base.py

@abc.abstractmethod
def patch(self, modules: Sequence[str]) -> None:
    """Instrument a set of supported libraries

    Parameters
    ----------
    modules: set[str]
        Set of modules to be patched
    """

patch_all abstractmethod

patch_all() -> None

Instrument all supported libraries

Source code in aws_lambda_powertools/tracing/base.py

@abc.abstractmethod
def patch_all(self) -> None:
    """Instrument all supported libraries"""

put_annotation abstractmethod

put_annotation(
    key: str, value: str | numbers.Number | bool
) -> None

Annotate current active trace entity with a key-value pair.

Note: Annotations will be indexed for later search query.

PARAMETER	DESCRIPTION
key	Metadata key TYPE: str
value	Annotation value TYPE: str | Number | bool

Source code in aws_lambda_powertools/tracing/base.py

@abc.abstractmethod
def put_annotation(self, key: str, value: str | numbers.Number | bool) -> None:
    """Annotate current active trace entity with a key-value pair.

    Note: Annotations will be indexed for later search query.

    Parameters
    ----------
    key: str
        Metadata key
    value: str | numbers.Number | bool
        Annotation value
    """

put_metadata abstractmethod

put_metadata(
    key: str, value: Any, namespace: str = "default"
) -> None

Add metadata to the current active trace entity.

Note: Metadata is not indexed but can be later retrieved by BatchGetTraces API.

PARAMETER	DESCRIPTION
key	Metadata key TYPE: str
value	Any object that can be serialized into a JSON string TYPE: Any
namespace	Metadata namespace, by default 'default' TYPE: str DEFAULT: 'default'

Source code in aws_lambda_powertools/tracing/base.py

@abc.abstractmethod
def put_metadata(self, key: str, value: Any, namespace: str = "default") -> None:
    """Add metadata to the current active trace entity.

    Note: Metadata is not indexed but can be later retrieved by BatchGetTraces API.

    Parameters
    ----------
    key: str
        Metadata key
    value: Any
        Any object that can be serialized into a JSON string
    namespace: set[str]
        Metadata namespace, by default 'default'
    """

BaseSegment

Bases: ABC

Holds common properties and methods on segment and subsegment.

METHOD	DESCRIPTION
add_exception	Add an exception to trace entities.
add_subsegment	Add input subsegment as a child subsegment.
close	Close the trace entity by setting end_time
put_annotation	Annotate segment or subsegment with a key-value pair.
put_metadata	Add metadata to segment or subsegment. Metadata is not indexed
remove_subsegment	Remove input subsegment from child subsegments.

add_exception abstractmethod

add_exception(
    exception: BaseException,
    stack: list[traceback.StackSummary],
    remote: bool = False,
)

Add an exception to trace entities.

PARAMETER	DESCRIPTION
exception	Caught exception TYPE: BaseException
stack	List of traceback summaries Output from traceback.extract_stack(). TYPE: list[StackSummary]
remote	Whether it's a client error (False) or downstream service error (True), by default False TYPE: bool DEFAULT: False

Source code in aws_lambda_powertools/tracing/base.py

@abc.abstractmethod
def add_exception(self, exception: BaseException, stack: list[traceback.StackSummary], remote: bool = False):
    """Add an exception to trace entities.

    Parameters
    ----------
    exception: Exception
        Caught exception
    stack: list[traceback.StackSummary]
        List of traceback summaries

        Output from `traceback.extract_stack()`.
    remote: bool
        Whether it's a client error (False) or downstream service error (True), by default False
    """

add_subsegment abstractmethod

add_subsegment(subsegment: Any)

Add input subsegment as a child subsegment.

Source code in aws_lambda_powertools/tracing/base.py

@abc.abstractmethod
def add_subsegment(self, subsegment: Any):
    """Add input subsegment as a child subsegment."""

close abstractmethod

close(end_time: int | None = None)

Close the trace entity by setting end_time and flip the in progress flag to False.

PARAMETER	DESCRIPTION
end_time	Time in epoch seconds, by default current time will be used. TYPE: int | None DEFAULT: None

Source code in aws_lambda_powertools/tracing/base.py

@abc.abstractmethod
def close(self, end_time: int | None = None):
    """Close the trace entity by setting `end_time`
    and flip the in progress flag to False.

    Parameters
    ----------
    end_time: int
        Time in epoch seconds, by default current time will be used.
    """

put_annotation abstractmethod

put_annotation(
    key: str, value: str | numbers.Number | bool
) -> None

Annotate segment or subsegment with a key-value pair.

Note: Annotations will be indexed for later search query.

PARAMETER	DESCRIPTION
key	Metadata key TYPE: str
value	Annotation value TYPE: str | Number | bool

Source code in aws_lambda_powertools/tracing/base.py

@abc.abstractmethod
def put_annotation(self, key: str, value: str | numbers.Number | bool) -> None:
    """Annotate segment or subsegment with a key-value pair.

    Note: Annotations will be indexed for later search query.

    Parameters
    ----------
    key: str
        Metadata key
    value: str | numbers.Number | bool
        Annotation value
    """

put_metadata abstractmethod

put_metadata(
    key: str, value: Any, namespace: str = "default"
) -> None

Add metadata to segment or subsegment. Metadata is not indexed but can be later retrieved by BatchGetTraces API.

PARAMETER	DESCRIPTION
key	Metadata key TYPE: str
value	Any object that can be serialized into a JSON string TYPE: Any
namespace	Metadata namespace, by default 'default' TYPE: str DEFAULT: 'default'

Source code in aws_lambda_powertools/tracing/base.py

@abc.abstractmethod
def put_metadata(self, key: str, value: Any, namespace: str = "default") -> None:
    """Add metadata to segment or subsegment. Metadata is not indexed
    but can be later retrieved by BatchGetTraces API.

    Parameters
    ----------
    key: str
        Metadata key
    value: Any
        Any object that can be serialized into a JSON string
    namespace: set[str]
        Metadata namespace, by default 'default'
    """

remove_subsegment abstractmethod

remove_subsegment(subsegment: Any)

Remove input subsegment from child subsegments.

Source code in aws_lambda_powertools/tracing/base.py

@abc.abstractmethod
def remove_subsegment(self, subsegment: Any):
    """Remove input subsegment from child subsegments."""