From 554322b4e3bb0d64a90af17a9180067ca116aa47 Mon Sep 17 00:00:00 2001 From: Ian Costanzo Date: Wed, 18 Mar 2020 13:18:22 -0700 Subject: [PATCH 1/5] JSON samples for decorator and trace message Signed-off-by: Ian Costanzo --- features/0034-message-tracing/README.md | 41 +++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/features/0034-message-tracing/README.md b/features/0034-message-tracing/README.md index f3ca3b348..ebea6023d 100644 --- a/features/0034-message-tracing/README.md +++ b/features/0034-message-tracing/README.md @@ -62,6 +62,34 @@ Tracing is requested by decorating the JSON plaintext of an DIDComm message (whi [![example of ~trace](msg-with-trace.png)](msg-with-trace.json) +``` +{ + "@type": "did:sov:...", + "@id": "abc-def-...", + "msg": "U2Vl...", + "~trace": { + "target": "http://example.com/tracer", + "full_thread": true + } +} +``` + +``` +{ + "@type": "did:sov:...", + "@id": "abc-def-...", + "msg": "U2Vl...", + "~trace": { + "target": "message", + "full_thread": true, + "trace_reports": [{}, {}, ...] + } +} +``` + +The `"target"` can refer to a url (as above) or the term `"message"`, which is a request to +append trace information to the message itself. + This example asks the handler of the message to perform an HTTP POST of a __trace report__ about the message to the URI `http://example.com/tracer`. @@ -87,6 +115,19 @@ The body of the HTTP request (the _trace report_) is a JSON document that looks [![trace report](trace-report.png)](trace-report.json) +``` +{ + "@type": "did:sov:.../1.0/trace_report", + "msg_id": {"id": "abc-def-...df", "seq": 1}, + "thread_id": {"thid": "hij-klm-nop-...qr", "sender_order": 1}, + "handler": "did:sov:1234abcd#3", + "ellapsed_milli": 27, + "traced_type": "did:sov:...", + "timestamp": "2018-03-27 18:23:45.123Z", + "outcome": "OK ..." +} +``` + ### Subtleties ##### Message IDs From 70f538728cb7af5c4fffe189ae9f32c9f6cfa7ce Mon Sep 17 00:00:00 2001 From: Ian Costanzo Date: Wed, 8 Apr 2020 08:25:19 -0700 Subject: [PATCH 2/5] Updated json examples Signed-off-by: Ian Costanzo --- features/0034-message-tracing/README.md | 20 ++++---------------- 1 file changed, 4 insertions(+), 16 deletions(-) diff --git a/features/0034-message-tracing/README.md b/features/0034-message-tracing/README.md index ebea6023d..ee2fff13a 100644 --- a/features/0034-message-tracing/README.md +++ b/features/0034-message-tracing/README.md @@ -74,19 +74,6 @@ Tracing is requested by decorating the JSON plaintext of an DIDComm message (whi } ``` -``` -{ - "@type": "did:sov:...", - "@id": "abc-def-...", - "msg": "U2Vl...", - "~trace": { - "target": "message", - "full_thread": true, - "trace_reports": [{}, {}, ...] - } -} -``` - The `"target"` can refer to a url (as above) or the term `"message"`, which is a request to append trace information to the message itself. @@ -118,12 +105,13 @@ The body of the HTTP request (the _trace report_) is a JSON document that looks ``` { "@type": "did:sov:.../1.0/trace_report", - "msg_id": {"id": "abc-def-...df", "seq": 1}, - "thread_id": {"thid": "hij-klm-nop-...qr", "sender_order": 1}, + "msg_id": "abc-def-...df", + "thread_id": "hij-klm-nop-...qr", "handler": "did:sov:1234abcd#3", "ellapsed_milli": 27, "traced_type": "did:sov:...", - "timestamp": "2018-03-27 18:23:45.123Z", + "str_time": "2018-03-27 18:23:45.123Z", + "timestamp": "1234567890.123456", "outcome": "OK ..." } ``` From 633d2cb86884f921463ffdfecca4f8faf3abaf3a Mon Sep 17 00:00:00 2001 From: Ian Costanzo Date: Wed, 8 Apr 2020 14:58:26 -0700 Subject: [PATCH 3/5] Fixed readme Signed-off-by: Ian Costanzo --- features/0034-message-tracing/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/features/0034-message-tracing/README.md b/features/0034-message-tracing/README.md index ee2fff13a..96ba26da6 100644 --- a/features/0034-message-tracing/README.md +++ b/features/0034-message-tracing/README.md @@ -74,8 +74,8 @@ Tracing is requested by decorating the JSON plaintext of an DIDComm message (whi } ``` -The `"target"` can refer to a url (as above) or the term `"message"`, which is a request to -append trace information to the message itself. +The `"target"` can refer to a url (as above) or the term `"log"`, which is a request to +append trace information to the standard log file. This example asks the handler of the message to perform an HTTP POST of a __trace report__ about the message to the URI `http://example.com/tracer`. From 2945583c2ce0c2a6eeb92a8c947c39de294a5dec Mon Sep 17 00:00:00 2001 From: Ian Costanzo Date: Mon, 27 Jul 2020 07:45:23 -0700 Subject: [PATCH 4/5] Updated tracing pr Signed-off-by: Ian Costanzo --- features/0034-message-tracing/README.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/features/0034-message-tracing/README.md b/features/0034-message-tracing/README.md index 96ba26da6..33c8f4cda 100644 --- a/features/0034-message-tracing/README.md +++ b/features/0034-message-tracing/README.md @@ -64,7 +64,7 @@ Tracing is requested by decorating the JSON plaintext of an DIDComm message (whi ``` { - "@type": "did:sov:...", + "@type": "did:sov:BzCBs...;spec/routing/1.0/forward", "@id": "abc-def-...", "msg": "U2Vl...", "~trace": { @@ -75,7 +75,8 @@ Tracing is requested by decorating the JSON plaintext of an DIDComm message (whi ``` The `"target"` can refer to a url (as above) or the term `"log"`, which is a request to -append trace information to the standard log file. +append trace information to the standard log file. (Information can then be manually +collated from agents.) This example asks the handler of the message to perform an HTTP POST of a __trace report__ about the message to the URI `http://example.com/tracer`. @@ -104,12 +105,12 @@ The body of the HTTP request (the _trace report_) is a JSON document that looks ``` { - "@type": "did:sov:.../1.0/trace_report", + "@type": "did:sov:BzCBs...;spec/1.0/trace_report", "msg_id": "abc-def-...df", "thread_id": "hij-klm-nop-...qr", "handler": "did:sov:1234abcd#3", "ellapsed_milli": 27, - "traced_type": "did:sov:...", + "traced_type": "did:sov:BzCBs...;spec/routing/1.0/forward", "str_time": "2018-03-27 18:23:45.123Z", "timestamp": "1234567890.123456", "outcome": "OK ..." @@ -126,7 +127,7 @@ connection when the reports are analyzed together. ![tracing unrelated messages](trace-xyz.png) -To solve this problem, traced messages use an ID convention that permits ordering. +To solve this problem, traced messages *may* use an ID convention that permits ordering. Assume that the inner application message has a base ID, _X_. Containing messages (e.g., `forward` messages) have IDs in the form _X_.1, _X_.2, _X_.3, and so forth -- where numbers represent the order in @@ -216,8 +217,9 @@ plaintext of the report, as utf8. * `@type`: Should always be `"did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/tracing/1.0/trace_report"`, or some evolved version thereof. Required for version control and to support trace sinks that process other HTTP payloads as well. -* `for_id`: The ID of the message that the handler is looking at when it composes the +* `msg_id`: The ID of the message that the handler is looking at when it composes the trace report. Required. +* `thread_id`: The ID of the protocol thread. Required. * `handler`: A string that identifies the handler in a way that's useful for troubleshooting purposes. For example, it might identify a particular agent by DID+keyref, or it might be a friendly string like "iPhone" or "AgentsRUs Cloud Agent, geocaching extension v1.3.7". Optional but @@ -226,9 +228,10 @@ plaintext of the report, as utf8. the trace report? If the same handler emits more than one trace report, how long has it been since the last trace was composed? Optional but encouraged. * `traced_type`: What was the message type of the traced message? Optional but encouraged. -* `report_time`: What was the UTC timestamp of the system clock of the handler +* `str_time`: What was the UTC timestamp of the system clock of the handler when the handler composed the trace report? ISO 8601 format with millisecond precision. Optional but encouraged. +* `timestamp`: Value fo the `str_time` field in milliseconds (UNIX time format). * `outcome`: A string that describes the outcome of the message handling. The string MUST begin with one of the following tokens: `"OK"` (meaning the handler completed its processing successfully; `"ERR"` (the handler failed), or `"PEND"` (the handler is still working on the From f7e1bff1b6277fdf42e639d5597a4676651610ea Mon Sep 17 00:00:00 2001 From: Ian Costanzo Date: Mon, 27 Jul 2020 07:46:17 -0700 Subject: [PATCH 5/5] Updated tracing pr Signed-off-by: Ian Costanzo --- features/0034-message-tracing/README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/features/0034-message-tracing/README.md b/features/0034-message-tracing/README.md index 33c8f4cda..80ba3c424 100644 --- a/features/0034-message-tracing/README.md +++ b/features/0034-message-tracing/README.md @@ -60,8 +60,6 @@ Tracing is requested by decorating the JSON plaintext of an DIDComm message (whi and handled at its final destination) with the `~trace` attribute. Here is the simplest possible example: -[![example of ~trace](msg-with-trace.png)](msg-with-trace.json) - ``` { "@type": "did:sov:BzCBs...;spec/routing/1.0/forward", @@ -101,8 +99,6 @@ even if it is expired or invalid. The rationale for this choice is: The body of the HTTP request (the _trace report_) is a JSON document that looks like this: -[![trace report](trace-report.png)](trace-report.json) - ``` { "@type": "did:sov:BzCBs...;spec/1.0/trace_report",