class Logit::Tracer

Overview

Routes log events to registered backends.

The Tracer is responsible for:

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

Defined in:

logit/tracing/tracer.cr

Constructors

Class Method Summary

Instance Method Summary

Constructor Detail

def self.default : Tracer #

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.


[View source]
def self.new(name : String) #

Creates a new tracer with the given name.


[View source]

Class Method Detail

def self.default=(tracer : Tracer) #

Sets the default tracer.

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


[View source]
def self.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.


[View source]
def self.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

[View source]

Instance Method Detail

def 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.


[View source]
def backends : Array(Backend) #

The backends registered with this tracer.


[View source]
def backends=(backends : Array(Backend)) #

The backends registered with this tracer.


[View source]
def close : Nil #

Closes all backends and releases resources.

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


[View source]
def 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.


[View source]
def flush : Nil #

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.


[View source]
def name : String #

The name of this tracer.


[View source]
def name=(name : String) #

The name of this tracer.


[View source]
def remove_backend(name : String) : Nil #

Removes a backend by name.

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


[View source]