From 1df6ba99c781fc8eeb30a02aab913d10600527ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= Date: Wed, 7 Mar 2012 17:11:16 +0100 Subject: Update scheduler_wall_time documentation * Add example on calculating scheduler utilization --- erts/doc/src/erlang.xml | 52 ++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 45 insertions(+), 7 deletions(-) (limited to 'erts') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index fbe7b36163..ed79109bdd 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -4935,17 +4935,51 @@ true scheduler_wall_time -

Returns - [{Scheduler_Id, Scheduler_Worked_Time, Scheduler_Total_Time}], time lapses are since the - the system flag scheduler_wall_time - was set to true. +

Returns a list of tuples with + {SchedulerId, ActiveTime, TotalTime}], where SchedulerId is an integer id of the scheduler, ActiveTime is + the duration the scheduler has been busy. TotalTime is the total time duration since + scheduler_wall_time activation. The time unit is not defined and may be subject to change. scheduler_wall_time should only be used to calculate relative values for scheduler-utilization. ActiveTime can never exceed TotalTime. +

+ +

The definition of a busy scheduler is when it is not idle or not scheduling (selecting) a process or port, meaning; executing process code, executing linked-in-driver or NIF code, garbage collecting or handling any other memory management. +

+ +

Returns undefined if the system flag - scheduler_wall_time is set to false. + scheduler_wall_time is turned off.

+

The list of scheduler information is unsorted and may come in different order - between calls. The time unit is undefined and may be changed and should only be used - to calculate relative utilization. + between calls.

+

Using scheduler_wall_time to calculate scheduler utilization.

+
+> erlang:system_flag(scheduler_wall_time, true).
+false
+> Ts0 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
+ok
+
+

Some time later we will take another snapshot and calculate scheduler-utilization per scheduler.

+
+> Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
+ok
+> lists:map(fun({{I, W0, T0}, {I, W1, T1}}) -> {I, (W1 - W0)/(T1 - T0)} end, lists:zip(Ts0,Ts1)).
+[{1,0.9743474730177548},
+ {2,0.9744843782751444},
+ {3,0.9995902361669045},
+ {4,0.9738012596572161},
+ {5,0.9717956667018103},
+ {6,0.9739235846420741},
+ {7,0.973237033077876},
+ {8,0.9741297293248656}]
+
+

Using the same snapshot to calculate a total scheduler-utilization.

+
+> {W, T} = lists:foldl(fun({{_, W0, T0}, {_, W1, T1}}, {Wi,Ti}) -> 
+	{Wi + (W1 - W0), Ti + (T1 - T0)} end, {0,0}, lists:zip(Ts0,Ts1)), W/T.
+0.9769136803764825
+
+ wall_clock @@ -4965,6 +4999,10 @@ true {2046,11} > statistics(garbage_collection). {85,23961,0} + +

scheduler_wall_time is by default disabled. Use erlang:system_flag(scheduler_wall_time, true) to enable it.

+ + -- cgit v1.2.3 From 8ed601a6f4f03ea6cdb82948e0c8aa06a14bd791 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= Date: Wed, 7 Mar 2012 17:32:35 +0100 Subject: doc: Rewording of scheduler busy --- erts/doc/src/erlang.xml | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) (limited to 'erts') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index ed79109bdd..441feaf76e 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -4937,11 +4937,17 @@ true

Returns a list of tuples with {SchedulerId, ActiveTime, TotalTime}], where SchedulerId is an integer id of the scheduler, ActiveTime is - the duration the scheduler has been busy. TotalTime is the total time duration since - scheduler_wall_time activation. The time unit is not defined and may be subject to change. scheduler_wall_time should only be used to calculate relative values for scheduler-utilization. ActiveTime can never exceed TotalTime. + the duration the scheduler has been busy, TotalTime is the total time duration since + scheduler_wall_time + activation. The time unit is not defined and may be subject to change. + scheduler_wall_time should only be used to calculate relative + values for scheduler-utilization. ActiveTime can never exceed TotalTime.

