class

Logit::Tracer

Inherits Reference / Object

Routes log events to registered backends.

The Tracer is responsible for:

  • Managing a collection of backends
  • Emitting events to all applicable backends
  • Providing error isolation (one backend failure doesn't affect others)
  • Thread-safe backend management

Most applications use the default tracer, which is set up automatically by Logit.configure. You typically don't need to interact with the Tracer directly.

Default Tracer

The default tracer is used by all instrumented methods:

# Get the default tracer
tracer = Logit::Tracer.default

# Check if logging is enabled at a level
if Logit::Tracer.should_emit?(Logit::LogLevel::Debug)
  # ... expensive debug operation
end

Custom Tracers

For advanced use cases, you can create named tracers:

Logit.configure do |config|
  tracer = Logit::Tracer.new("audit")
  tracer.add_backend(Logit::Backend::File.new("audit.log"))
  config.add_tracer("audit", tracer)
end

Constructors

default

Returns the default tracer.

If no tracer has been configured via Logit.configure, creates a default tracer with a Backend::Null that discards all events.

This ensures libraries using Logit don't impose logging on applications. Applications can enable logging by calling Logit.configure with the desired backends.

Source
new(name : String)

Creates a new tracer with the given name.

Source

Class methods

default=(tracer : Tracer)

Sets the default tracer.

Called automatically by Logit.configure. You typically don't need to call this directly.

Source
should_emit?(level : LogLevel, namespace : String) : Bool

Checks if any backend will emit at this level for a specific namespace.

Takes namespace bindings into account for more precise early filtering.

Source
should_emit?(level : LogLevel) : Bool

Checks if any backend will emit at this level.

Use this for early filtering to avoid expensive operations when logging is disabled at a particular level.

if Logit::Tracer.should_emit?(Logit::LogLevel::Debug)
  # Only compute expensive debug info if it will be logged
  debug_info = compute_expensive_debug_info
end
Source

Instance methods

add_backend(backend : Backend) : Nil

Adds a backend to this tracer.

Thread-safe. The backend will receive all events emitted to this tracer that pass its level and namespace filters.

Source
backends

The backends registered with this tracer.

Source
backends=(backends : Array(Backend))

The backends registered with this tracer.

Source
close

Closes all backends and releases resources.

Call this during application shutdown to ensure log files are properly closed and all data is flushed.

Source
emit(event : Event) : Nil

Emits an event to all registered backends.

Each backend decides whether to log the event based on its level and namespace bindings. Backend failures are isolated - if one backend fails, others still receive the event.

Source
flush

Flushes all backends.

Call this to ensure buffered log data is written. Useful before application shutdown or when you need logs to be immediately visible.

Source
name

The name of this tracer.

Source
name=(name : String)

The name of this tracer.

Source
remove_backend(name : String) : Nil

Removes a backend by name.

Thread-safe. The backend will no longer receive events.

Source