holoscan.data_loggers

SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

class holoscan.data_loggers.BasicConsoleLogger

Bases: holoscan.core._core.DataLoggerResource

Basic console logger for debugging and development purposes.

This data logger outputs structured log messages to the console (via the Holoscan logging system) for any data received. It can handle tensors, tensor maps, metadata, and general data types by converting them to human-readable text format.

The logger provides filtering capabilities to control which messages are logged.

Parameters

fragmentholoscan.core.Fragment (constructor only)

The fragment that the data logger belongs to.

serializerholoscan.data_loggers.SimpleTextSerializer, optional

Text serializer used to convert data to string format. If not provided, a default SimpleTextSerializer will be created automatically.

log_inputsbool, optional

Whether to log input messages. Default is True.

log_outputsbool, optional

Whether to log output messages. Default is True.

log_tensor_data_contentbool, optional

Whether to log the actual content of tensor data. Default is False.

log_metadatabool, optional

Whether to log metadata associated with messages. Default is True.

allowlist_patternslist of str, optional

List of regex patterns. Only messages matching these patterns will be logged. If empty, all messages are allowed.

denylist_patternslist of str, optional

List of regex patterns. Messages matching these patterns will be filtered out. Denylist takes precedence over allowlist.

namestr, optional (constructor only)

The name of the data logger. Default value is "basic_console_logger".

} // namespace BasicConsoleLogger

Notes

If allowlist_patterns or denylist_patterns are specified, they are applied to the unique_id assigned to messages by the underlying framework.

In a non-distributed application (without a fragment name), the unique_id for a message will have one of the following forms:

• operator_name.port_name

• operator_name.port_name:index (for multi-receivers with N:1 connection)

For distributed applications, the fragment name will also appear in the unique id:

• fragment_name.operator_name.port_name

• fragment_name.operator_name.port_name:index (for multi-receivers with N:1 connection)

Attributes

args	The list of arguments associated with the component.
description	YAML formatted string describing the resource.
fragment	Fragment that the resource belongs to.
id	The identifier of the component.
name	The name of the resource.
resource_type	Resource type.

spec

Methods

add_arg(*args, **kwargs)	Overloaded function.
initialize(self)	initialization method for the resource.
service(self, service_type[, id])	Retrieve a registered fragment service through the component's fragment.
setup(self, arg0)	setup method for the resource.

ResourceType

class ResourceType

Bases: pybind11_builtins.pybind11_object

Members:

NATIVE

GXF

Attributes

name

value

GXF = <ResourceType.GXF: 1>

NATIVE = <ResourceType.NATIVE: 0>

__init__(self: holoscan.core._core.Resource.ResourceType, value: int) → None

property name

property value

__init__(self: holoscan.data_loggers.basic_console_logger._basic_console_logger.BasicConsoleLogger, fragment: holoscan.core._core.Fragment, *args, serializer: holoscan.data_loggers.basic_console_logger._basic_console_logger.SimpleTextSerializer = None, log_inputs: bool = True, log_outputs: bool = True, log_tensor_data_content: bool = False, log_metadata: bool = True, allowlist_patterns: list[str] = [], denylist_patterns: list[str] = [], name: str = 'basic_console_logger') → None

Basic console logger for debugging and development purposes.

This data logger outputs structured log messages to the console (via the Holoscan logging system) for any data received. It can handle tensors, tensor maps, metadata, and general data types by converting them to human-readable text format.

The logger provides filtering capabilities to control which messages are logged.

Parameters

fragmentholoscan.core.Fragment (constructor only)

The fragment that the data logger belongs to.

serializerholoscan.data_loggers.SimpleTextSerializer, optional

Text serializer used to convert data to string format. If not provided, a default SimpleTextSerializer will be created automatically.

log_inputsbool, optional

Whether to log input messages. Default is True.

log_outputsbool, optional

Whether to log output messages. Default is True.

log_tensor_data_contentbool, optional

Whether to log the actual content of tensor data. Default is False.

log_metadatabool, optional

