Tstanley — Mon, 31 May 2010 21:40:02 GMT

Tstanley: /* Getting Started */

== Instrumenting a Platform to Generate Causeway Trace Logs ==

Introduction, communicating events loops

* Waterken
** promises
* AmbientTalk
** futures

=== Getting Started ===

* See [[Causeway]] for user documentation, which includes instructions for launching Causeway from a command line shell.

* See HP Labs Technical Report at www.hpl.hp.com/techreports/2009/HPL-2009-78.html for a more in-depth discussion of the material presented here. A careful read is not necessary but a quick skim to see what's there is a good idea.

This documentation assumes an understanding of the purchase-order example program.

* Read the source code. It's part of the E distribution and can be found here.

<code>e/src/esrc/scripts/test/causeway/waterken/sources</code>
<code>e/src/esrc/scripts/test/causeway/ambientTalk/sources</code>

Also, we're asking that you write a version of the purchase-order example that runs on your platform, as one of your first test cases. It's best to start with the Ajax-style continuation-passing, using callbacks. This approach is less expressive than promises, but generating the trace log is more straightforward.

* Browse the example programs in Causeway, e.g., Help >> Open Waterken Example (Ajax-style).

=== Support Tools ===

* Enable Causeway's debug view

Setting Causeway's debug flag enables a debug view. As events are selected in the viewer, the debug view shows the corresponding trace record in the log file. This is a very useful option, especially in the beginning, when things aren't quite working.
<pre>
$ rune -Dcauseway_debug=true causeway.e-swt
</pre>

''(''
'''Note:'''
''When this debug option is set, Causeway's JSON parser uses <tt>getTwine()</tt>. This is an inefficient algorithm which is not likely to change anytime soon. The trace logs for the example programs are roughly 20K; the poor performance is noticed with logs > 250K.)''

[[Image:debug-view.png]]

* Support for visualizing graph filter algorithm

Your first traces are likely to be noisy and Causeway's views, baffling. It can take some careful consideration and cleverness to figure out why and what to do about it. Simple filters (e.g., hiding stack frames, options for more or less detail) are necessary but not sufficient. The right abstractions must be found to enhance program understanding, while maintaining causality. Currently, Causeway does not support user-specified filters that manipulate the message graph (DAG) structure. Our approach to debugging our filtering algorithm is described HERE. Once we have more experience, we expect to support user-specified filters.

== Causeway's Trace Log Format ==

Causeway supports the trace log format defined by Tyler Close at waterken.sourceforge.net/debug/.

We will explain this format, and how to get your platform to generate it, in three steps: Simple Ajax (below), [[Causeway Platform Developer: Ajax|Ajax with promotion]], and [[Causeway Platform Developer: Promises|full promises]].

[[Image:event-types.png|alt=Trace log event types]]

When causality tracing is on the events are logged as follows.

{| border="1"
! Event !! Record type
|-
| An eventual send to an object || Sent
|-
| A message delivery, starting a new turn || Got
|-
| Registration of a when-block, to execute when a promise resolves || SentIf
|-
| Returned result from a remote object, for local promise resolution || Returned
|-
| A state-based event contributes to promise resolution || Progressed
|-
| A promise resolves || Fulfilled or Rejected
|-
| Programmer logs a comment || Comment
|}

In the Causeway viewer, individual tree items represent events and their descriptive labels depend on the information available in the trace record for the event.

[[Image:tree-item-labels.png|alt=Tree item labels]]

To present the most useful information available, Causeway labels tree items according to the following priority.

# User comments specified in the <tt>text</tt> field, prefixed with "#".
# Source code specified in the top call stack object. The <tt>trace</tt> object must include a <tt>span</tt>.
# Source file and function name specified in top call stack object. The <tt>trace</tt> object must include a <tt>name</tt> and <tt>source</tt>.
# If none of the above, the label is a Causeway-generated comment, prefixed with "##", e.g., ## unknown sender.

=== Logging Ajax-style Messaging in Waterken ===

Consider the sequence of events shown below.

[[Image:part-in-stock.png|alt=Ajax-style message send]]

* a remote inventory object is queried for the availability of a part
* the inventory object reports true to <tt>teller</tt>, a callback object

The eventual send to the inventory object has two log entries: a <tt>Sent</tt> and its corresponding <tt>Got</tt>.

<pre>
"class" : [ "org.ref_send.log.Sent", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 3,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/",
"number" : 3
}
},
"message" : "lqhjpwbbeemozk-2-0",
"timestamp" : 1274238401772,
"trace" : {
"calls" : [ {
"name" : "Main.Buy.fulfill",
"source" : "org/waterken/purchase_ajax/Main.java",
"span" : [ [ 68 ] ]
}, {
"name" : "Main.Buy.fulfill",
"source" : "org/waterken/purchase_ajax/Main.java",
"span" : [ [ 48 ] ]
} ]
}
</pre>

<pre>
"class" : [ "org.ref_send.log.Got", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 1,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/product/",
"number" : 2
}
},
"message" : "lqhjpwbbeemozk-2-0",
"trace" : {
"calls" : [ {
"name" : "InventoryMaker.InventoryX.partInStock",
"source" : "org/waterken/purchase_ajax/InventoryMaker.java"
} ]
}
</pre>

* In the <tt>Sent</tt> trace record:
** <tt>anchor</tt> uniquely identifies the origin of this message send as the 3rd messaging event from the buyer vat, turn 3.
** <tt>message</tt> is a generated string which uniquely identifies a message.
**<tt>trace</tt> is the stack capture at the point of the message send.

('''Note:''' The <tt>loop</tt> field identifies the vat by URI. By convention, Causeway picks up the part following "/-/", in this case buyer, for a short display name.)

('''Note:''' The <tt>timestamp</tt> field is optional. Currently, Causeway ignores it, so it's not shown in the remaining trace records.)

The corresponding <tt>Got</tt> has a matching <tt>message</tt>. The message delivery in the product vat starts a new turn, turn 2. Being at the top of a new turn, there is limited stack capture and getting a source span through Java reflection, is not practical.

Reporting true to <tt>teller</tt> has two log entries: a <tt>Sent</tt> and its corresponding <tt>Got</tt>.

<pre>
"class" : [ "org.ref_send.log.Sent", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 2,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/product/",
"number" : 2
}
},
"message" : "ewrigzpctikrhk-1-0",
"trace" : {
"calls" : [ {
"name" : "InventoryMaker.InventoryX.partInStock",
"source" : "org/waterken/purchase_ajax/InventoryMaker.java",
"span" : [ [ 19 ] ]
} ]
}
</pre>

<pre>
"class" : [ "org.ref_send.log.Got", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 1,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/",
"number" : 10
}
},
"message" : "ewrigzpctikrhk-1-0",
"trace" : {
"calls" : [ {
"name" : "AsyncAnd.run",
"source" : "org/waterken/purchase_ajax/AsyncAnd.java"
} ]
}
</pre>

The reply to the query is the 2nd messaging event from the product vat, turn 2.

The corresponding <tt>Got</tt> has a matching <tt>message</tt>. The message delivery in the buyer vat starts a new turn, turn 10.

=== Logging Promise-based Messaging in Waterken ===

Our example program implements a promise-based distributed procedure for handling new purchase orders. Before an order is placed, certain conditions must be met: the item is in stock and available, the customer's account is in good standing, and the delivery options are up to date.

An object residing in the "buyer" vat has remote references to objects residing in the "product" and "accounts" vats. The buyer queries the remote objects with asynchronous (non-blocking) message sends. A promise is a placeholder for the answer to a query; when the answer becomes available the promise resolves to that value.

The code snippet below shows the 3 queries being fired off. The order of the incoming answers cannot be known. All 3 answers must be examined before the order is placed.

Collecting the answers is handled by an <tt>AsyncAnd</tt> object. The <tt>run</tt> method returns a promise for the result. By registering a when-block on the resolution of that promise, the invocation of <tt>checkAnswers</tt> is synchronized with the completion of the collection of the answers.

<pre>
Promise<Boolean> partP = _._(inventory).partInStock(partNo);
Promise<Boolean> creditP = _._(creditBureau).checkCredit(name);
Promise<Boolean> deliverP = _._(shipper).canDeliver(profile);

final Promise<Boolean> allOkP =
new AsyncAnd(_).run(partP, creditP, deliverP);

/*
* Register a when-block on promise returned by AsyncAnd.
* The block executes when the promise resolves (either
* fulfilled or rejected).
*/

_.when(allOkP, checkAnswers(_, inventory));
</pre>

We start with a detailed description of a single message, <tt>partInStock</tt>. Then we'll look at how <tt>AsyncAnd</tt> collects the answers and reports a final result.

The graph below describes the mechanics of Waterken promise resolution.

[[Image:wk-promise-mechanics.png|alt=Waterken promise resolution]]

# buyer does an eventual send to product and registers a when-block on the resolution of that promise
# product receives the message and returns a result
# buyer receives the result and resolves the promise locally
# buyer executes the when-block

The sequence of graphs below describe transformations on Causeway's message graph to better represent promise semantics, rather than the mechanics of promise resolution.

[[Image:raw-d1-d2.png|alt=Raw, then filtered graph]]

Now, we can say more about the <code>AsyncAnd</code> logic.

In <code>AsyncAnd.run()</code> a promise-resolver pair implements the communication synchronization.

<pre>
public Promise<Boolean> run(Promise<Boolean>... answers) {
final Channel<Boolean> result = _.defer();
final int[] expected = {answers.length};
for (Promise<Boolean> answerP : answers) {

/*
* Register a when-block on each promise. The block executes
* when the promise resolves (either fulfilled or rejected).
*/

_.when(answerP, new DoAnswer(expected, result.resolver));
}
return result.promise;
}
</pre>

The <code>progress()</code> message captures a stack trace and logs a <tt>Progressed</tt> record to indicate that a state-based event contributed to the resolution of a promise. (If logging is off, it is a semantic no-op.)

Let's say all 3 answers are true and the promise eventually resolves to true. It's reasonable to think of all 3 answers as contributing to the resolution, i.e., the resolving of the promise had 3 causes. But without event promotion, the message-order view would show only 1 cause.

The arrival of the first 2 answers causes a local state change (a counter is decremented), while the last answer causes a message send. Without event promotion, the promise resolution would have a single cause: the last answer. The <code>progress()</code> message is used to promote state-based events to message order.

<pre>
public Void fulfill(Boolean answer) {
if (answer) {
myExpected[0]--;
if (myExpected[0] == 0) {
/*
* Resolve the promise with true.
*/
myResolver.apply(true);
} else {
/*
* Progress had been made in resolving the promise.
* If logging is on, a Progressed event record is written.
* If logging is off, this is a no-op.
*/
myResolver.progress();
}
} else {
/*
* Resolve the promise with false. Notice that this
* short-circuits the logic: any remaining expected answers
* are ignored.
*/
myResolver.apply(false);
}
}
</pre>

The resulting process-order view and message-order view are shown below. The registration of when-blocks are filtered from message-order as they don't contribute to the understanding of message flow; however, they do appear in process-order.

[[Image:wk-promise-pov-mov.png|alt=Waterken promise process-order and message-order views]]

=== Performance Issues in Waterken ===

Due to the expense of stack capture in Java, tracing in Waterken incurs roughly, an order of magnitude performance penalty. If tracing is off, there is no penalty.

Waterken guarantees message order delivery and in addition, if a connection is dropped, there's enough information to know about partial success. For example, if 2 messages (msg1, msg2) are sent from vat A to vat B, they are guaranteed to be processed in the order sent. If the connection is dropped after msg1 is successfully sent, when the connection is re-established, it is known that only msg2 must be resent.

The identifiers used to support these guarantees are also used for tracing. The advantage of these multi-purpose identifiers is there is no overhead when tracing is off (i.e., unique message identifiers, just for tracing, are not sent out over the wire.)

''(''
'''Note:'''
''Resending a message after a connection is re-established can result in 2 identical <tt>Sent</tt> events being logged. Causeway notices when the event records are identical and ignores the duplicate.)''

[[Category:Applications]]

Causeway Platform Developer: Promises

Tstanley — Mon, 31 May 2010 21:35:03 GMT

Tstanley:

Placeholder -- ignore for now

== Instrumenting a Platform to Generate Causeway Trace Logs ==

Introduction, communicating events loops

* Waterken
** promises
* AmbientTalk
** futures

=== Getting Started ===

* See [[Causeway]] for user documentation, which includes instructions for launching Causeway from a command line shell.

* See HP Labs Technical Report for a more in-depth discussion of the material presented here. A careful read is not necessary but a quick skim to see what's there is a good idea.

This documentation assumes an understanding of the purchase-order example program.

* Read the source code. It's part of the E distribution and can be found here.

<code>e/src/esrc/scripts/test/causeway/waterken/sources</code>
<code>e/src/esrc/scripts/test/causeway/ambientTalk/sources</code>

Also, we're asking that you write a version of the purchase-order example that runs on your platform, as one of your first test cases. It's best to start with the Ajax-style continuation-passing, using callbacks. This approach is less expressive than promises, but generating the trace log is more straightforward.

* Browse the example programs in Causeway, e.g., Help >> Open Waterken Example (Ajax-style).

=== Support Tools ===

* Enable Causeway's debug view

Setting Causeway's debug flag enables a debug view. As events are selected in the viewer, the debug view shows the corresponding trace record in the log file. This is a very useful option, especially in the beginning, when things aren't quite working.
<pre>
$ rune -Dcauseway_debug=true causeway.e-swt
</pre>

''(''
'''Note:'''
''When this debug option is set, Causeway's JSON parser uses <tt>getTwine()</tt>. This is an inefficient algorithm which is not likely to change anytime soon. The trace logs for the example programs are roughly 20K; the poor performance is noticed with logs > 250K.)''

[[Image:debug-view.png]]

* Support for visualizing graph filter algorithm

Your first traces are likely to be noisy and Causeway's views, baffling. It can take some careful consideration and cleverness to figure out why and what to do about it. Simple filters (e.g., hiding stack frames, options for more or less detail) are necessary but not sufficient. The right abstractions must be found to enhance program understanding, while maintaining causality. Currently, Causeway does not support user-specified filters that manipulate the message graph (DAG) structure. Our approach to debugging our filtering algorithm is described HERE. Once we have more experience, we expect to support user-specified filters.

== Causeway's Trace Log Format ==

Causeway supports the trace log format defined by Tyler Close at waterken.sourceforge.net/debug/.

We will explain this format, and how to get your platform to generate it, in three steps: Simple Ajax (below), [[Causeway Platform Developer: Ajax|Ajax with promotion]], and [[Causeway Platform Developer: Promises|full promises]].

[[Image:event-types.png|alt=Trace log event types]]

When causality tracing is on the events are logged as follows.

{| border="1"
! Event !! Record type
|-
| An eventual send to an object || Sent
|-
| A message delivery, starting a new turn || Got
|-
| Registration of a when-block, to execute when a promise resolves || SentIf
|-
| Returned result from a remote object, for local promise resolution || Returned
|-
| A state-based event contributes to promise resolution || Progressed
|-
| A promise resolves || Fulfilled or Rejected
|-
| Programmer logs a comment || Comment
|}

In the Causeway viewer, individual tree items represent events and their descriptive labels depend on the information available in the trace record for the event.

[[Image:tree-item-labels.png|alt=Tree item labels]]

To present the most useful information available, Causeway labels tree items according to the following priority.

# User comments specified in the <tt>text</tt> field, prefixed with "#".
# Source code specified in the top call stack object. The <tt>trace</tt> object must include a <tt>span</tt>.
# Source file and function name specified in top call stack object. The <tt>trace</tt> object must include a <tt>name</tt> and <tt>source</tt>.
# If none of the above, the label is a Causeway-generated comment, prefixed with "##", e.g., ## unknown sender.

=== Logging Ajax-style Messaging in Waterken ===

Consider the sequence of events shown below.

[[Image:part-in-stock.png|alt=Ajax-style message send]]

* a remote inventory object is queried for the availability of a part
* the inventory object reports true to <tt>teller</tt>, a callback object

The eventual send to the inventory object has two log entries: a <tt>Sent</tt> and its corresponding <tt>Got</tt>.

<pre>
"class" : [ "org.ref_send.log.Sent", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 3,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/",
"number" : 3
}
},
"message" : "lqhjpwbbeemozk-2-0",
"timestamp" : 1274238401772,
"trace" : {
"calls" : [ {
"name" : "Main.Buy.fulfill",
"source" : "org/waterken/purchase_ajax/Main.java",
"span" : [ [ 68 ] ]
}, {
"name" : "Main.Buy.fulfill",
"source" : "org/waterken/purchase_ajax/Main.java",
"span" : [ [ 48 ] ]
} ]
}
</pre>

<pre>
"class" : [ "org.ref_send.log.Got", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 1,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/product/",
"number" : 2
}
},
"message" : "lqhjpwbbeemozk-2-0",
"trace" : {
"calls" : [ {
"name" : "InventoryMaker.InventoryX.partInStock",
"source" : "org/waterken/purchase_ajax/InventoryMaker.java"
} ]
}
</pre>

* In the <tt>Sent</tt> trace record:
** <tt>anchor</tt> uniquely identifies the origin of this message send as the 3rd messaging event from the buyer vat, turn 3.
** <tt>message</tt> is a generated string which uniquely identifies a message.
**<tt>trace</tt> is the stack capture at the point of the message send.

('''Note:''' The <tt>loop</tt> field identifies the vat by URI. By convention, Causeway picks up the part following "/-/", in this case buyer, for a short display name.)

('''Note:''' The <tt>timestamp</tt> field is optional. Currently, Causeway ignores it, so it's not shown in the remaining trace records.)

The corresponding <tt>Got</tt> has a matching <tt>message</tt>. The message delivery in the product vat starts a new turn, turn 2. Being at the top of a new turn, there is limited stack capture and getting a source span through Java reflection, is not practical.

Reporting true to <tt>teller</tt> has two log entries: a <tt>Sent</tt> and its corresponding <tt>Got</tt>.

<pre>
"class" : [ "org.ref_send.log.Sent", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 2,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/product/",
"number" : 2
}
},
"message" : "ewrigzpctikrhk-1-0",
"trace" : {
"calls" : [ {
"name" : "InventoryMaker.InventoryX.partInStock",
"source" : "org/waterken/purchase_ajax/InventoryMaker.java",
"span" : [ [ 19 ] ]
} ]
}
</pre>

<pre>
"class" : [ "org.ref_send.log.Got", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 1,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/",
"number" : 10
}
},
"message" : "ewrigzpctikrhk-1-0",
"trace" : {
"calls" : [ {
"name" : "AsyncAnd.run",
"source" : "org/waterken/purchase_ajax/AsyncAnd.java"
} ]
}
</pre>

The reply to the query is the 2nd messaging event from the product vat, turn 2.

The corresponding <tt>Got</tt> has a matching <tt>message</tt>. The message delivery in the buyer vat starts a new turn, turn 10.

=== Logging Promise-based Messaging in Waterken ===

Our example program implements a promise-based distributed procedure for handling new purchase orders. Before an order is placed, certain conditions must be met: the item is in stock and available, the customer's account is in good standing, and the delivery options are up to date.

An object residing in the "buyer" vat has remote references to objects residing in the "product" and "accounts" vats. The buyer queries the remote objects with asynchronous (non-blocking) message sends. A promise is a placeholder for the answer to a query; when the answer becomes available the promise resolves to that value.

