Telemetry Module API Reference¶

This section documents the internals of the telemetry module in Bijux CLI.

bijux_cli.infra.telemetry ¶

Provides concrete telemetry service implementations for event tracking.

This module defines concrete classes that implement the TelemetryProtocol. It offers different strategies for handling telemetry events, allowing the application's analytics behavior to be configured easily.

Key components include

TelemetryEvent: An enumeration of all standardized event names, providing a single source of truth for telemetry event types.
NullTelemetry: A no-op implementation that silently discards all events, useful for disabling telemetry entirely.
LoggingTelemetry: An implementation that forwards all telemetry events to the application's structured logging service.

LoggingTelemetry ¶

LoggingTelemetry(observability: ObservabilityProtocol)

Bases: TelemetryProtocol

A telemetry service that logs events via the Observability service.

This implementation of TelemetryProtocol forwards all telemetry events to the structured logger as debug-level messages.

Attributes:

_obs (ObservabilityProtocol) –

The logging service instance.
_buffer (list) –

A buffer to store events (currently only cleared on flush).

Initializes the LoggingTelemetry service.

Parameters:

observability (ObservabilityProtocol) –

The service for logging events.

Source code in src/bijux_cli/infra/telemetry.py

@inject
def __init__(self, observability: ObservabilityProtocol):
    """Initializes the `LoggingTelemetry` service.

    Args:
        observability (ObservabilityProtocol): The service for logging events.
    """
    self._obs = observability
    self._buffer: list[tuple[str, dict[str, Any]]] = []

enable ¶

enable() -> None

Performs a no-op enable operation.

Source code in src/bijux_cli/infra/telemetry.py

def enable(self) -> None:
    """Performs a no-op enable operation."""
    return

event ¶

event(
    name: str | TelemetryEvent, payload: dict[str, Any]
) -> None

Logs a telemetry event at the 'debug' level.

Parameters:

name (str | TelemetryEvent) –

The event name or enum member.
payload (dict[str, Any]) –

The event data dictionary.

Returns:

None ( None ) –

Source code in src/bijux_cli/infra/telemetry.py

def event(self, name: str | TelemetryEvent, payload: dict[str, Any]) -> None:
    """Logs a telemetry event at the 'debug' level.

    Args:
        name (str | TelemetryEvent): The event name or enum member.
        payload (dict[str, Any]): The event data dictionary.

    Returns:
        None:
    """
    event_name = name.value if isinstance(name, TelemetryEvent) else name
    self._obs.log("debug", f"Telemetry event: {event_name}", extra=payload)
    self._buffer.append((event_name, payload))

flush ¶

flush() -> None

Clears the internal buffer of telemetry events.

Source code in src/bijux_cli/infra/telemetry.py

def flush(self) -> None:
    """Clears the internal buffer of telemetry events."""
    self._buffer.clear()

NullTelemetry ¶

Bases: TelemetryProtocol

A no-op telemetry service that discards all events.

This implementation of TelemetryProtocol can be used to effectively disable analytics and event tracking.

enable ¶

enable() -> None

Performs a no-op enable operation.

Source code in src/bijux_cli/infra/telemetry.py

def enable(self) -> None:
    """Performs a no-op enable operation."""
    return

event ¶

event(
    name: str | TelemetryEvent, payload: dict[str, Any]
) -> None

Discards the telemetry event.

Parameters:

name (str | TelemetryEvent) –

The event name (ignored).
payload (dict[str, Any]) –

The event data (ignored).

Returns:

None ( None ) –

Source code in src/bijux_cli/infra/telemetry.py

def event(self, name: str | TelemetryEvent, payload: dict[str, Any]) -> None:
    """Discards the telemetry event.

    Args:
        name (str | TelemetryEvent): The event name (ignored).
        payload (dict[str, Any]): The event data (ignored).

    Returns:
        None:
    """
    return

flush ¶

flush() -> None

Performs a no-op flush operation.

Source code in src/bijux_cli/infra/telemetry.py

def flush(self) -> None:
    """Performs a no-op flush operation."""
    return

TelemetryEvent ¶

Bases: str, Enum

Defines standardized telemetry event names for tracking CLI activities.