Whether to log metadata associated with messages. Default is True.

allowlist_patternslist of str, optional

List of regex patterns. Only messages matching these patterns will be logged. If empty, all messages are allowed.

denylist_patternslist of str, optional

List of regex patterns. Messages matching these patterns will be filtered out. Denylist takes precedence over allowlist.

namestr, optional (constructor only)

The name of the data logger. Default value is "basic_console_logger".

} // namespace BasicConsoleLogger

Notes

If allowlist_patterns or denylist_patterns are specified, they are applied to the unique_id assigned to messages by the underlying framework.

In a non-distributed application (without a fragment name), the unique_id for a message will have one of the following forms:

• operator_name.port_name

• operator_name.port_name:index (for multi-receivers with N:1 connection)

For distributed applications, the fragment name will also appear in the unique id:

• fragment_name.operator_name.port_name

• fragment_name.operator_name.port_name:index (for multi-receivers with N:1 connection)

add_arg(*args, **kwargs)

Overloaded function.

1. add_arg(self: holoscan.core._core.ComponentBase, arg: holoscan.core._core.Arg) -> None

Add an argument to the component.

2. add_arg(self: holoscan.core._core.ComponentBase, arg: holoscan.core._core.ArgList) -> None

Add a list of arguments to the component.

property args

The list of arguments associated with the component.

Returns

arglistholoscan.core.ArgList

property description

YAML formatted string describing the resource.

property fragment

Fragment that the resource belongs to.

Returns

nameholoscan.core.Fragment

property id

The identifier of the component.

The identifier is initially set to -1, and will become a valid value when the component is initialized.

With the default executor (holoscan.gxf.GXFExecutor), the identifier is set to the GXF component ID.

Returns

idint

initialize(self: holoscan.core._core.Resource) → None

initialization method for the resource.

property name

The name of the resource.

Returns

namestr

property resource_type

Resource type.

holoscan.core.Resource.ResourceType enum representing the type of the resource. The two types currently implemented are NATIVE and GXF.

service(self: object, service_type: type, id: str = '') → object

Retrieve a registered fragment service through the component’s fragment.

This method delegates to the fragment’s service() method to retrieve a previously registered fragment service by its type and optional identifier. Returns None if no fragment service is found with the specified type and identifier.

Parameters

service_typetype

The type of the fragment service to retrieve. Must be a type that inherits from Resource or FragmentService.

idstr, optional

The identifier of the fragment service. If empty, retrieves by service type only. For Resources, this would typically be the resource’s name.

Returns

object or None

The fragment service instance of the requested type, or None if not found. If the service wraps a Resource and a Resource type is requested, the unwrapped Resource instance is returned.

Raises

RuntimeError

If the component has no associated fragment or if the fragment’s service method cannot be accessed.

Notes

This is a convenience method that internally calls the fragment’s service() method. For services that wrap Resources, the method will automatically unwrap and return the Resource if a Resource type is requested.

setup(self: holoscan.core._core.Resource, arg0: holoscan.core._core.ComponentSpec) → None

setup method for the resource.

property spec

class holoscan.data_loggers.SimpleTextSerializer

Bases: holoscan.core._core.Resource

Simple text serializer for converting various data types to human-readable strings.

This serializer can handle common data types including integers, floats, strings, vectors, metadata dictionaries, tensors, and tensor maps. It provides configurable limits for vector elements and metadata items to prevent excessively long output.

Parameters

fragmentholoscan.core.Fragment (constructor only)

The fragment that the serializer belongs to.

max_elementsint, optional

Maximum number of vector elements to display before truncation. Default is 10.

max_metadata_itemsint, optional

Maximum number of metadata dictionary items to display before truncation. Default is 10.

log_python_object_contentsbool, optional

Whether to log Python object contents. Default is True. Warning: logging the contents of Python objects via the repr method requires acquiring the GIL which can be slow.

namestr, optional (constructor only)

The name of the serializer. Default value is "simple_text_serializer".

Attributes