-

The definition of a busy scheduler is when it is not idle or not scheduling (selecting) a process or port, meaning; executing process code, executing linked-in-driver or NIF code, garbage collecting or handling any other memory management. +

The definition of a busy scheduler is when it is not idle or not + scheduling (selecting) a process or port, meaning; executing process + code, executing linked-in-driver or NIF code, executing + built-in-functions or any other runtime handling, garbage collecting or handling any other memory management.

-- cgit v1.2.3 From e19f2fb347fb29ce37be6acf1d4e6b5d64f4b84a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= Date: Thu, 8 Mar 2012 09:59:28 +0100 Subject: doc: Change variable name to 'A' to reflect Active --- erts/doc/src/erlang.xml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'erts') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 441feaf76e..922d20bb82 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -4969,7 +4969,8 @@ ok 

 > Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
 ok
-> lists:map(fun({{I, W0, T0}, {I, W1, T1}}) -> {I, (W1 - W0)/(T1 - T0)} end, lists:zip(Ts0,Ts1)).
+> lists:map(fun({{I, A0, T0}, {I, A1, T1}}) ->
+	{I, (A1 - A0)/(T1 - T0)} end, lists:zip(Ts0,Ts1)).
 [{1,0.9743474730177548},
  {2,0.9744843782751444},
  {3,0.9995902361669045},
@@ -4981,8 +4982,8 @@ ok

Using the same snapshot to calculate a total scheduler-utilization.

-> {W, T} = lists:foldl(fun({{_, W0, T0}, {_, W1, T1}}, {Wi,Ti}) -> 
-	{Wi + (W1 - W0), Ti + (T1 - T0)} end, {0,0}, lists:zip(Ts0,Ts1)), W/T.
+> {A, T} = lists:foldl(fun({{_, A0, T0}, {_, A1, T1}}, {Ai,Ti}) ->
+	{Ai + (A1 - A0), Ti + (T1 - T0)} end, {0, 0}, lists:zip(Ts0,Ts1)), A/T.
 0.9769136803764825
-- cgit v1.2.3 From 5ca9e5b8b990f7539a3e312fa33e09bd21c228c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= Date: Thu, 8 Mar 2012 10:16:54 +0100 Subject: doc: Rewording of scheduler_wall_time --- erts/doc/src/erlang.xml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'erts') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 922d20bb82..cd95a6a312 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -4939,7 +4939,8 @@ true {SchedulerId, ActiveTime, TotalTime}], where SchedulerId is an integer id of the scheduler, ActiveTime is the duration the scheduler has been busy, TotalTime is the total time duration since scheduler_wall_time - activation. The time unit is not defined and may be subject to change. + activation. The time unit is not defined and may be subject to change + between releases, operating systems and system restarts. scheduler_wall_time should only be used to calculate relative values for scheduler-utilization. ActiveTime can never exceed TotalTime.

@@ -4947,7 +4948,8 @@ true

The definition of a busy scheduler is when it is not idle or not scheduling (selecting) a process or port, meaning; executing process code, executing linked-in-driver or NIF code, executing - built-in-functions or any other runtime handling, garbage collecting or handling any other memory management. + built-in-functions or any other runtime handling, garbage collecting + or handling any other memory management.

@@ -4980,7 +4982,7 @@ ok {7,0.973237033077876}, {8,0.9741297293248656}] -

Using the same snapshot to calculate a total scheduler-utilization.

+

Using the same snapshots to calculate a total scheduler-utilization.

 > {A, T} = lists:foldl(fun({{_, A0, T0}, {_, A1, T1}}, {Ai,Ti}) ->
 	{Ai + (A1 - A0), Ti + (T1 - T0)} end, {0, 0}, lists:zip(Ts0,Ts1)), A/T.
-- 
cgit v1.2.3


From 991444c8345a1704f3ddce13eaa010f551a754c7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= 
Date: Thu, 8 Mar 2012 10:34:34 +0100
Subject: doc: Move examples and notes into tag-lists