The code snippet below shows the 3 queries being fired off. The order of the incoming answers cannot be known. All 3 answers must be examined before the order is placed.

Collecting the answers is handled by an <tt>AsyncAnd</tt> object. The <tt>run</tt> method returns a promise for the result. By registering a when-block on the resolution of that promise, the invocation of <tt>checkAnswers</tt> is synchronized with the completion of the collection of the answers.

<pre>
Promise<Boolean> partP = _._(inventory).partInStock(partNo);
Promise<Boolean> creditP = _._(creditBureau).checkCredit(name);
Promise<Boolean> deliverP = _._(shipper).canDeliver(profile);

final Promise<Boolean> allOkP =
new AsyncAnd(_).run(partP, creditP, deliverP);

/*
* Register a when-block on promise returned by AsyncAnd.
* The block executes when the promise resolves (either
* fulfilled or rejected).
*/

_.when(allOkP, checkAnswers(_, inventory));
</pre>

We start with a detailed description of a single message, <tt>partInStock</tt>. Then we'll look at how <tt>AsyncAnd</tt> collects the answers and reports a final result.

The graph below describes the mechanics of Waterken promise resolution.

[[Image:wk-promise-mechanics.png|alt=Waterken promise resolution]]

# buyer does an eventual send to product and registers a when-block on the resolution of that promise
# product receives the message and returns a result
# buyer receives the result and resolves the promise locally
# buyer executes the when-block

The sequence of graphs below describe transformations on Causeway's message graph to better represent promise semantics, rather than the mechanics of promise resolution.

[[Image:raw-d1-d2.png|alt=Raw, then filtered graph]]

Now, we can say more about the <code>AsyncAnd</code> logic.

In <code>AsyncAnd.run()</code> a promise-resolver pair implements the communication synchronization.

<pre>
public Promise<Boolean> run(Promise<Boolean>... answers) {
final Channel<Boolean> result = _.defer();
final int[] expected = {answers.length};
for (Promise<Boolean> answerP : answers) {

/*
* Register a when-block on each promise. The block executes
* when the promise resolves (either fulfilled or rejected).
*/

_.when(answerP, new DoAnswer(expected, result.resolver));
}
return result.promise;
}
</pre>

The <code>progress()</code> message captures a stack trace and logs a <tt>Progressed</tt> record to indicate that a state-based event contributed to the resolution of a promise. (If logging is off, it is a semantic no-op.)

Let's say all 3 answers are true and the promise eventually resolves to true. It's reasonable to think of all 3 answers as contributing to the resolution, i.e., the resolving of the promise had 3 causes. But without event promotion, the message-order view would show only 1 cause.

The arrival of the first 2 answers causes a local state change (a counter is decremented), while the last answer causes a message send. Without event promotion, the promise resolution would have a single cause: the last answer. The <code>progress()</code> message is used to promote state-based events to message order.

<pre>
public Void fulfill(Boolean answer) {
if (answer) {
myExpected[0]--;
if (myExpected[0] == 0) {
/*
* Resolve the promise with true.
*/
myResolver.apply(true);
} else {
/*
* Progress had been made in resolving the promise.
* If logging is on, a Progressed event record is written.
* If logging is off, this is a no-op.
*/
myResolver.progress();
}
} else {
/*
* Resolve the promise with false. Notice that this
* short-circuits the logic: any remaining expected answers
* are ignored.
*/
myResolver.apply(false);
}
}
</pre>

The resulting process-order view and message-order view are shown below. The registration of when-blocks are filtered from message-order as they don't contribute to the understanding of message flow; however, they do appear in process-order.

[[Image:wk-promise-pov-mov.png|alt=Waterken promise process-order and message-order views]]

=== Performance Issues in Waterken ===

Due to the expense of stack capture in Java, tracing in Waterken incurs roughly, an order of magnitude performance penalty. If tracing is off, there is no penalty.

Waterken guarantees message order delivery and in addition, if a connection is dropped, there's enough information to know about partial success. For example, if 2 messages (msg1, msg2) are sent from vat A to vat B, they are guaranteed to be processed in the order sent. If the connection is dropped after msg1 is successfully sent, when the connection is re-established, it is known that only msg2 must be resent.

The identifiers used to support these guarantees are also used for tracing. The advantage of these multi-purpose identifiers is there is no overhead when tracing is off (i.e., unique message identifiers, just for tracing, are not sent out over the wire.)

''(''
'''Note:'''
''Resending a message after a connection is re-established can result in 2 identical <tt>Sent</tt> events being logged. Causeway notices when the event records are identical and ignores the duplicate.)''

[[Category:Applications]]

Tstanley — Sun, 30 May 2010 20:46:06 GMT

Tstanley: /* Logging Promise-based Messaging in Waterken */

== Instrumenting a Platform to Generate Causeway Trace Logs ==

Introduction, communicating events loops

* Waterken
** promises
* AmbientTalk
** futures

=== Getting Started ===

* See [[Causeway]] for user documentation, which includes instructions for launching Causeway from a command line shell.

* See HP Labs Technical Report for a more in-depth discussion of the material presented here. A careful read is not necessary but a quick skim to see what's there is a good idea.

This documentation assumes an understanding of the purchase-order example program.

* Read the source code. It's part of the E distribution and can be found here.

<code>e/src/esrc/scripts/test/causeway/waterken/sources</code>
<code>e/src/esrc/scripts/test/causeway/ambientTalk/sources</code>

Also, we're asking that you write a version of the purchase-order example that runs on your platform, as one of your first test cases. It's best to start with the Ajax-style continuation-passing, using callbacks. This approach is less expressive than promises, but generating the trace log is more straightforward.

* Browse the example programs in Causeway, e.g., Help >> Open Waterken Example (Ajax-style).

Setting Causeway's debug flag enables a Debug view. As events are selected in the viewer, the Debug view shows the corresponding trace record in the log file. This is a very useful option, especially in the beginning, when things aren't quite working.
<pre>
$ rune -Dcauseway_debug=true causeway.e-swt
</pre>

