这是一个简单、强大且非常快速的日志记录工具,可以作为 Logger 的替代方案。它支持自动滚动日志文件、格式化日志等功能。
Lumberjack is an extension to the Ruby standard library Logger class, designed to provide advanced, flexible, and structured logging for Ruby applications. It builds on the familiar Logger API, adding powerful features for modern logging needs:
The philosophy behind the library is to promote use of structured logging with the standard Ruby Logger API as a foundation. The developer of a piece of functionality should only need to worry about the data that needs to be logged for that functionality and not how it is logged or formatted. Loggers can be setup with global attributes and formatters that handle these concerns.
Lumberjack provides context isolation that allow you to temporarily modify logging behavior for specific blocks of code or create independent logger instances. This is particularly useful for isolating logging configuration in different parts of your application without affecting the global logger state.
Context blocks allow you to temporarily change the logger's configuration (level, progname, and attributes) for a specific block of code. When the block exits, the logger returns to its previous state.
Context blocks and forked loggers are thread and fiber-safe, maintaining isolation across concurrent operations:
logger.level = :info
# Temporarily change log level for debugging a specific section
logger.context do
logger.level = :debug
logger.debug("This debug message will be logged")
end
# Back to info level - debug messages are filtered out again
logger.debug("This won't be logged")You can use with_level, with_progname, and tag to setup a context block with a specific level, progname, or attributes.
As a best practice, every main unit of work in your application (i.e. HTTP request, background job, etc.) should have a context block. This ensures that any attributes or changes to the logger are scoped to that unit of work and do not leak into other parts of the application.
Context blocks can be nested, with inner contexts inheriting and potentially overriding outer context settings:
logger.context do
logger.tag(user_id: 123, service: "api")
logger.info("API request started") # Includes user_id: 123, service: "api"
logger.context(endpoint: "/users", service: "user_service") do
logger.tag(service: "user_service", endpoint: "/users")
logger.info("Processing user data") # Includes: user_id: 123, service: "user_service", endpoint: "/users"
end
logger.info("API request completed") # Back to: user_id: 123, service: "api"
endLogger forking creates independent logger instances that inherit the parent logger's current context. Changes made to the forked logger will not affect the parent logger.
Forked loggers are useful when there is a section of your application that requires different logging behavior. Forked loggers are cheap to create, so you can use them liberally.
main_logger = Lumberjack::Logger.new
main_logger.tag!(version: "1.0.0")
# Create a forked logger for a specific component
user_service_logger = main_logger.fork(progname: "UserService", level: :debug)
user_service_logger.tag!(component: "user_management")
user_service_logger.debug("Debug info") # Includes version and component attributes
main_logger.info("Main logger info") # Includes only version attribute
main_logger.debug("Main logger debug info") # Not logged since level is :infoBy default each fiber will have its own logging context. This is useful in asynchronous applications where multiple fibers may be running concurrently. You can change the isolation level to :thread if you want each thread to have its own logging context instead.
Lumberjack.isolation_level = :thread # Set isolation level globally
logger = Lumberjack::Logger.new(STDOUT, isolation_level: :thread) # Set isolation level per loggerFiber isolation is the safest behavior since it completely isolates local contexts. However, in applications where threads are the main unit of work and fibers are never shared across threads, thread isolation may be more appropriate. Otherwise you can end up with the logger losing the context block when switching fibers within the same thread.
Lumberjack extends standard logging with attributes (structured key-value pairs) that add context and metadata to your log entries. This enables powerful filtering, searching, and analytics capabilities.
Add attributes with any logging method:
# Add attributes to individual log calls
logger.info("User logged in", user_id: 123, ip_address: "192.168.1.100")
logger.error("Payment failed", user_id: 123, amount: 29.99, error: "card_declined")
# Attributes can be any type
logger.debug("Processing data",
records_count: 1500,
processing_time: 2.34,
metadata: { batch_id: "abc-123", source: "api" },
timestamp: Time.now
)[!Note] Attributes are passed in log statements in the little used
prognameargument that is defined in the standard Ruby Logger API. This attribute is normally used to set a specific program name for the log entry that overrides the default program name on the logger.The only difference in the API is that Lumberjack loggers can take a Hash to set attributes instead of just a string. You can still pass a string to override the program name.
Use the tag method to tag the the current context with attributes. The attributes will be included in all log entries within that context.
logger.context do
logger.tag(user_id: current_user.id, session: "abc-def")
logger.info("Session started") # Includes user_id and session
logger.debug("Loading user preferences") # Includes user_id and session
logger.info("Dashboard rendered") # Includes user_id and session
end
logger.info("Outside of context") # Does not include user_id or sessionYou can also use the tag method with a block to open a new context and assign attributes.
# Apply attributes to all log entries within the block
logger.tag(user_id: 123, session: "abc-def") do
logger.info("Session started")
logger.debug("Loading user preferences")
logger.info("Dashboard rendered")
endCalling tag outside of a context without a block is a no-op and has no effect on the logger.
You can also use the tag_all_contexts method to add attributes to all parent context blocks. This can be useful in cases where you need to set an attribute that should be included in all subsequent log entries for the duration of the process defined by the outermost context.
Consider this example where we want to include the user_id attribute in all log entries. We need to set it on all parent contexts in order to have it extend beyond the current context block.
logger.context do
logger.tag(request_id: "req-123") do
logger.info("Processing request") # Includes request_id
logger.tag(action: "login") do
user_id = login_user(params)
logger.tag(login_method: params[:login_method])
logger.tag_all_contexts(user_id: user_id)
logger.info("User logged in") # Includes request_id, action, login_method, and user_id
end
logger.info("Request completed") # Includes request_id and user_id
endYou can add global attributes that apply to all log entries with the tag! method.
logger.tag!(
version: "1.2.3",
env: Rails.env,
request_id: -> { Current.request_id }
)If the value of an attribute is a Proc, it will be evaluated at runtime when the log entries are created. So in the above example, request_id will be dynamically set to the current request ID whenever a log entry is created.
Note that blank attributes are never included in the log output, so if Current.request_id is nil, the request_id attribute will be omitted from the log entry.
There is also a global Lumberjack context that applies to all Lumberjack loggers.
Lumberjack.tag(version: "1.2.3") do
logger_1.info("Something happened") # Includes version
logger_2.info("Something else happened") # Includes version
endAttributes support nested structures and complex data types:
logger.info("API request completed",
request: {
method: "POST",
path: "/api/users",
headers: { "Content-Type" => "application/json" }
},
response: {
status: 201,
duration_ms: 45.2,
size_bytes: 1024
},
user: {
id: 123,
role: "admin",
permissions: ["read", "write", "delete"]
}
)Attributes from different sources are merged together, with more specific attributes taking precedence:
# Persistent logger attributes
logger.tag!(service: "web", datacenter: "us-east-1")
logger.tag(request_id: "req-123") do
# Block-level attributes override any conflicts
logger.tag(datacenter: "us-west-2") do
logger.info("Processing request",
user_id: 456,
datacenter: "eu-central-1" # This takes highest precedence
)
# Final attributes: { service: "web", request_id: "req-123", user_id: 456, datacenter: "eu-central-1" }
end
endAttributes use dot notation for nested structures, so there is no difference between these statements:
logger.info("User signed in"暂无开放 Issues,或尚未同步最近议题。