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.

+

=== 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>

<pre>

$ rune -Dcauseway_debug=true causeway.e-swt

$ rune -Dcauseway_debug=true causeway.e-swt

Line 32:

Line 36:

''(''

''(''

'''Note:'''

'''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.)''

+

''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.)''

Line 38:

Line 42:

-

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.

+

* Support for visualizing graph filter algorithm

-

+

-

# 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>)

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.

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.

Line 50:

Line 49:

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

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

+

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

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

Line 74:

Line 74:

|}

|}

+

Individual tree items 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>)

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

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

Line 117:

Line 124:

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

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>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.

+

''(''

+

'''Note:'''

+

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

<pre>

<pre>

Line 508:

Line 519:

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.)

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.

+

''(''

+

'''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.)''

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.

$ rune -Dcauseway_debug=true causeway.e-swt

(Note:When this debug option is set, Causeway's JSON parser uses getTwine(). 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.)

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/.

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

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

Individual tree items 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 text field string. This field is required for Comment records; it is optional for Sent, SentIf, and Resolved 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. _._(inventory).partInStock(partNo, teller);)

If there's no span, source file name and function name specified in the top stack entry. (e.g. [buyer, 8] AsyncAnd.run)

If nothing else, a Causeway comment. (e.g. ## unknown sender)

Logging Ajax-style Messaging in Waterken

Consider the sequence of events shown below.

a remote inventory object is queried for the availability of a part

the inventory object reports true to teller, a callback object

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

The corresponding Got record matches on message. 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 teller has two log entries: a Sent and its corresponding Got.

The corresponding Got record matches on message. 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 AsyncAnd object. The run method returns a promise for the result. By registering a when-block on the resolution of that promise, the invocation of checkAnswers is synchronized with the collection of the answers.

The progress() message captures a stack trace and logs a Progressed 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 progress() 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.

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);
}
}

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 SentIf 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.

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 Sent events being logged. Causeway notices when the event records are identical and ignores the duplicate.)