''(''
'''Note:'''
''When this debug option is set, Causeway's JSON parser uses <code>getTwine()</code>. This is an inefficient algorithm which is not likely to change anytime soon. The trace logs for the example programs are roughly 20K; the poor performance is noticed with logs > 250K.)''

[[Image:debug-view.png]]

Individual tree items (e.g. shown in the message-order view above) represent events and their descriptive labels depend on the information available in the trace record for the event. Causeway labels the tree items according to the following priority.

# The <tt>text</tt> field string. This field is required for <tt>Comment</tt> records; it is optional for <tt>Sent</tt>, <tt>SentIf</tt>, and <tt>Resolved</tt> records. (e.g. # Order placed for West Coast Buyers)
# If the trace record has at least one stack entry with a source and span, a single line of source code from the source file specified in the top stack entry. (e.g. <code>_._(inventory).partInStock(partNo, teller);</code>)
# If there's no span, source file name and function name specified in the top stack entry. (e.g. <code>[buyer, 8] AsyncAnd.run</code>)
# If nothing else, a Causeway comment. (e.g. <code>## unknown sender</code>)

Your first traces are likely to be noisy and Causeway's views, baffling. It can take some careful consideration and cleverness to figure out why and what to do about it. Simple filters (e.g., hiding stack frames, options for more or less detail) are necessary but not sufficient. The right abstractions must be found to enhance program understanding, while maintaining causality. Currently, Causeway does not support user-specified filters that manipulate the message graph (DAG) structure. Our approach to debugging our filtering algorithm is described HERE. Once we have more experience, we expect to support user-specified filters.

== Causeway's Trace Log Format ==

Causeway supports the trace log format defined by Tyler Close at waterken.sourceforge.net/debug/.

[[Image:event-types.png|alt=Trace log event types]]

When causality tracing is on the events are logged as follows.

{| border="1"
! Event !! Record type
|-
| An eventual send to an object || Sent
|-
| A message delivery, starting a new turn || Got
|-
| Registration of a when-block, to execute when a promise resolves || SentIf
|-
| Returned result from a remote object, for local promise resolution || Returned
|-
| A state-based event contributes to promise resolution || Progressed
|-
| A promise resolves || Fulfilled or Rejected
|-
| Programmer logs a comment || Comment
|}

=== Logging Ajax-style Messaging in Waterken ===

Consider the sequence of events shown below.

[[Image:part-in-stock.png|alt=Ajax-style message send]]

* a remote inventory object is queried for the availability of a part
* the inventory object reports true to <code>teller</code>, a callback object

The eventual send to the inventory object has two log entries: a <tt>Sent</tt> and its corresponding <tt>Got</tt>.

<pre>
"class" : [ "org.ref_send.log.Sent", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 3,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/",
"number" : 3
}
},
"message" : "lqhjpwbbeemozk-2-0",
"timestamp" : 1274238401772,
"trace" : {
"calls" : [ {
"name" : "Main.Buy.fulfill",
"source" : "org/waterken/purchase_ajax/Main.java",
"span" : [ [ 68 ] ]
}, {
"name" : "Main.Buy.fulfill",
"source" : "org/waterken/purchase_ajax/Main.java",
"span" : [ [ 48 ] ]
} ]
}
</pre>

The <tt>anchor</tt> uniquely identifies the origin of this message send as the 3rd messaging event from the buyer vat, turn 3.

The <tt>message</tt> is a generated string which uniquely identifies a message.

The <tt>trace</tt> is the stack capture at the point of the message send.

Note: The <tt>loop</tt> field identifies the vat by URI. By convention, Causeway picks up the part following "/-/", in this case buyer, for a short display name.

Note: The <tt>timestamp</tt> field is optional. Currently, it is ignored by Causeway, so it's not shown in the remaining trace records.

<pre>
"class" : [ "org.ref_send.log.Got", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 1,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/product/",
"number" : 2
}
},
"message" : "lqhjpwbbeemozk-2-0",
"trace" : {
"calls" : [ {
"name" : "InventoryMaker.InventoryX.partInStock",
"source" : "org/waterken/purchase_ajax/InventoryMaker.java"
} ]
}
</pre>

The corresponding <tt>Got</tt> record matches on <tt>message</tt>. The message delivery in the product vat starts a new turn, turn 2.
Being at the top of a new turn, there is limited stack capture and getting a source span through Java reflection, is not practical.

Reporting true to <tt>teller</tt> has two log entries: a <tt>Sent</tt> and its corresponding <tt>Got</tt>.

<pre>
"class" : [ "org.ref_send.log.Sent", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 2,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/product/",
"number" : 2
}
},
"message" : "ewrigzpctikrhk-1-0",
"trace" : {
"calls" : [ {
"name" : "InventoryMaker.InventoryX.partInStock",
"source" : "org/waterken/purchase_ajax/InventoryMaker.java",
"span" : [ [ 19 ] ]
} ]
}
</pre>

The <tt>anchor</tt> uniquely identifies the origin of this message send as the 2nd messaging event from the product vat, turn 2.

<pre>
"class" : [ "org.ref_send.log.Got", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 1,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/",
"number" : 10
}
},
"message" : "ewrigzpctikrhk-1-0",
"trace" : {
"calls" : [ {
"name" : "AsyncAnd.run",
"source" : "org/waterken/purchase_ajax/AsyncAnd.java"
} ]
}
</pre>

The corresponding <tt>Got</tt> record matches on <tt>message</tt>. The message delivery in the buyer vat starts a new turn, turn 10.

=== Logging Promise-based Messaging in Waterken ===

Our example program implements a promise-based distributed procedure for handling new purchase orders. Before an order is placed, certain conditions must be met: the item is in stock and available, the customer's account is in good standing, and the delivery options are up to date.

An object residing in the "buyer" vat has remote references to objects residing in the "product" and "accounts" vats.

The buyer queries the remote objects with asynchronous (non-blocking) message sends. A promise is a placeholder for the answer to a query; when the answer becomes available the promise resolves to that value.

The code snippet below shows the 3 queries being fired off. The order of the incoming answers cannot be known. All 3 answers must be examined before the order is placed.

Collecting the answers is handled by an <code>AsyncAnd</code> object. The <code>run</code> method returns a promise for the result. By registering a when-block on the resolution of that promise, the invocation of <code>checkAnswers</code> is synchronized with the collection of the answers.

<pre>
Promise<Boolean> partP = _._(inventory).partInStock(partNo);
Promise<Boolean> creditP = _._(creditBureau).checkCredit(name);
Promise<Boolean> deliverP = _._(shipper).canDeliver(profile);

final Promise<Boolean> allOkP =
new AsyncAnd(_).run(partP, creditP, deliverP);

/*
* Register a when-block on promise returned by AsyncAnd.
* The block executes when the promise resolves (either
* fulfilled or rejected).
*/

_.when(allOkP, checkAnswers(_, inventory));
</pre>

We start with a detailed description of a single message, <code>partInStock</code>. Then we'll look at how <code>AsyncAnd</code> collects the answers and reports a final result.

[[Image:wk-promise-mechanics.png|alt=Waterken promise resolution]]

This graph describes the mechanics of Waterken promise resolution.

