Commit 53c32b76 authored by Peter Waher's avatar Peter Waher

Troubleshooting using sniffers

parent e3250562
......@@ -1196,6 +1196,54 @@ Event sent in a `message` from concentrator to subscriber, when a node has been
Troubleshooting
---------------------
Clients with sufficient privileges can, if the concentrator supports it, use *sniffers* to troubleshoot communication problems in remote devices controlled
by the concentrator. This is particularly relevant if the concentrator is a protocol bridge. To troubleshoot communication, the client can register a
*sniffer* with the corresponding node. If accepted, the concentrator will update the client on what communication is occurring on the node, by sending
event messages to the client.
### registerSniffer
Registers a sniffer on a node in a concentrator, for troubleshooting. The `registerSniffer` element is sent in an `iq set` to the concentrator, which
responds with a `sniffer` element if accepting the request. All sniffers have an expiry point in time. The client can request a given expiry time, but
the concentrator decides how long a sniffer is allowed to be active.
| Element | Attribute | Type | Use | Default | Description |
|:--------------------|:------------------|:--------------|:---------|:---------|:--------------------------------------------------------------------------------------------------------------------|
| `registerSniffer` | `id` | `xs:string` | required | | Node identity. |
| | `src` | `xs:string` | optional | | Source identity. |
| | `pt` | `xs:string` | optional | | Partition. |
| | `expires` | `xs:dateTime` | optional | | Requested expiry time. If not provided, the concentrator automatically chooses an expiration date and time. |
| `sniffer` | | | | | Contains information about a sniffer in the concentrator. |
| | `snifferId` | `xs:string` | required | | Sniffer identity, selected by the concentrator. |
| | `expires` | `xs:dateTime` | required | | When the sniffer automatically expires. |
### unregisterSniffer
Unregisters a sniffer on a node in a concentrator, before it expires. The `unregisterSniffer` element is sent in an `iq set` to the concentrator, which
responds with an empty response if accepting the request.
| Element | Attribute | Type | Use | Default | Description |
|:--------------------|:------------------|:--------------|:---------|:---------|:--------------------------------------------------------------------------------------------------------------------|
| `unregisterSniffer` | `id` | `xs:string` | required | | Node identity. |
| | `src` | `xs:string` | optional | | Source identity. |
| | `pt` | `xs:string` | optional | | Partition. |
| | `snifferId` | `xs:string` | required | | Sniffer identity. |
### sniff
The concentrator asynchronously updates the client on what the sniffer records by sending `message` stanzas to the client containing the `sniff` element. This
element in turn contains child elements describing what has happened.
| Element | Attribute | Type | Use | Default | Description |
|:---------------------------|:------------------|:------------------------|:---------|:---------|:--------------------------------------------|
| `sniff` | `snifferId` | `xs:string` | required | | Sniffer identity. |
| | `timestamp` | `xs:dateTime` | required | | Timestamp of message. |
| `expired` | | | | | Informs the client the sniffer has expired. |
| `rxBin` | (value) | `xs:base64Binary` | | | Binary data has been received. |
| `txBin` | (value) | `xs:base64Binary` | | | Binary data has been transmitted. |
| `rx` | (value) | `xs:string` | | | Text has been received. |
| `tx` | (value) | `xs:string` | | | Text has been transmitted. |
| `info` | (value) | `xs:string` | | | Information about what is happening. |
| `warning` | (value) | `xs:string` | | | A warning message. |
| `error` | (value) | `xs:string` | | | An error message. |
| `exception` | (value) | `xs:string` | | | An exception message. |
......@@ -1944,8 +1944,8 @@ purposes.
<xs:element name='sniff'>
<xs:annotation>
<xs:documentation>Any event during the execution of a node query is reported asynchronously in separate messages sent from the concentrator to the client executing the query.</xs:documentation>
<xs:documentation>Each message contains a queryProgress element, with one or more child elements containing information about the progress.</xs:documentation>
<xs:documentation>Any event detected by a sniffer is reported asynchronously in separate messages sent from the concentrator to the client that registered the sniffer.</xs:documentation>
<xs:documentation>Each message contains a sniff element, with one or more child elements containing information about what was detected.</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:choice minOccurs='1' maxOccurs='unbounded'>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment