module Logit::API

Overview

Direct logging methods for libraries and manual instrumentation.

These methods provide a Crystal Log-like API for targeted logging when annotations aren't appropriate (e.g., libraries, ORMs, HTTP clients).

Lazy Evaluation

Like Crystal's Log library, these methods support lazy evaluation via blocks:

# Eager evaluation - string always computed
Logit.debug("Processing #{expensive_operation()}")

# Lazy evaluation - block only executed if logging is enabled
Logit.debug { "Processing #{expensive_operation()}" }

Trace Context Integration

Manual log calls automatically inherit trace context from any active span:

@[Logit::Log]
def process_order(order_id : Int64)
  # This log call inherits the trace_id and span_id from the annotation
  Logit.info { "Starting order processing" }

  validate_order(order_id)

  Logit.info { "Order validation complete" }
end

Usage in Libraries

module MyORM
  def self.execute_query(sql : String) : Array(Result)
    # Lazy debug log - only computed if debug enabled
    Logit.debug { "Executing query: #{sql}" }

    results = DB.query(sql)

    # Lazy info log with structured data
    Logit.info { "Query returned #{results.size} rows" }

    results
  rescue ex : DB::Error
    # Log exceptions with full context
    Logit.exception("Database query failed", ex)
    raise ex
  end
end

Structured Attributes

You can add structured attributes to log messages:

Logit.warn("Slow query detected",
  duration_ms: 450,
  query: sql,
  table: "users"
)

Extended Modules

• Logit::API

Defined in:

Instance Method Summary

• #debug(message : String, **kwargs) : Nil

  Logs a message at Debug level.

• #debug(**kwargs, &block : -> String) : Nil

  Logs a message at Debug level with lazy evaluation.

• #error(message : String, **kwargs) : Nil

  Logs a message at Error level.

• #error(**kwargs, &block : -> String) : Nil

  Logs a message at Error level with lazy evaluation.

• #exception(message : String, ex : Exception, level : LogLevel, **kwargs) : Nil

  Logs an exception at a specific level.

• #exception(message : String, ex : Exception, **kwargs) : Nil

  Logs an exception with full details.

• #fatal(message : String, **kwargs) : Nil

  Logs a message at Fatal level.

• #fatal(**kwargs, &block : -> String) : Nil

  Logs a message at Fatal level with lazy evaluation.

• #info(message : String, **kwargs) : Nil

  Logs a message at Info level.

• #info(**kwargs, &block : -> String) : Nil

  Logs a message at Info level with lazy evaluation.

• #trace(message : String, **kwargs) : Nil

  Logs a message at Trace level.

• #trace(**kwargs, &block : -> String) : Nil

  Logs a message at Trace level with lazy evaluation.

• #warn(message : String, **kwargs) : Nil

  Logs a message at Warn level.

• #warn(**kwargs, &block : -> String) : Nil

  Logs a message at Warn level with lazy evaluation.

Instance Method Detail

begin
  risky_operation
rescue ex : SomeError
  Logit.exception("Operation failed", ex)
  raise ex
end

Logit.trace("Direct message")
Logit.trace { "Lazy message: #{expensive()}" }