# buyer does an eventual send to product and registers a when-block on the resolution of that promise
# product receives the message and returns a result
# buyer receives the result and resolves the promise locally
# buyer executes the when-block

* The graph structure representing the message send and resolution
* The events logged
* The graph filter

[[Image:raw-d1-d2.png|alt=Raw, then filtered graph]]

Now, we can say more about the <code>AsyncAnd</code> logic.

In <code>AsyncAnd.run()</code> a promise-resolver pair implements the communication synchronization.

<pre>
public Promise<Boolean> run(Promise<Boolean>... answers) {
final Channel<Boolean> result = _.defer();
final int[] expected = {answers.length};
for (Promise<Boolean> answerP : answers) {

/*
* Register a when-block on each promise. The block executes
* when the promise resolves (either fulfilled or rejected).
*/

_.when(answerP, new DoAnswer(expected, result.resolver));
}
return result.promise;
}
</pre>

The <code>progress()</code> message captures a stack trace and logs a <tt>Progressed</tt> record to indicate that a state-based event contributed to the resolution of a promise. (If logging is off, it is a semantic no-op.)

Let's say all 3 answers are true and the promise eventually resolves to true. It's reasonable to think of all 3 answers as contributing to the resolution of the promise. The <code>progress()</code> message is used to promote state-based events to message order.

The arrival of the first 2 answers causes a local state change (a counter is decremented), while the last answer causes a message send. Without event promotion, the promise resolution would have a single cause: the last answer.

<pre>
public Void fulfill(Boolean answer) {
if (answer) {
myExpected[0]--;
if (myExpected[0] == 0) {
/*
* Resolve the promise with true.
*/
myResolver.apply(true);
} else {
/*
* Progress had been made in resolving the promise.
* If logging is on, a Progressed event record is written.
* If logging is off, this is a no-op.
*/
myResolver.progress();
}
} else {
/*
* Resolve the promise with false. Notice that this
* short-circuits the logic: any remaining expected answers
* are ignored.
*/
myResolver.apply(false);
}
}
</pre>

=== Trace Log Records for Waterken Promise Resolution ===

<pre>
"class" : [ "org.ref_send.log.Sent", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 2,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/",
"number" : 3
}
},
"message" : "jisyrc633lurdq-2-0",
"trace" : {
"calls" : [ {
"name" : "Buyer.Buy.fulfill",
"source" : "org/waterken/purchase_promise/Buyer.java",
"span" : [ [ 59 ] ]
}, {
"name" : "Buyer.Buy.fulfill",
"source" : "org/waterken/purchase_promise/Buyer.java",
"span" : [ [ 44 ] ]
} ]
}
</pre>

<pre>
"class" : [ "org.ref_send.log.Got", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 1,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/product/",
"number" : 2
}
},
"message" : "jisyrc633lurdq-2-0",
"trace" : {
"calls" : [ {
"name" : "InventoryMaker.InventoryX.partInStock",
"source" : "org/waterken/purchase_promise/InventoryMaker.java"
} ]
}
</pre>

<pre>
"class" : [ "org.ref_send.log.Returned", "org.ref_send.log.Sent", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 2,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/product/",
"number" : 2
}
},
"message" : "jisyrc633lurdq-2-0-return",
</pre>

<pre>
"class" : [ "org.ref_send.log.Got", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 1,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/",
"number" : 6
}
},
"message" : "jisyrc633lurdq-2-0-return",
</pre>

<pre>
"class" : [ "org.ref_send.log.Fulfilled", "org.ref_send.log.Resolved", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 2,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/",
"number" : 6
}
},
"condition" : "http://localhost:8080/-/buyer/#p3",
</pre>

<pre>
"class" : [ "org.ref_send.log.Got", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 1,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/",
"number" : 9
}
},
"message" : "http://localhost:8080/-/buyer/#w3",
"trace" : {
"calls" : [ {
"name" : "AsyncAnd.DoAnswer.fulfill",
"source" : "org/waterken/purchase_promise/AsyncAnd.java"
} ]
}
</pre>

<pre>
"class" : [ "org.ref_send.log.Progressed", "org.ref_send.log.Resolved", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 2,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/",
"number" : 9
}
},
"condition" : "http://localhost:8080/-/buyer/#p6",
"trace" : {
"calls" : [ {
"name" : "AsyncAnd.DoAnswer.fulfill",
"source" : "org/waterken/purchase_promise/AsyncAnd.java",
"span" : [ [ 52 ] ]
}, {
"name" : "AsyncAnd.DoAnswer.fulfill",
"source" : "org/waterken/purchase_promise/AsyncAnd.java",
"span" : [ [ 26 ] ]
} ]
}
</pre>

<pre>
"class" : [ "org.ref_send.log.Got", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 1,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/",
"number" : 15
}
},
"message" : "http://localhost:8080/-/buyer/#w6",
"trace" : {
"calls" : [ {
"name" : "Buyer.CheckAnswers.fulfill",
"source" : "org/waterken/purchase_promise/Buyer.java"
} ]
}
</pre>

Consider the sequence of events shown below.

[[Image:promise-part-in-stock.png|alt=Promise-based message send]]

Note: For the purpose of describing the trace records the screenshot shows events that actually will be filtered by Causeway and do not appear in the message-order view.

The registration of when-blocks, logged as <tt>SentIf</tt> records, are filtered from the message-order view, as they don't contribute to the understanding of message flow. However, they do appear in process-order, as shown below.

[[Image:sentifs-po-view.png|alt=SentIf events in process-order view]]

<pre>
"class" : [ "org.ref_send.log.SentIf", "org.ref_send.log.Sent", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 8,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/",
"number" : 3
}
},
"condition" : "http://localhost:8080/-/buyer/#p6",
"message" : "http://localhost:8080/-/buyer/#w6",
"trace" : {
"calls" : [ {
"name" : "Buyer.Buy.fulfill",
"source" : "org/waterken/purchase_promise/Buyer.java",
"span" : [ [ 72 ] ]
}, {
"name" : "Buyer.Buy.fulfill",
"source" : "org/waterken/purchase_promise/Buyer.java",
"span" : [ [ 44 ] ]
} ]
}
</pre>

