From 7b696f32ced20ea6af3ff1301d945f72440ad3d0 Mon Sep 17 00:00:00 2001 From: Thang Le Quoc Date: Wed, 11 Feb 2026 11:00:28 +0700 Subject: [PATCH 1/2] docs: Add TimerNinjaBlock usage guideline to README --- README.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d33b653..b865fb8 100644 --- a/README.md +++ b/README.md @@ -248,7 +248,62 @@ public void requestMoneyTransfer(int sourceUserId, int targetUserId, int amount) **Sample output:** > public void requestMoneyTransfer(int sourceUserId, int targetUserId, int amount) - Args: [sourceUserId={1}, targetUserId={2}, amount={3000}] - 1037 ms ¤ [Threshold Exceed !!: 200 ms] -## Reading the time trace output +**Sample output:** +> public void requestMoneyTransfer(int sourceUserId, int targetUserId, int amount) - Args: [sourceUserId={1}, targetUserId={2}, amount={3000}] - 1037 ms ¤ [Threshold Exceed !!: 200 ms] + +## Block Tracking with TimerNinjaBlock ⚡ (New in 1.3.0) + +TimerNinjaBlock allows you to measure arbitrary code blocks within a method without extracting separate methods. This is perfect for tracking specific phases or operations inside a method. + +### Basic Usage + +```java +public void processOrder(Order order) { + // Regular code not tracked + + TimerNinjaBlock.measure("database query", () -> { + database.query("SELECT * FROM orders WHERE id = " + order.getId()); + }); + + // More code not tracked +} +``` + +### Block with Return Value + +```java +public void processOrder(Order order) { + String result = TimerNinjaBlock.measure("fetch data", () -> { + return api.fetchOrderData(order.getId()); + }); + + System.out.println(result); +} +``` + +### Block with Custom Configuration + +```java +import java.time.temporal.ChronoUnit; + +public void processOrder(Order order) { + BlockTrackerConfig config = new BlockTrackerConfig() + .setTimeUnit(ChronoUnit.SECONDS) + .setThreshold(2); + + TimerNinjaBlock.measure("long operation", config, () -> { + performLongRunningTask(order); + }); +} +``` + +**Sample output:** +> [Block] database query - 42 ms +> [Block] fetch data - 125 ms + +Use TimerNinjaBlock when you need granular tracking within a method without creating separate tracked methods. + +## Reading the time trace output## Reading the time trace output Once the method is executed, you should be able to find the result similar to this one in the output/log ```log From 38c5f769bc9d6af858506807afe80e91db18ba94 Mon Sep 17 00:00:00 2001 From: Thang Le Quoc Date: Wed, 11 Feb 2026 11:17:24 +0700 Subject: [PATCH 2/2] feat: Update README --- README.md | 43 +++++++++---------------------------------- 1 file changed, 9 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index b865fb8..70997ac 100644 --- a/README.md +++ b/README.md @@ -248,10 +248,9 @@ public void requestMoneyTransfer(int sourceUserId, int targetUserId, int amount) **Sample output:** > public void requestMoneyTransfer(int sourceUserId, int targetUserId, int amount) - Args: [sourceUserId={1}, targetUserId={2}, amount={3000}] - 1037 ms ¤ [Threshold Exceed !!: 200 ms] -**Sample output:** -> public void requestMoneyTransfer(int sourceUserId, int targetUserId, int amount) - Args: [sourceUserId={1}, targetUserId={2}, amount={3000}] - 1037 ms ¤ [Threshold Exceed !!: 200 ms] -## Block Tracking with TimerNinjaBlock ⚡ (New in 1.3.0) + +## Block Tracking with `TimerNinjaBlock` TimerNinjaBlock allows you to measure arbitrary code blocks within a method without extracting separate methods. This is perfect for tracking specific phases or operations inside a method. @@ -269,41 +268,13 @@ public void processOrder(Order order) { } ``` -### Block with Return Value - -```java -public void processOrder(Order order) { - String result = TimerNinjaBlock.measure("fetch data", () -> { - return api.fetchOrderData(order.getId()); - }); - - System.out.println(result); -} -``` - -### Block with Custom Configuration +Use TimerNinjaBlock for granular tracking within a method without creating separate tracked methods. -```java -import java.time.temporal.ChronoUnit; +For more advanced block tracking usage, see the [User Guide Wiki](https://github.com/thanglequoc/timer-ninja/wiki/User-Guide#block-tracking). -public void processOrder(Order order) { - BlockTrackerConfig config = new BlockTrackerConfig() - .setTimeUnit(ChronoUnit.SECONDS) - .setThreshold(2); - - TimerNinjaBlock.measure("long operation", config, () -> { - performLongRunningTask(order); - }); -} -``` - -**Sample output:** -> [Block] database query - 42 ms -> [Block] fetch data - 125 ms -Use TimerNinjaBlock when you need granular tracking within a method without creating separate tracked methods. -## Reading the time trace output## Reading the time trace output +## Reading the time trace output Once the method is executed, you should be able to find the result similar to this one in the output/log ```log @@ -320,6 +291,10 @@ Any sequence execution of other annotated tracker methods inside the parent meth `Trace timestamp`: The timestamp when the trace context is initiated, in UTC timezone. `Begin-end of trace context`: The detailed execution time of each method. The `|--` sign indicate the call to this method originated from the above parent method, which help to visualize the execution stacktrace. + +## User Guide +For comprehensive documentation, examples, and best practices on using the Timer-Ninja library efficiently, visit the [Wiki page](https://github.com/thanglequoc/timer-ninja/wiki/User-Guide). + ## Troubleshooting If you need to troubleshoot, you can toggle the `DEBUG` log level on logger `io.github.thanglequoc.timerninja.TimerNinjaThreadContext`.