Skip to content
v0.1.3

Observability Module API Reference

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

bijux_cli.contracts.observability

Defines the contract for the structured logging and observability service.

This module specifies the ObservabilityProtocol, a formal interface that any service providing structured logging capabilities must implement. It ensures a consistent API for configuring loggers, binding contextual data, and emitting log messages throughout the application.

ObservabilityProtocol

Bases: Protocol

Defines the contract for a structured logging facade.

This interface specifies methods for configuring logging, binding contextual data, and emitting log messages in a structured format.

bind 

bind(**_kv: Any) -> Self

Binds context key-value pairs to the logger for future log entries.

Parameters:

  • **_kv (Any, default: {} ) –

    Key-value pairs to bind to the logging context.

Returns:

  • Self ( Self ) –

    The service instance, allowing for method chaining.

Source code in src/bijux_cli/contracts/observability.py 
50
51
52
53
54
55
56
57
58
59
def bind(self, **_kv: Any) -> Self:
    """Binds context key-value pairs to the logger for future log entries.

    Args:
        **_kv (Any): Key-value pairs to bind to the logging context.

    Returns:
        Self: The service instance, allowing for method chaining.
    """
    ...

close 

close() -> None

Closes the logger and releases any associated resources.

Source code in src/bijux_cli/contracts/observability.py 
81
82
83
def close(self) -> None:
    """Closes the logger and releases any associated resources."""
    ...

get_logger 

get_logger() -> FilteringBoundLogger | None

Returns the underlying logger instance.

Returns:

  • FilteringBoundLogger | None –

    FilteringBoundLogger | None: The logger instance (e.g., from structlog) or None if it has not been configured.

Source code in src/bijux_cli/contracts/observability.py 
41
42
43
44
45
46
47
48
def get_logger(self) -> FilteringBoundLogger | None:
    """Returns the underlying logger instance.

    Returns:
        FilteringBoundLogger | None: The logger instance (e.g., from
            `structlog`) or None if it has not been configured.
    """
    ...

log 

log(
    level: str,
    msg: str,
    *,
    extra: dict[str, Any] | None = None,
) -> Self

Logs a message with the specified level and context.

Parameters:

  • level (str) –

    The log level (e.g., 'debug', 'info', 'error').

  • msg (str) –

    The message to log.

  • extra (dict[str, Any] | None, default: None ) –

    An optional dictionary of additional context to include in the log entry.

Returns:

  • Self ( Self ) –

    The service instance, allowing for method chaining.

Source code in src/bijux_cli/contracts/observability.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
def log(
    self,
    level: str,
    msg: str,
    *,
    extra: dict[str, Any] | None = None,
) -> Self:
    """Logs a message with the specified level and context.

    Args:
        level (str): The log level (e.g., 'debug', 'info', 'error').
        msg (str): The message to log.
        extra (dict[str, Any] | None): An optional dictionary of
            additional context to include in the log entry.

    Returns:
        Self: The service instance, allowing for method chaining.
    """
    ...

set_telemetry 

set_telemetry(telemetry: TelemetryProtocol) -> Self

Sets the telemetry service instance for integration.

Parameters:

Returns:

  • Self ( Self ) –

    The service instance, allowing for method chaining.

Source code in src/bijux_cli/contracts/observability.py 
85
86
87
88
89
90
91
92
93
94
def set_telemetry(self, telemetry: TelemetryProtocol) -> Self:
    """Sets the telemetry service instance for integration.

    Args:
        telemetry (TelemetryProtocol): An instance of the telemetry service.

    Returns:
        Self: The service instance, allowing for method chaining.
    """
    ...

setup classmethod 

setup(*, debug: bool = False) -> Self

Creates and configures a new instance of the observability service.

Parameters:

  • debug (bool, default: False ) –

    If True, configures the logger for debug-level output.

Returns:

  • Self ( Self ) –

    A new, configured instance of the service.

Source code in src/bijux_cli/contracts/observability.py 
29
30
31
32
33
34
35
36
37
38
39
@classmethod
def setup(cls, *, debug: bool = False) -> Self:
    """Creates and configures a new instance of the observability service.

    Args:
        debug (bool): If True, configures the logger for debug-level output.

    Returns:
        Self: A new, configured instance of the service.
    """
    ...