<pre>
"class" : [ "org.ref_send.log.SentIf", "org.ref_send.log.Sent", "org.ref_send.log.Event" ],
"anchor" : {
"number" : 5,
"turn" : {
"loop" : "http://localhost:8080/-/buyer/",
"number" : 3
}
},
"condition" : "http://localhost:8080/-/buyer/#p3",
"message" : "http://localhost:8080/-/buyer/#w3",
"trace" : {
"calls" : [ {
"name" : "AsyncAnd.run",
"source" : "org/waterken/purchase_promise/AsyncAnd.java",
"span" : [ [ 87 ] ]
}, {
"name" : "Buyer.Buy.fulfill",
"source" : "org/waterken/purchase_promise/Buyer.java",
"span" : [ [ 63 ] ]
}, {
"name" : "Buyer.Buy.fulfill",
"source" : "org/waterken/purchase_promise/Buyer.java",
"span" : [ [ 44 ] ]
} ]
}
</pre>

=== Performance Issues in Waterken ===

Due to the expense of stack capture in Java, tracing in Waterken incurs roughly, an order of magnitude performance penalty. If tracing is off, there is no penalty.

Waterken guarantees message order delivery and in addition, if a connection is dropped, there's enough information to know about partial success. For example, if 2 messages (msg1, msg2) are sent from vat A to vat B, they are guaranteed to be processed in the order sent. If the connection is dropped after msg1 is successfully sent, when the connection is re-established, it is known that only msg2 must be resent.

The identifiers used to support these guarantees are also used for tracing. The advantage of these multi-purpose identifiers is there is no overhead when tracing is off (i.e., unique message identifiers, just for tracing, are not sent out over the wire.)

Note: Resending a message after a connection is re-established can result in 2 identical <tt>Sent</tt> events being logged. Causeway notices when the event records are identical and ignores the duplicate.

=== Logging Ajax-style Messaging in AmbientTalk ===

=== Logging Futures-based Messaging in AmbientTalk ===

=== Performance Issues in AmbientTalk ===

[[Category:Applications]]

Tstanley — Sat, 29 May 2010 00:50:32 GMT

Causeway

Tstanley — Wed, 26 May 2010 22:44:19 GMT

Tstanley: /* Menu Commands */

== Causeway: A message-oriented distributed debugger ==

Causeway is an open source postmortem distributed debugger for examining the behavior of distributed programs built as communicating event loops. Its message-oriented approach follows the flow of messages across process and machine boundaries.

== Getting Started ==

The simplest way to get started is to launch Causeway from a command line shell and then open one of the examples.

<pre>
$ cd e/src/esrc/scripts
$ rune causeway.e-swt
</pre>

From the Welcome view select an example program from the Help menu.

[[Image:Welcome-help.png]]

Optionally, the sources and trace logs can be specified on the command line.

<pre>
$ rune -Dsrc=<srcRootDir> causeway.e-swt <logs>...
</pre>

Java's default memory settings are sufficient for the examples but larger programs need more stack and heap space.
Use the -Xss (stack) and -Xmx (heap) options to increase Java default memory sizes. Follow the amount with m for Mb or k for Kb.
Notice the format does not follow the name=value convention. The J option tells rune to pass the option to Java.

<pre>
$ rune -J-Xss128m -J-Xmx128m causeway.e-swt
</pre>

== Waterken Example (Ajax-style) ==

This Java program ran on the Waterken server instrumented to generate Causeway's trace log format. The program is a distributed implementation of a procedure for handling new purchase orders.

Before an order is placed, certain conditions must be met: the item is in stock and available, the customer’s account is in good standing, and the delivery options are up to date. An object residing in the “buyer” process (or vat) has remote references to objects
residing in the “product” and “accounts” processes. The buyer queries the remote objects with asynchronous message sends. This example uses Ajax-style continuation-passing: a request carries a callback argument to which a response should be sent.

The screenshot below shows the principal views from Causeway's postmortem display for this example.

== Causeway Viewer ==

[[Image:viewer.png|alt=Causeway Viewer|Causeway Viewer]]

* Search view (leftmost): This view lists bookmarks and results of search commands.

* Process-order view: This view lists events in chronological order, organized by vat. For example, clicking the "buyer" tab shows all events logged by the buyer vat. The events are ordered by turn number and within each turn, an intra-turn number.

* Message-order view: This view shows the order in which events caused other events by sending messages. Message order is reflected in the outline structure: nested events were caused by the parent event. Causeway assigns each vat a color so we can see when message flow crosses vat boundaries.

* Stack Explorer and Source view: These views are familiar from sequential debugging.

=== Menu Commands ===

'''File >> Set Source Root...''' point at the root directory of the sources.

For example, for the trace record pathname shown below,

<pre>
"trace" : {
"calls" : [ {
"name" : "AsyncAnd.run",
"source" : "org/waterken/purchase_ajax/AsyncAnd.java"
} ]
}
</pre>

set the source root to the underlined prefix.

~/Desktop/waterken/example/src/org/waterken/purchase_ajax/AsyncAnd.java

''(Limitation: Cannot set multiple source roots.)''

'''File >> Open''' select log files to open.

''(Limitation: Cannot select a folder. Must go into the folder and select the multiple files.)''

'''File >> Export...''' translates Causeway's message graph (DAG) to the GraphViz DOT format and writes the dot file to a local disk. The dot file is a human-readable text file. It specifies a graph using the DOT language. [http://www.graphviz.org/ GraphViz] must be downloaded and installed to see the graph visualization. The graph below was generated for the Waterken example described above.

