{"id":16865938,"url":"https://github.com/lukemathwalker/tracing-bunyan-formatter","last_synced_at":"2025-05-15T08:07:57.371Z","repository":{"id":38196380,"uuid":"260934527","full_name":"LukeMathWalker/tracing-bunyan-formatter","owner":"LukeMathWalker","description":"A Layer implementation for tokio-rs/tracing providing Bunyan formatting for events and spans.","archived":false,"fork":false,"pushed_at":"2024-11-26T14:17:25.000Z","size":258,"stargazers_count":93,"open_issues_count":11,"forks_count":36,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-03T04:09:08.996Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LukeMathWalker.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-03T13:58:34.000Z","updated_at":"2025-03-27T09:47:25.000Z","dependencies_parsed_at":"2025-01-15T07:03:21.869Z","dependency_job_id":"ebb11b56-b8e2-4858-8bc5-15f9b490dde6","html_url":"https://github.com/LukeMathWalker/tracing-bunyan-formatter","commit_stats":{"total_commits":79,"total_committers":15,"mean_commits":5.266666666666667,"dds":0.5443037974683544,"last_synced_commit":"8c0ed4353f2cca2d2d878f9f1cf173c918b61a42"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukeMathWalker%2Ftracing-bunyan-formatter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukeMathWalker%2Ftracing-bunyan-formatter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukeMathWalker%2Ftracing-bunyan-formatter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukeMathWalker%2Ftracing-bunyan-formatter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LukeMathWalker","download_url":"https://codeload.github.com/LukeMathWalker/tracing-bunyan-formatter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248166865,"owners_count":21058481,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-13T14:48:56.756Z","updated_at":"2025-04-10T06:20:03.649Z","avatar_url":"https://github.com/LukeMathWalker.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003etracing-bunyan-formatter\u003c/h1\u003e\n\u003cdiv align=\"center\"\u003e\n \u003cstrong\u003e\n   Bunyan formatting for tokio-rs/tracing.\n \u003c/strong\u003e\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003c!-- Crates version --\u003e\n  \u003ca href=\"https://crates.io/crates/tracing-bunyan-formatter\"\u003e\n    \u003cimg src=\"https://img.shields.io/crates/v/tracing-bunyan-formatter.svg?style=flat-square\"\n    alt=\"Crates.io version\" /\u003e\n  \u003c/a\u003e\n  \u003c!-- Downloads --\u003e\n  \u003ca href=\"https://crates.io/crates/tracing-bunyan-formatter\"\u003e\n    \u003cimg src=\"https://img.shields.io/crates/d/tracing-bunyan-formatter.svg?style=flat-square\"\n      alt=\"Download\" /\u003e\n  \u003c/a\u003e\n  \u003c!-- docs.rs docs --\u003e\n  \u003ca href=\"https://docs.rs/tracing-bunyan-formatter\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square\"\n      alt=\"docs.rs docs\" /\u003e\n  \u003c/a\u003e\n  \u003c!-- CI --\u003e\n  \u003ca href=\"https://github.com/LukeMathWalker/tracing-bunyan-formatter\"\u003e\n    \u003cimg src=\"https://circleci.com/gh/LukeMathWalker/tracing-bunyan-formatter.svg?style=shield\" alt=\"CircleCI badge\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\u003cbr/\u003e\n\n`tracing-bunyan-formatter` provides two [`Layer`]s implementation to be used on top of\na [`tracing`] [`Subscriber`]:\n- [`JsonStorageLayer`], to attach contextual information to spans for ease of consumption by\n  downstream [`Layer`]s, via [`JsonStorage`] and [`Span`]'s [`extensions`](https://docs.rs/tracing-subscriber/0.2.5/tracing_subscriber/registry/struct.ExtensionsMut.html);\n- [`BunyanFormattingLayer`], which emits a [bunyan](https://github.com/trentm/node-bunyan)-compatible formatted record upon entering a span,\n exiting a span and event creation.\n\n**Important**: each span will inherit all fields and properties attached to its parent - this is\ncurrently not the behaviour provided by [`tracing_subscriber::fmt::Layer`](https://docs.rs/tracing-subscriber/0.2.5/tracing_subscriber/fmt/struct.Layer.html).\n\n## Example\n\n```rust\nuse tracing_bunyan_formatter::{BunyanFormattingLayer, JsonStorageLayer};\nuse tracing::instrument;\nuse tracing::info;\nuse tracing_subscriber::Registry;\nuse tracing_subscriber::layer::SubscriberExt;\n\n#[instrument]\npub fn a_unit_of_work(first_parameter: u64) {\n    for i in 0..2 {\n        a_sub_unit_of_work(i);\n    }\n    info!(excited = \"true\", \"Tracing is quite cool!\");\n}\n\n#[instrument]\npub fn a_sub_unit_of_work(sub_parameter: u64) {\n    info!(\"Events have the full context of their parent span!\");\n}\n\nfn main() {\n    let formatting_layer = BunyanFormattingLayer::new(\"tracing_demo\".into(), std::io::stdout);\n    let subscriber = Registry::default()\n        .with(JsonStorageLayer)\n        .with(formatting_layer);\n    tracing::subscriber::set_global_default(subscriber).unwrap();\n\n    info!(\"Orphan event without a parent span\");\n    a_unit_of_work(2);\n}\n```\n\n## Console output\n\n\u003cdiv\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/LukeMathWalker/tracing-bunyan-formatter/master/images/ConsoleOutput.png\" /\u003e\n\u003c/div\u003e\n\u003chr/\u003e\n\nIf you pipe the output in the [`bunyan`](https://github.com/trentm/node-bunyan) CLI:\n\u003cdiv\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/LukeMathWalker/tracing-bunyan-formatter/master/images/ConsoleBunyanOutput.png\" /\u003e\n\u003c/div\u003e\n\u003chr/\u003e\n\nAs a pure-Rust alternative check out the [`bunyan` crate](https://crates.io/crates/bunyan).\nIt includes a CLI binary with similar functionality to the original `bunyan` CLI written in\nJavaScript.\n\n\n## Implementation strategy\n\nThe layered approach we have pursued is not necessarily the most efficient,\nbut it makes it easier to separate different concerns and re-use common logic across multiple [`Layer`]s.\n\nWhile the current crate has no ambition to provide any sort of general purpose framework on top of\n[`tracing-subscriber`]'s [`Layer`] trait, the information collected by [`JsonStorageLayer`] can be leveraged via\nits public API by other downstream layers outside of this crate whose main concern is formatting.\nIt significantly lowers the amount of complexity you have to deal with if you are interested\nin implementing your own formatter, for whatever reason or purpose.\n\nYou can also add another enrichment layer following the [`JsonStorageLayer`] to collect\nadditional information about each span and store it in [`JsonStorage`].\nWe could have pursued this compositional approach to add `elapsed_milliseconds` to each span\ninstead of baking it in [`JsonStorage`] itself.\n\n## Optional features\n\nYou can enable the `arbitrary_precision` feature to handle numbers of arbitrary size losslessly. Be aware of a [known issue with untagged deserialization](https://github.com/LukeMathWalker/tracing-bunyan-formatter/issues/4).\n\n### `valuable`\n\nThe `tracing` crate has an unstable feature `valuable` to enable\nrecording custom composite types like `struct`s and `enum`s. Custom\ntypes must implement the [`valuable`\ncrate](https://crates.io/crates/valuable)'s `Valuable` trait, which\ncan be derived with a macro.\n\nTo use `tracing` and `tracing-bunyan-formatter` with `valuable`, you must set the following configuration in your binary (as of the current crate versions on 2023-03-29):\n\n1. Enable the feature flag `valuable` for the `tracing` dependency.\n2. Add the `--cfg tracing_unstable` arguments to your rustc\n   flags (see [`tracing`'s documentation on this][tracing_unstable]).\n   This can be done in a few ways:\n    1. Adding the arguments to your binary package's\n       `.cargo/config.toml` under `build.rustflags`. See the\n       [`cargo` config reference documentation][cargo_build_rustflags]).\n\n       Example:\n\n       ```toml\n       [build]\n       rustflags = \"--cfg tracing_unstable\"\n       ```\n\n    2. Adding the arguments to the `RUSTFLAGS` environment variable when you\n       run `cargo`. See the [`cargo` environment variable\n       docs][cargo_env_vars]).\n\n       Example:\n       ```sh\n       RUSTFLAGS=\"--cfg tracing_unstable\" cargo build\n       ```\n\n3. Enable the feature flag `valuable` for the `tracing-bunyan-formatter` dependency.\n4. Add dependency `valuable`.\n5. Optional: if you want to derive the `Valuable` trait for your\n   custom types, enable the feature flag `derive` for the `valuable`\n   dependency.\n\nSee more details in the example in [`examples/valuable.rs`](examples/valuable.rs).\n\n[cargo_build_rustflags]: https://doc.rust-lang.org/cargo/reference/config.html#buildrustflags\n[cargo_env_vars]: https://doc.rust-lang.org/cargo/reference/environment-variables.html\n[tracing_unstable]: https://docs.rs/tracing/0.1.37/tracing/index.html#unstable-features\n\n## Testing\n\nJust run `cargo test`.\n\nTo run extra tests with the `valuable` feature enabled, run:\n\n```sh\nRUSTFLAGS='--cfg tracing_unstable' \\\ncargo test --target-dir target/debug_valuable --features \"valuable valuable/derive\"\n\nRUSTFLAGS='--cfg tracing_unstable' \\\ncargo run --example valuable --target-dir target/debug_valuable --features \"valuable valuable/derive\"\n```\n\n[`Layer`]: https://docs.rs/tracing-subscriber/0.2.5/tracing_subscriber/layer/trait.Layer.html\n[`JsonStorageLayer`]: https://docs.rs/tracing-bunyan-formatter/0.1.6/tracing_bunyan_formatter/struct.JsonStorageLayer.html\n[`JsonStorage`]: https://docs.rs/tracing-bunyan-formatter/0.1.6/tracing_bunyan_formatter/struct.JsonStorage.html\n[`BunyanFormattingLayer`]: https://docs.rs/tracing-bunyan-formatter/0.1.6/tracing_bunyan_formatter/struct.BunyanFormattingLayer.html\n[`Span`]: https://docs.rs/tracing/0.1.13/tracing/struct.Span.html\n[`Subscriber`]: https://docs.rs/tracing-core/0.1.10/tracing_core/subscriber/trait.Subscriber.html\n[`tracing`]: https://docs.rs/tracing\n[`tracing-subscriber`]: https://docs.rs/tracing-subscriber\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukemathwalker%2Ftracing-bunyan-formatter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flukemathwalker%2Ftracing-bunyan-formatter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukemathwalker%2Ftracing-bunyan-formatter/lists"}