---
 erts/doc/src/erlang.xml | 51 ++++++++++++++++++++++++++++---------------------
 1 file changed, 29 insertions(+), 22 deletions(-)

(limited to 'erts')

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index cd95a6a312..239cc63f71 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -4881,6 +4881,7 @@ true
Type, Res -- see below +

All times are in milliseconds unless otherwise specified.

Returns information about the system as specified by Type:

@@ -4894,15 +4895,20 @@ true

Returns {Total_Exact_Reductions, Exact_Reductions_Since_Last_Call}.

-

NOTE:statistics(exact_reductions) is - a more expensive operation than - statistics(reductions) - especially on an Erlang machine with SMP support.

+

statistics(exact_reductions) is + a more expensive operation than + statistics(reductions) + especially on an Erlang machine with SMP support.

+ garbage_collection

Returns {Number_of_GCs, Words_Reclaimed, 0}. This information may not be valid for all implementations.

+ 
+> statistics(garbage_collection).
+{85,23961,0}
+
 io @@ -4914,12 +4920,18 @@ true reductions

Returns - {Total_Reductions, Reductions_Since_Last_Call}.

-

NOTE: From erts version 5.5 (OTP release R11B) - this value does not include reductions performed in current - time slices of currently scheduled processes. If an - exact value is wanted, use - statistics(exact_reductions).

+ {Total_Reductions, Reductions_Since_Last_Call}.

+ +

From erts version 5.5 (OTP release R11B) + this value does not include reductions performed in current + time slices of currently scheduled processes. If an + exact value is wanted, use + statistics(exact_reductions).

+ + 
+> statistics(reductions).
+{2046,11}
+
 run_queue @@ -4932,6 +4944,10 @@ true Note that the run-time is the sum of the run-time for all threads in the Erlang run-time system and may therefore be greater than the wall-clock time.

+ 
+> statistics(runtime).
+{1690,1620}
+
 scheduler_wall_time @@ -4989,6 +5005,9 @@ ok 0.9769136803764825 + +

scheduler_wall_time is by default disabled. Use erlang:system_flag(scheduler_wall_time, true) to enable it.

+ wall_clock @@ -5000,18 +5019,6 @@ ok opposed to runtime or CPU time.

 -

All times are in milliseconds.

- 
-> statistics(runtime).
-{1690,1620}
-> statistics(reductions).
-{2046,11}
-> statistics(garbage_collection).
-{85,23961,0}
- -

scheduler_wall_time is by default disabled. Use erlang:system_flag(scheduler_wall_time, true) to enable it.

- - -- cgit v1.2.3 From 3e313c2b3930b22edd43add9ecd817d16a77eb2a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= Date: Thu, 8 Mar 2012 10:41:58 +0100 Subject: doc: Enhance wording and remove typos --- erts/doc/src/erlang.xml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'erts') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 239cc63f71..8c438b0bd7 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -4952,7 +4952,7 @@ true scheduler_wall_time

Returns a list of tuples with - {SchedulerId, ActiveTime, TotalTime}], where SchedulerId is an integer id of the scheduler, ActiveTime is + {SchedulerId, ActiveTime, TotalTime}, where SchedulerId is an integer id of the scheduler, ActiveTime is the duration the scheduler has been busy, TotalTime is the total time duration since scheduler_wall_time activation. The time unit is not defined and may be subject to change @@ -4965,7 +4965,9 @@ true scheduling (selecting) a process or port, meaning; executing process code, executing linked-in-driver or NIF code, executing built-in-functions or any other runtime handling, garbage collecting - or handling any other memory management. + or handling any other memory management. Note, a scheduler may also be + busy even if the operating system has scheduled out the scheduler + thread.

@@ -4973,7 +4975,7 @@ true scheduler_wall_time is turned off.

-

The list of scheduler information is unsorted and may come in different order +

The list of scheduler information is unsorted and may appear in different order between calls.

Using scheduler_wall_time to calculate scheduler utilization.

-- cgit v1.2.3