{"action":"created","issue":{"url":"https://api.github.com/repos/rust-lang/log/issues/27","labels_url":"https://api.github.com/repos/rust-lang/log/issues/27/labels{/name}","comments_url":"https://api.github.com/repos/rust-lang/log/issues/27/comments","events_url":"https://api.github.com/repos/rust-lang/log/issues/27/events","html_url":"https://github.com/rust-lang/log/pull/27","id":60245383,"number":27,"title":"API overhaul round 2","user":{"login":"sfackler","id":1455697,"avatar_url":"https://avatars.githubusercontent.com/u/1455697?v=3","gravatar_id":"","url":"https://api.github.com/users/sfackler","html_url":"https://github.com/sfackler","followers_url":"https://api.github.com/users/sfackler/followers","following_url":"https://api.github.com/users/sfackler/following{/other_user}","gists_url":"https://api.github.com/users/sfackler/gists{/gist_id}","starred_url":"https://api.github.com/users/sfackler/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sfackler/subscriptions","organizations_url":"https://api.github.com/users/sfackler/orgs","repos_url":"https://api.github.com/users/sfackler/repos","events_url":"https://api.github.com/users/sfackler/events{/privacy}","received_events_url":"https://api.github.com/users/sfackler/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":{"login":"huonw","id":1203825,"avatar_url":"https://avatars.githubusercontent.com/u/1203825?v=3","gravatar_id":"","url":"https://api.github.com/users/huonw","html_url":"https://github.com/huonw","followers_url":"https://api.github.com/users/huonw/followers","following_url":"https://api.github.com/users/huonw/following{/other_user}","gists_url":"https://api.github.com/users/huonw/gists{/gist_id}","starred_url":"https://api.github.com/users/huonw/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/huonw/subscriptions","organizations_url":"https://api.github.com/users/huonw/orgs","repos_url":"https://api.github.com/users/huonw/repos","events_url":"https://api.github.com/users/huonw/events{/privacy}","received_events_url":"https://api.github.com/users/huonw/received_events","type":"User","site_admin":false},"milestone":null,"comments":2,"created_at":"2015-03-08T07:16:14Z","updated_at":"2015-03-08T07:16:40Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/rust-lang/log/pulls/27","html_url":"https://github.com/rust-lang/log/pull/27","diff_url":"https://github.com/rust-lang/log/pull/27.diff","patch_url":"https://github.com/rust-lang/log/pull/27.patch"},"body":"This PR contains a series of commits which add functionality and future-proofing. There are breaking changes for libraries implementing `Log` but not for libraries using the logging macros. I opened this as a PR instead of filing an issue because I think it's a bit easier to talk about when looking at an actual implementation. It deserves some discussion before merging for sure.\r\n\r\n### \"Encapsulate\" `LogLocation` by mangling the field names and making them `#[doc(hidden)]`.\r\nWe may want to add to this struct in the future (maybe function name if that macro ever gets added), or replace the internals with something that extracts information from debuginfo for example. It's a bit suboptimal since we can't actually make the fields private, but I think it's good enough that we can alter the struct backwards compatibly.\r\n\r\n### Remove `LogRecord::new`\r\nI added this because it made it easier to test logger implementations, but it cripples the log crate's ability to add features without breaking backwards compatibility. Logger implementations can restructure a tiny bit to make testing easier (translate a LogRecord to their own internal type for example).\r\n\r\n### Make entry point functions \"private\"\r\nThe `log` and `enabled` functions were previously fully public, which inhibits our ability to add features. I took a similar strategy here as I did for `LogLocation` of mangling the names and marking them `#[doc(hidden)]`.\r\n\r\n### Add the concept of a \"target\" to log directives\r\nMost of the time when logging, using the current module path as the \"target\" for filtering makes sense. However, you sometimes need more fine-grained control over logging messages. For example, consider a \"router\" function in a web server. We want to have normal diagnostic loggging calls, but also provide a request log:\r\n```rust\r\nfn route(url: Request) {\r\n     debug!(\"starting routing for {:?}\", url);\r\n\r\n     match find_handler(&url) {\r\n          Ok(handler) => {\r\n              debug!(\"got handler for {:?}\", url);\r\n              info!(target: \"request_log\", \"{} - {}\", url, handler);\r\n              handler.handle(url);\r\n          }\r\n          Err(err) => error!(\"error routing {:?}\", url),\r\n     }\r\n}\r\n```\r\nThe `debug!` and `error!` calls will end up with a target set to the module path (`app::router` or whatever), but the `info!` call will instead have a target of `request_log`. It's then extremely easy to set up a logging framework like `log4rs` to pipe the `request_log` target to a separate file from the rest of the log output.\r\n\r\n#### Open Question\r\nOne interesting note here is that log4j derived logging implementations call these \"loggers\", not \"targets\". The overall framework is typically called a \"logging context\" I believe. It would be kind of nice to mirror that terminology for familiarity's sake, but it would require a much larger API and documentation change (renaming `set_logger` to `set_context`, etc). Thoughts?\r\n\r\n### Encapsulate data passed to `Log::enabled`\r\nWe were previously passing the log level and module path (now target) to `Log::enabled`. We may want to add more \"selection\" metadata to a log event in the future, however. For example, in slf4j, you can pass `Marker` objects when logging which can provide more flexibility than just tweaking the target would. I'm not familiar enough with them to add them now, but we should at least make sure that we'll be able to."},"comment":{"url":"https://api.github.com/repos/rust-lang/log/issues/comments/77736746","html_url":"https://github.com/rust-lang/log/pull/27#issuecomment-77736746","issue_url":"https://api.github.com/repos/rust-lang/log/issues/27","id":77736746,"user":{"login":"sfackler","id":1455697,"avatar_url":"https://avatars.githubusercontent.com/u/1455697?v=3","gravatar_id":"","url":"https://api.github.com/users/sfackler","html_url":"https://github.com/sfackler","followers_url":"https://api.github.com/users/sfackler/followers","following_url":"https://api.github.com/users/sfackler/following{/other_user}","gists_url":"https://api.github.com/users/sfackler/gists{/gist_id}","starred_url":"https://api.github.com/users/sfackler/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sfackler/subscriptions","organizations_url":"https://api.github.com/users/sfackler/orgs","repos_url":"https://api.github.com/users/sfackler/repos","events_url":"https://api.github.com/users/sfackler/events{/privacy}","received_events_url":"https://api.github.com/users/sfackler/received_events","type":"User","site_admin":false},"created_at":"2015-03-08T07:16:40Z","updated_at":"2015-03-08T07:16:40Z","body":"cc @alexcrichton "}}