module

Logit

Logit - Annotation-based logging with OpenTelemetry support for Crystal.

Logit provides automatic method instrumentation through annotations, structured logging with wide events, and full OpenTelemetry compatibility. Simply annotate methods with @[Logit::Log] and Logit handles the rest.

Quick Start

require "logit"

# Configure Logit (optional - defaults to console output)
Logit.configure do |config|
  config.console(level: Logit::LogLevel::Debug)
end

class MyService
  @[Logit::Log]
  def process(data : String) : String
    data.upcase
  end
end

Annotation Options

The @[Logit::Log] annotation supports the following options:

  • log_args (Bool) - Whether to log method arguments (default: true, or LOG_ARGS_DEFAULT if defined)
  • log_return (Bool) - Whether to log return values (default: true, or LOG_RETURN_DEFAULT if defined)
  • log_exception (Bool) - Whether to log exceptions (default: true, or LOG_EXCEPTION_DEFAULT if defined)
  • name (String) - Custom span name (default: method name)
  • level (LogLevel) - Log level for this method (default: Info)
  • redact (Array(String)) - Argument names to redact from logs

Key Features

  • Automatic instrumentation: No manual log calls needed
  • OpenTelemetry semantics: Trace IDs, span IDs, and semantic attributes
  • Fiber-aware context: Spans are tracked per-fiber for safe concurrency
  • Flexible backends: Console, file, or custom backends
  • Namespace filtering: Control log levels per namespace pattern
  • Redaction support: Automatically redact sensitive data

See Logit.configure for configuration options and Logit::Backend for available output backends.

Constants

VERSION = "0.1.0"

Class methods

add_context(hash : Hash(String, String)) : Nil

Adds method-local context from a hash.

Source
add_context(named_tuple : NamedTuple) : Nil

Adds method-local context from a named tuple.

Source
add_context

Adds method-local context that is cleared after the current method completes.

@[Logit::Log]
def process(item : Item) : Bool
  Logit.add_context(item_type: item.type)
  # ... context is included in this method's log event
  true
end  # context cleared here
Source
add_fiber_context(hash : Hash(String, String)) : Nil

Adds fiber-local context from a hash.

Source
add_fiber_context(named_tuple : NamedTuple) : Nil

Adds fiber-local context from a named tuple.

Source
add_fiber_context

Adds fiber-local context that persists across method calls in this fiber.

Use this for request-scoped data like request IDs or user information.

# At the start of a request
Logit.add_fiber_context(request_id: request.id, user_id: current_user.id)

# All logs in this fiber now include request_id and user_id
process_request
save_data

# At the end of the request
Logit.clear_fiber_context
Source
clear_context

Clears all method-local context.

Source
clear_fiber_context

Clears all fiber-local context.

Source
configure

Configures Logit with the provided block and applies the configuration.

This is the main entry point for setting up Logit. The configuration is applied immediately after the block completes.

Logit.configure do |config|
  config.console(level: Logit::LogLevel::Debug)
  config.file("logs/app.log")
  config.redact_common_patterns
end

If you don't call configure, Logit uses a default console backend at Info level.

Source
debug(message : String, **kwargs) : Nil

Logs a message at Debug level.

Source
debug

Logs a message at Debug level with lazy evaluation.

Source
error(message : String, **kwargs) : Nil

Logs a message at Error level.

Source
error

Logs a message at Error level with lazy evaluation.

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

Logs an exception at a specific level.

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

Logs an exception with full details at Error level.

Source
fatal(message : String, **kwargs) : Nil

Logs a message at Fatal level.

Source
fatal

Logs a message at Fatal level with lazy evaluation.

Source
get_context(key : String) : String | Nil

Gets a method-local context value.

Source
get_fiber_context(key : String) : String | Nil

Gets a fiber-local context value.

Source
info(message : String, **kwargs) : Nil

Logs a message at Info level.

Source
info

Logs a message at Info level with lazy evaluation.

Source
trace(message : String, **kwargs) : Nil

Logs a message at Trace level.

Source
trace

Logs a message at Trace level with lazy evaluation.

Source
warn(message : String, **kwargs) : Nil

Logs a message at Warn level.

Source
warn

Logs a message at Warn level with lazy evaluation.

Source

Macros

logit_add_context

Add key-value pairs to the current logging context

Source
logit_with_context

Execute a block with additional context that is automatically removed after

Source
setup_instrumentation(type_name)

Setup macro to be called at the END of a class definition (for manual instrumentation) This generates wrapper methods for all @Log annotated methods Note: In most cases, you should rely on the global macro finished hook instead

Source

Nested types