args	The list of arguments associated with the component.
description	YAML formatted string describing the resource.
fragment	Fragment that the resource belongs to.
id	The identifier of the component.
name	The name of the resource.
resource_type	Resource type.

spec

Methods

add_arg(*args, **kwargs)	Overloaded function.
initialize(self)	initialization method for the resource.
service(self, service_type[, id])	Retrieve a registered fragment service through the component's fragment.
setup(self, arg0)	setup method for the resource.

ResourceType

class ResourceType

Bases: pybind11_builtins.pybind11_object

Members:

NATIVE

GXF

Attributes

name

value

GXF = <ResourceType.GXF: 1>

NATIVE = <ResourceType.NATIVE: 0>

__init__(self: holoscan.core._core.Resource.ResourceType, value: int) → None

property name

property value

__init__(self: holoscan.data_loggers.basic_console_logger._basic_console_logger.SimpleTextSerializer, fragment: holoscan.core._core.Fragment, *args, max_elements: int = 10, max_metadata_items: int = 10, log_python_object_contents: bool = True, name: str = 'simple_text_serializer') → None

Simple text serializer for converting various data types to human-readable strings.

This serializer can handle common data types including integers, floats, strings, vectors, metadata dictionaries, tensors, and tensor maps. It provides configurable limits for vector elements and metadata items to prevent excessively long output.

Parameters

fragmentholoscan.core.Fragment (constructor only)

The fragment that the serializer belongs to.

max_elementsint, optional

Maximum number of vector elements to display before truncation. Default is 10.

max_metadata_itemsint, optional

Maximum number of metadata dictionary items to display before truncation. Default is 10.

log_python_object_contentsbool, optional

Whether to log Python object contents. Default is True. Warning: logging the contents of Python objects via the repr method requires acquiring the GIL which can be slow.

namestr, optional (constructor only)

The name of the serializer. Default value is "simple_text_serializer".

add_arg(*args, **kwargs)

Overloaded function.

1. add_arg(self: holoscan.core._core.ComponentBase, arg: holoscan.core._core.Arg) -> None

Add an argument to the component.

2. add_arg(self: holoscan.core._core.ComponentBase, arg: holoscan.core._core.ArgList) -> None

Add a list of arguments to the component.

property args

The list of arguments associated with the component.

Returns

arglistholoscan.core.ArgList

property description

YAML formatted string describing the resource.

property fragment

Fragment that the resource belongs to.

Returns

nameholoscan.core.Fragment

property id

The identifier of the component.

The identifier is initially set to -1, and will become a valid value when the component is initialized.

With the default executor (holoscan.gxf.GXFExecutor), the identifier is set to the GXF component ID.

Returns

idint

initialize(self: holoscan.core._core.Resource) → None

initialization method for the resource.

property name

The name of the resource.

Returns

namestr

property resource_type

Resource type.

holoscan.core.Resource.ResourceType enum representing the type of the resource. The two types currently implemented are NATIVE and GXF.

service(self: object, service_type: type, id: str = '') → object

Retrieve a registered fragment service through the component’s fragment.

This method delegates to the fragment’s service() method to retrieve a previously registered fragment service by its type and optional identifier. Returns None if no fragment service is found with the specified type and identifier.

Parameters

service_typetype

The type of the fragment service to retrieve. Must be a type that inherits from Resource or FragmentService.

idstr, optional

The identifier of the fragment service. If empty, retrieves by service type only. For Resources, this would typically be the resource’s name.

Returns

object or None

The fragment service instance of the requested type, or None if not found. If the service wraps a Resource and a Resource type is requested, the unwrapped Resource instance is returned.

Raises

RuntimeError

If the component has no associated fragment or if the fragment’s service method cannot be accessed.

Notes

This is a convenience method that internally calls the fragment’s service() method. For services that wrap Resources, the method will automatically unwrap and return the Resource if a Resource type is requested.

setup(self: holoscan.core._core.Resource, arg0: holoscan.core._core.ComponentSpec) → None

setup method for the resource.

property spec