{"id":15295132,"url":"https://github.com/kolloch/reqray","last_synced_at":"2025-04-13T15:59:17.579Z","repository":{"id":44033562,"uuid":"323128569","full_name":"kolloch/reqray","owner":"kolloch","description":"Log call tree summaries after each request for rust programs instrumented with `tracing`.","archived":false,"fork":false,"pushed_at":"2022-02-12T21:21:20.000Z","size":298,"stargazers_count":44,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-11T14:34:10.399Z","etag":null,"topics":["calltree","logging","rust","rust-lang","rust-library","tracing","tracing-library"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kolloch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-12-20T17:35:59.000Z","updated_at":"2025-03-29T05:06:39.000Z","dependencies_parsed_at":"2022-09-26T20:31:09.937Z","dependency_job_id":null,"html_url":"https://github.com/kolloch/reqray","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kolloch%2Freqray","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kolloch%2Freqray/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kolloch%2Freqray/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kolloch%2Freqray/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kolloch","download_url":"https://codeload.github.com/kolloch/reqray/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248741198,"owners_count":21154252,"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":["calltree","logging","rust","rust-lang","rust-library","tracing","tracing-library"],"created_at":"2024-09-30T17:08:43.733Z","updated_at":"2025-04-13T15:59:17.559Z","avatar_url":"https://github.com/kolloch.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Reqray\n\n[![Build Status](https://api.travis-ci.com/kolloch/reqray.svg?branch=main\u0026status=started)](https://travis-ci.com/kolloch/reqray)\n[![Crate](https://img.shields.io/crates/v/reqray.svg)](https://crates.io/crates/reqray)\n[![Docs](https://docs.rs/reqray/badge.svg)](https://docs.rs/reqray)\n\nLog \"request x-rays\" for rust programs instrumented with [tracing](https://github.com/tokio-rs/tracing). This\nincludes aggregated wall/own times as frequently found in flame graphs in a human-friendly text format.\n\nTo deploy it, you don't need some complicated services, just some local code added to your instrumented program.\n\nThis makes answers to these question often trivial to answer:\n\n* What part of the request takes the most time?\n* How many DB requests am I performing? Does the DB request aggregation work?\n* How far did the execution get before the error that aborted the request?\n\nIt looks like this:\n\n```\n2022-02-06T20:01:57.103747Z  INFO Call summary of request@examples/nested.rs:51\n\n                        # calls │   ∑ alive ms │    ∑ busy ms │ ∑ own busy ms │ span tree\n                    ────────────┼──────────────┼──────────────┼────────────-──┼───────────────────────\n                          0 001 ┊      258.910 ┊      258.890 ┊         0.106 ┊ ┬ request\n                          0 001 ┊       87.204 ┊       87.190 ┊        19.299 ┊ ├┬ nested\n                          0 001 ┊        0.036 ┊        0.021 ┊         0.021 ┊ ┊├─ random\n                          1 000 ┊       75.738 ┊       61.912 ┊        61.912 ┊ ┊╰─ repeated\n                          0 002 ┊        0.051 ┊        0.027 ┊         0.027 ┊ ├─ repeated\n                          0 001 ┊        1.644 ┊        1.632 ┊         0.019 ┊ ├┬ nest_deeply\n                          0 001 ┊        1.619 ┊        1.607 ┊         0.025 ┊ ┊╰┬ nest_deeply\n                          0 001 ┊        1.593 ┊        1.577 ┊         0.024 ┊ ┊ ╰┬ nest_deeply\n                          0 001 ┊        1.561 ┊        1.547 ┊         0.022 ┊ ┊  ╰┬ nest_deeply\n                          0 001 ┊        1.532 ┊        1.520 ┊         0.023 ┊ ┊   ╰┬ nest_deeply\n                          0 001 ┊        1.504 ┊        1.492 ┊         0.023 ┊ ┊    ╰┬ nest_deeply\n                          0 001 ┊        1.476 ┊        1.463 ┊         0.025 ┊ ┊     ╰┬ nest_deeply\n                          0 001 ┊        1.446 ┊        1.433 ┊         0.025 ┊ ┊      ╰┬ nest_deeply\n                          0 001 ┊        1.415 ┊        1.402 ┊         1.402 ┊ ┊       ╰─ nest_deeply\n                          0 001 ┊      169.915 ┊      169.905 ┊        17.883 ┊ ╰┬ nested2\n                          0 001 ┊        0.010 ┊        0.001 ┊         0.001 ┊  ├─ random\n                          1 000 ┊       88.793 ┊       76.081 ┊        76.081 ┊  ├─ repeated\n                          0 001 ┊       70.386 ┊       70.377 ┊        19.332 ┊  ╰┬ nested\n                          0 001 ┊        0.011 ┊        0.001 ┊         0.001 ┊   ├─ random\n                          1 000 ┊       58.468 ┊       45.280 ┊        45.280 ┊   ╰─ repeated\n```\n\n* **calls**: The total number of spans created at this call path.\n* **∑ alive ms**: The total time spans at this call path were alive i.e. sum of times between new and close events.\n* **∑ busy ms**: The total time spans at this call path were entered i.e. sum of times between enter and leave events.\n* **∑ own busy ms**: The total time spans at this call path were entered without any children entered.\n\nIt looked like this until 0.3.x:\n\n```\nDec 20 18:48:32.405  INFO Call summary of request@examples/nested.rs:47\n\n                        # calls │    ∑ wall ms │     ∑ own ms │ span tree\n                    ────────────┼──────────────┼──────────────┼───────────────────────\n                          0 001 ┊      377.886 ┊        0.260 ┊ ┬ request\n                          0 001 ┊      120.704 ┊       48.896 ┊ ├┬ nested\n                          0 001 ┊        0.008 ┊        0.008 ┊ ┊├─ random\n                          1 000 ┊       64.347 ┊       64.347 ┊ ┊╰─ repeated\n                          0 002 ┊        0.118 ┊        0.118 ┊ ├─ repeated\n                          0 001 ┊        3.818 ┊        0.049 ┊ ├┬ nest_deeply\n                          0 001 ┊        3.762 ┊        0.053 ┊ ┊╰┬ nest_deeply\n                          0 001 ┊        3.702 ┊        0.057 ┊ ┊ ╰┬ nest_deeply\n                          0 001 ┊        3.637 ┊        0.056 ┊ ┊  ╰┬ nest_deeply\n                          0 001 ┊        3.574 ┊        0.058 ┊ ┊   ╰┬ nest_deeply\n                          0 001 ┊        3.503 ┊        0.061 ┊ ┊    ╰┬ nest_deeply\n                          0 001 ┊        3.435 ┊        0.063 ┊ ┊     ╰┬ nest_deeply\n                          0 001 ┊        3.365 ┊        0.066 ┊ ┊      ╰┬ nest_deeply\n                          0 001 ┊        3.292 ┊        3.292 ┊ ┊       ╰─ nest_deeply\n                          0 001 ┊      252.949 ┊       49.258 ┊ ╰┬ nested2\n                          0 001 ┊        0.006 ┊        0.006 ┊  ├─ random\n                          1 000 ┊       63.343 ┊       63.343 ┊  ├─ repeated\n                          0 001 ┊      132.841 ┊       54.091 ┊  ╰┬ nested\n                          0 001 ┊        0.007 ┊        0.007 ┊   ├─ random\n                          1 000 ┊       70.875 ┊       70.875 ┊   ╰─ repeated\n\n```\n\n## Setup\n\nFor a quick startm, add/edit these `[dependencies]` in `Cargo.toml`:\n\n```\ntracing = \"0.1\"\ntracing-subscriber = { version = \"0.3\", features = [\"registry\", \"env-filter\"] }\nreqray = \"0.4\"\n```\n\nAnd add/edit your tracing layer setup:\n\n```rust\n    use reqray::CallTreeCollector;\n    use tracing_subscriber::{EnvFilter, util::SubscriberInitExt, fmt, prelude::*};\n\n    let fmt_layer = fmt::layer()\n        .with_target(false);\n    let filter_layer = EnvFilter::try_from_default_env()\n        .or_else(|_| EnvFilter::try_new(\"info\"))\n        .unwrap();\n\n    tracing_subscriber::registry()\n    // -----------------------------------------------\n        .with(CallTreeCollector::default())\n    // -----------------------------------------------\n        .with(filter_layer)\n        .with(fmt_layer)\n        .init();\n```\n\nInstead of `CallTreeCollector::default()` you can chose a more explicit config:\n\n```rust\n    // ...\n    let call_tree_collector = CallTreeCollectorBuilder::default()\n        .max_call_depth(10)\n        .build_with_collector(\n            LoggingCallTreeCollectorBuilder::default()\n                .left_margin(20)\n                .build(),\n        );\n\n    tracing_subscriber::registry()\n        .with(call_tree_collector)\n        // ...\n```\n\n## Compatibility with `tracing-subscriber 0.2`\n\nUse reqray 0.2.x for integration with tracing-subscriber 0.2.x. Otherwise, the API\nshould be identical.\n\nE.g. `color_eyre` 0.5.x depends on `tracing-error` 0.1.x which requires `tracing-subscriber` 0.2. \n\n## Overhead\n\nI did basic performance testing (see benches) to check for obvious gotchas\n-- I didn't spot any. If your code actually does talk to a database\nor anything expensive, it should be in the same order of magnitude as logging\noverhead with the tracing library in general.\n\nIn my totally unrepresentative example with some log statements which does\nnothing else really, the logging overhead increased by 30-50% -- this is roughly\nthe amount of actual log lines added to the log output in this case.\n\nGenerally, you should only instrument relevant calls in your program not every\none of them, especially not those in a CPU-bound loop. If you have those,\nit might make sense to filter those before the CallTreeCollector is invoked.\n\nI am very curious to hear actual stats in real life programs!\n\n## Inspiration\n\nWhen working together with Klas Kalass, he created something similar for Java:\nthe [Fuava CTProfiler](https://github.com/freiheit-com/fuava_ctprofiler).\n\nIt proved to be immensely useful at a nearly daily basis. Thank you, Klas!\n\nSince then, I have worked with sophisticated distributed tracing systems,\nbut they often lacked aggregation possibilities. Others hacked some interesting\naggregation scripts on top and I myself became somewhat obsessed with creating\nsimilar scripts.\n\n## Thanks\n\nI felt very welcome when I suggested something like this in issue\n[tracing#639](https://github.com/tokio-rs/tracing/issues/639). Thank you, @hawkw!\n\nSimilarly, Eliza was very supportive and helpful in the tracing discod channel.\nThank you, Eliza!\n\n## Contributions\n\nGiving feedback or saying thanks on [Twitter](https://twitter.com/pkolloch) or\non the tracing discord channel is appreciated.\n\nContributions in the form of documentation and bug fixes are highly welcome.\nPlease start a discussion with me (e.g. via an issue) before working on larger\nfeatures.\n\nI'd really appreciate tests for all new features. Please run `cargo test`\nbefore submitting a pull request. Just use `cargo fmt` for formatting.\n\nFeature ideas are also welcome -- just know that this is a pure hobby side\nproject and I will not allocate a lot of bandwidth to this. Therefore, important\nbug fixes are always prioritised.\n\nBy submitting a pull request, you agree to license your changes via all the\ncurrent licenses of the project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkolloch%2Freqray","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkolloch%2Freqray","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkolloch%2Freqray/lists"}