[[Image:messageGraph.png|alt=Causeway's DAG as GraphViz graph]]

'''Search >> Find Lost Messages''' reports sent messages that were apparently not received.

'''Tools >> Set Filter Options...''' presents all source files seen during parsing of the trace logs. Individual files can be filtered out.

[[Image:filter-async-and.png|alt=Filter options dialog]]

Here, <code>AsyncAnd.java</code> is selected and all stack frames whose source is in the <code>AsyncAnd</code> class are hidden. The resulting message-order view and GraphViz graph are simpler and more abstract.

[[Image:filtered-mov.png|alt=Message-order view with AsyncAnd.java filter]]

[[Image:filtered-mg.png|alt=Message graph with AsyncAnd.java filter]]

''(Limitation: These settings are not persistent across launches.)''

=== Context Menu Commands ===

'''Bookmark''' bookmarks the currently selected event.

[[Image:bookmark.png|alt=Bookmark menu item]]

'''Find Multiples''' finds the multiple causes of a joining event, e.g., finds the multiple sends to a target showing a multiples icon.

[[Image:find-multiples.png|alt=Find multiples menu item]]

'''Search Stacks''' finds all events that contain a stack frame for this source line, e.g., all events passing through this source code.

[[Image:search-stacks.png|alt=Search stacks menu item]]

''(Limitation: Matching events must match exactly on source and line position as specified in the trace logs. Not all lines in the source view can be searched and currently, there is no visual indication identifying the lines that can be searched.)''

== See Also ==

[[Causeway Platform Developer]] to understand how to instrument a platform to generate Causeway trace logs.

[http://www.hpl.hp.com/techreports/2009/HPL-2009-78.html HP Labs Technical Report] presents our experience with the Waterken web server which we have instrumented to generate Causeway's language-neutral trace log format.

[http://www.youtube.com/watch?v=QeqcGa7HlBk Screencast] presents a brief demonstration of Causeway, using the example from the HP Tech Report.

[http://waterken.sourceforge.net/debug/ Debugging a Waterken application] explains how to configure the Waterken server to emit the [[wikipedia:JSON|JSON]] debugging records understood by Causeway.

[http://code.google.com/p/ambienttalk/wiki/Debugging Debugging AmbientTalk using Causeway] explains how to emit Causeway debugging records, in order to use Causeway to debug AmbientTalk applications.

[[Category:Applications]]

File:Filtered-mg.png

Tstanley — Wed, 26 May 2010 21:53:59 GMT

Tstanley:

File:Filtered-mov.png

Tstanley — Wed, 26 May 2010 21:53:31 GMT

Tstanley:

Causeway

Tstanley — Wed, 26 May 2010 21:51:56 GMT

Tstanley: /* Menu Commands */

== Causeway: A message-oriented distributed debugger ==

Causeway is an open source postmortem distributed debugger for examining the behavior of distributed programs built as communicating event loops. Its message-oriented approach follows the flow of messages across process and machine boundaries.

== Getting Started ==

The simplest way to get started is to launch Causeway from a command line shell and then open one of the examples.

<pre>
$ cd e/src/esrc/scripts
$ rune causeway.e-swt
</pre>

From the Welcome view select an example program from the Help menu.

[[Image:Welcome-help.png]]

Optionally, the sources and trace logs can be specified on the command line.

<pre>
$ rune -Dsrc=<srcRootDir> causeway.e-swt <logs>...
</pre>

Java's default memory settings are sufficient for the examples but larger programs need more stack and heap space.
Use the -Xss (stack) and -Xmx (heap) options to increase Java default memory sizes. Follow the amount with m for Mb or k for Kb.
Notice the format does not follow the name=value convention. The J option tells rune to pass the option to Java.

<pre>
$ rune -J-Xss128m -J-Xmx128m causeway.e-swt
</pre>

== Waterken Example (Ajax-style) ==

This Java program ran on the Waterken server instrumented to generate Causeway's trace log format. The program is a distributed implementation of a procedure for handling new purchase orders.

Before an order is placed, certain conditions must be met: the item is in stock and available, the customer’s account is in good standing, and the delivery options are up to date. An object residing in the “buyer” process (or vat) has remote references to objects
residing in the “product” and “accounts” processes. The buyer queries the remote objects with asynchronous message sends. This example uses Ajax-style continuation-passing: a request carries a callback argument to which a response should be sent.

The screenshot below shows the principal views from Causeway's postmortem display for this example.

== Causeway Viewer ==

[[Image:viewer.png|alt=Causeway Viewer|Causeway Viewer]]

* Search view (leftmost): This view lists bookmarks and results of search commands.

* Process-order view: This view lists events in chronological order, organized by vat. For example, clicking the "buyer" tab shows all events logged by the buyer vat. The events are ordered by turn number and within each turn, an intra-turn number.

* Message-order view: This view shows the order in which events caused other events by sending messages. Message order is reflected in the outline structure: nested events were caused by the parent event. Causeway assigns each vat a color so we can see when message flow crosses vat boundaries.

* Stack Explorer and Source view: These views are familiar from sequential debugging.

=== Menu Commands ===

'''File >> Set Source Root...''' point at the root directory of the sources.

For example, for the trace record pathname shown below,

<pre>
"trace" : {
"calls" : [ {
"name" : "AsyncAnd.run",
"source" : "org/waterken/purchase_ajax/AsyncAnd.java"
} ]
}
</pre>

set the source root to the underlined prefix.

~/Desktop/waterken/example/src/org/waterken/purchase_ajax/AsyncAnd.java

''(Limitation: Cannot set multiple source roots.)''

'''File >> Open''' select log files to open.

''(Limitation: Cannot select a folder. Must go into the folder and select the multiple files.)''

'''File >> Export...''' translates Causeway's message graph (DAG) to the GraphViz DOT format and writes the dot file to a local disk. The dot file is a human-readable text file. It specifies a graph using the DOT language. [http://www.graphviz.org/ GraphViz] must be downloaded and installed to see the graph visualization. The graph below was generated for the Waterken example described above.

[[Image:messageGraph.png|alt=Causeway's DAG as GraphViz graph]]

'''Search >> Find Lost Messages''' reports sent messages that were apparently not received.

'''Tools >> Set Filter Options...''' presents all source files seen during parsing of the trace logs. Individual files can be filtered out.

''(Limitation: These settings are not persistent across launches.)''

[[Image:filter-async-and.png|alt=Filter options dialog]]

=== Context Menu Commands ===

'''Bookmark''' bookmarks the currently selected event.

[[Image:bookmark.png|alt=Bookmark menu item]]

'''Find Multiples''' finds the multiple causes of a joining event, e.g., finds the multiple sends to a target showing a multiples icon.

[[Image:find-multiples.png|alt=Find multiples menu item]]

'''Search Stacks''' finds all events that contain a stack frame for this source line, e.g., all events passing through this source code.

[[Image:search-stacks.png|alt=Search stacks menu item]]

''(Limitation: Matching events must match exactly on source and line position as specified in the trace logs. Not all lines in the source view can be searched and currently, there is no visual indication identifying the lines that can be searched.)''

== See Also ==

[[Causeway Platform Developer]] to understand how to instrument a platform to generate Causeway trace logs.

[http://www.hpl.hp.com/techreports/2009/HPL-2009-78.html HP Labs Technical Report] presents our experience with the Waterken web server which we have instrumented to generate Causeway's language-neutral trace log format.

[http://www.youtube.com/watch?v=QeqcGa7HlBk Screencast] presents a brief demonstration of Causeway, using the example from the HP Tech Report.

[http://waterken.sourceforge.net/debug/ Debugging a Waterken application] explains how to configure the Waterken server to emit the [[wikipedia:JSON|JSON]] debugging records understood by Causeway.

[http://code.google.com/p/ambienttalk/wiki/Debugging Debugging AmbientTalk using Causeway] explains how to emit Causeway debugging records, in order to use Causeway to debug AmbientTalk applications.

[[Category:Applications]]

File:Filter-async-and.png

Tstanley — Wed, 26 May 2010 21:50:42 GMT

Tstanley: