luxonis_ml.telemetry

package documentation

Public telemetry API for Luxonis packages.

The luxonis_ml.telemetry package exposes a lightweight event-capture client, environment-driven configuration, singleton helpers, context providers, and suppression tools. It is designed so consuming packages can emit usage events without coupling directly to a specific analytics backend. PostHog support is optional through luxonis-ml[telemetry]; disabled, misconfigured, and debug configurations can use no-op or stdout backends.

Example

Emit an event from a component while keeping backend configuration separate from the call site.

from luxonis_ml.telemetry import Telemetry

telemetry = Telemetry("luxonis_ml", source_component="data")
telemetry.capture(
    "dataset_export_started",
    {"dataset_type": "coco"},
)

Note

Telemetry failures are intentionally non-fatal for host applications. If a backend cannot be initialized or capture fails, the telemetry layer falls back or suppresses the error rather than interrupting the caller.

See Also

luxonis_ml.telemetry.client for the capture client, luxonis_ml.telemetry.config for configuration, and luxonis_ml.telemetry.backends for backend implementations.

Package backends No package docstring; 0/1 constant, 4/4 classes, 0/4 module documented
Package cli No package docstring; 4/4 functions, 0/3 module documented
Module client No module docstring; 0/2 type alias, 1/1 function documented
Module config Undocumented
Module context No module docstring; 0/1 constant, 4/4 functions documented
Module events No module docstring; 1/1 class documented
Module redaction No module docstring; 0/7 constant, 7/7 functions documented
Module singleton No module docstring; 0/3 variable, 3/5 functions, 0/1 class documented
Module suppression No module docstring; 0/1 variable, 1/1 function documented

From __init__.py:

Class Telemetry Telemetry client for emitting events via pluggable backends.
Class TelemetryConfig Configuration for telemetry collection.
Class TelemetryDefaults Optional product-level defaults for telemetry configuration.
Function get_or_init Return an existing telemetry instance or initialize one.
Function get_telemetry Return a telemetry instance by singleton identity.
Function host_context Return coarse host metadata for optional event context.
Function host_context_provider Context provider that exposes coarse host metadata.
Function initialize_telemetry Initialize and return a telemetry instance for one emitter.
Function shutdown_on_exit Register an exit handler to flush telemetry on shutdown.
Function suppress_telemetry Context manager to suppress telemetry for nested calls.
Function system_context Return extended runtime metadata for optional event context.
Function system_context_provider Context provider that exposes extended runtime metadata.
def get_or_init(library_name: str, *, source_component: str | None = None, library_version: str | None = None, config: TelemetryConfig | None = None, context_providers: list[ContextProvider] | None = None, system_context_providers: list[SystemContextProvider] | None = None, register_exit_handler: bool = True) -> Telemetry:

Return an existing telemetry instance or initialize one.

Parameters
library_name:strName of the library emitting telemetry.
source_component:str | NoneOptional emitter/component name for the singleton instance. If omitted, the library name is reused.
library_version:str | NoneVersion string for the library.
config:TelemetryConfig | NoneOptional telemetry configuration.
context_providers:list[ContextProvider] | NoneCallables that return extra context to attach to every event.
system_context_providers:list[SystemContextProvider] | NoneCallables that return extra context to attach only when system metadata is requested.
register_exit_handler:boolWhether to flush telemetry on process exit.
Returns
TelemetryThe existing or newly initialized telemetry instance for the (library_name, source_component) key.
def get_telemetry(library_name: str | None = None, *, source_component: str | None = None) -> Telemetry | None:

Return a telemetry instance by singleton identity.

Parameters
library_name:str | NoneOptional library/product name to filter by.
source_component:str | NoneOptional emitter/component name to filter by.
Returns
Telemetry | NoneThe matching telemetry instance when the lookup resolves to one instance. Ambiguous lookups return None.
def host_context() -> dict[str, Any]:

Return coarse host metadata for optional event context.

def host_context_provider(_telemetry: object) -> dict[str, Any]:

Context provider that exposes coarse host metadata.

def initialize_telemetry(*, library_name: str, source_component: str | None = None, library_version: str | None = None, config: TelemetryConfig | None = None, context_providers: list[ContextProvider] | None = None, system_context_providers: list[SystemContextProvider] | None = None, register_exit_handler: bool = True) -> Telemetry:

Initialize and return a telemetry instance for one emitter.

Parameters
library_name:strName of the library emitting telemetry.
source_component:str | NoneOptional emitter/component name. If omitted, the library name is reused.
library_version:str | NoneOptional version string for the library.
config:TelemetryConfig | NoneOptional telemetry configuration.
context_providers:list[ContextProvider] | NoneOptional list of context provider callables.
system_context_providers:list[SystemContextProvider] | NoneOptional list of system context provider callables.
register_exit_handler:boolWhether to flush telemetry on process exit.
Returns
TelemetryThe initialized telemetry instance for the exact (library_name, source_component) key.
def shutdown_on_exit():

Register an exit handler to flush telemetry on shutdown.

@contextmanager
def suppress_telemetry() -> Generator[None, None, None]:

Context manager to suppress telemetry for nested calls.

def system_context() -> dict[str, Any]:

Return extended runtime metadata for optional event context.

def system_context_provider(_telemetry: object) -> dict[str, Any]:

Context provider that exposes extended runtime metadata.