Skip to content

log

Global tracing implementation for open telemetry, console and file sinks.

GlobalLog(service_name, service_version, console=None, otlp=None, file=None)

Initialize logs, traces/spans and metrics for a project.

Logging: normal .debug()/.info()/.warn() etc methods available.

Tracing/spans: .span() can be used to create a new span, or as a decorator to wrap functions.

Metrics: .get_meter() can be used.

Auto-instrumentation: self.meter_provider/tracer_provider/logger_provider are exposed from the instance to allow interaction with auto instrumentation libraries.

If open telemetry used, is opinionated in the fact it should be speaking to a local collector via grpc insecurely on localhost with no headers, only the port can be configured. The collector itself should be post-processing speaking to the outside world, to minimise tracing's impact on this program's performance.

Source code in py/bitbazaar/log/_global_log.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
def __init__(
    self,
    service_name: str,
    service_version: str,
    console: ConsoleSink | None = None,
    otlp: OLTPSink | None = None,
    file: FileSink | None = None,
):
    """Initialize logs, traces/spans and metrics for a project.

    Logging: normal `.debug()/.info()/.warn()` etc methods available.

    Tracing/spans: `.span()` can be used to create a new span, or as a decorator to wrap functions.

    Metrics: `.get_meter()` can be used.

    Auto-instrumentation: `self.meter_provider/tracer_provider/logger_provider` are exposed from the instance to allow interaction with auto instrumentation libraries.

    If open telemetry used, is opinionated in the fact it should be speaking to a local collector via grpc insecurely on localhost with no headers, only the port can be configured.
    The collector itself should be post-processing speaking to the outside world, to minimise tracing's impact on this program's performance.
    """
    (
        self.meter_provider,
        self.tracer_provider,
        self.logger_provider,
        self.file_handler,
    ) = prepare_providers(
        {
            "service_name": service_name,
            "service_version": service_version,
            "console": console,
            "otlp": otlp,
            "file": file,
        }
    )
    self.tracer = trace.get_tracer("GlobalLog")

    # Register as the global logger:
    global _LOG
    _LOG = self

flush()

Force all logs/spans through, useful when testing.

Source code in py/bitbazaar/log/_global_log.py 
188
189
190
191
192
193
194
def flush(self) -> None:
    """Force all logs/spans through, useful when testing."""
    self.tracer_provider.force_flush()
    self.logger_provider.force_flush()
    self.meter_provider.force_flush()
    if self.file_handler:
        self.file_handler.flush()

shutdown()

Shuts/closes everything down.

Source code in py/bitbazaar/log/_global_log.py 
196
197
198
199
200
201
202
def shutdown(self) -> None:
    """Shuts/closes everything down."""
    self.tracer_provider.shutdown()
    self.logger_provider.shutdown()
    self.meter_provider.shutdown()
    if self.file_handler:
        self.file_handler.close()

span(name, context=None, kind=SpanKind.INTERNAL, attributes=None, links=None, start_time=None, record_exception=True, set_status_on_exception=True, end_on_exit=True)

Context manager for creating a new span and set it as the current span in this tracer's context.

Exiting the context manager will call the span's end method, as well as return the current span to its previous value by returning to the previous context.

Example::

with tracer.start_as_current_span("one") as parent:
    parent.add_event("parent's event")
    with tracer.start_as_current_span("two") as child:
        child.add_event("child's event")
        trace.get_current_span()  # returns child
    trace.get_current_span()      # returns parent
trace.get_current_span()          # returns previously active span

This is a convenience method for creating spans attached to the tracer's context. Applications that need more control over the span lifetime should use :meth:start_span instead. For example::

with tracer.start_as_current_span(name) as span:
    do_work()

is equivalent to::

span = tracer.start_span(name)
with opentelemetry.trace.use_span(span, end_on_exit=True):
    do_work()

This can also be used as a decorator::

@tracer.start_as_current_span("name")
def function():
    ...

function()

Parameters:

Name Type Description Default
name str

The name of the span to be created.

 required
context Context | None

An optional Context containing the span's parent. Defaults to the global context.

 None
kind SpanKind

The span's kind (relationship to parent). Note that is meaningful even if there is no parent.

 INTERNAL
attributes Attributes

The span's attributes.

 None
links _Links

Links span to other spans

 None
start_time int | None

Sets the start time of a span

 None
record_exception bool

Whether to record any exceptions raised within the context as error event on the span.

 True
set_status_on_exception bool

Only relevant if the returned span is used in a with/context manager. Defines whether the span status will be automatically set to ERROR when an uncaught exception is raised in the span with block. The span status won't be set by this mechanism if it was previously set manually.

 True
end_on_exit bool

Whether to end the span automatically when leaving the context manager.

 True

Yields:

Type Description

The newly-created span.
Source code in py/bitbazaar/log/_global_log.py 
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
def span(
    self,
    name: str,
    context: Context | None = None,
    kind: SpanKind = SpanKind.INTERNAL,
    attributes: Attributes = None,
    links: _Links = None,
    start_time: int | None = None,
    record_exception: bool = True,
    set_status_on_exception: bool = True,
    end_on_exit: bool = True,
):
    """Context manager for creating a new span and set it as the current span in this tracer's context.

    Exiting the context manager will call the span's end method,
    as well as return the current span to its previous value by
    returning to the previous context.

    Example::

        with tracer.start_as_current_span("one") as parent:
            parent.add_event("parent's event")
            with tracer.start_as_current_span("two") as child:
                child.add_event("child's event")
                trace.get_current_span()  # returns child
            trace.get_current_span()      # returns parent
        trace.get_current_span()          # returns previously active span

    This is a convenience method for creating spans attached to the
    tracer's context. Applications that need more control over the span
    lifetime should use :meth:`start_span` instead. For example::

        with tracer.start_as_current_span(name) as span:
            do_work()

    is equivalent to::

        span = tracer.start_span(name)
        with opentelemetry.trace.use_span(span, end_on_exit=True):
            do_work()

    This can also be used as a decorator::

        @tracer.start_as_current_span("name")
        def function():
            ...

        function()

    Args:
        name: The name of the span to be created.
        context: An optional Context containing the span's parent. Defaults to the
            global context.
        kind: The span's kind (relationship to parent). Note that is
            meaningful even if there is no parent.
        attributes: The span's attributes.
        links: Links span to other spans
        start_time: Sets the start time of a span
        record_exception: Whether to record any exceptions raised within the
            context as error event on the span.
        set_status_on_exception: Only relevant if the returned span is used
            in a with/context manager. Defines whether the span status will
            be automatically set to ERROR when an uncaught exception is
            raised in the span with block. The span status won't be set by
            this mechanism if it was previously set manually.
        end_on_exit: Whether to end the span automatically when leaving the
            context manager.

    Yields:
        The newly-created span.
    """
    return self.tracer.start_as_current_span(
        name,
        context,
        kind,
        attributes,
        links,
        start_time,
        record_exception,
        set_status_on_exception,
        end_on_exit,
    )
Last update: August 7, 2024
Created: August 7, 2024