Monitor Changes with Edge Server
You can monitor changes in a keyspace using the keyspaces’s changes feed.
Sequences
The changes feed is based on sequences, which are abstract integer counters applied to documents. The changes feed returns the metadata (and optionally the contents) of documents that have changed since a specified sequence.
Initially, on first launch, the client returns a sequence of 0.
In this case, the changes feed lists every document in the keyspace.
The response from the changes feed includes a last_seq property.
Clients should save the value of the last_seq property; this is called a checkpoint, and represents the current sequence counter value.
On subsequent calls to the changes feed, the client may provide a checkpoint value using the ?since query parameter.
Set the value of this query parameter to the latest response’s last_seq property.
The the changes feed responds with only the documents that have changed since the specified checkpoint.
(It may be useful to add the query parameter ?active_only=true to suppress deleted document tombstones.
A new client has no need for this parameter.)
Push Changes
To avoid having to poll the changes feed, there are two alternate ways to invoke it that save bandwidth by waiting until changes arrive.
These are selected by adding a ?feed query parameter to the call.
-
The longpoll mode (
?feed=longpoll) is just like the regular changes feed, except that if there are no changes to report, it will wait to send a response until something happens. The client therefore should operate in a loop where it requests the feed, processes the response when it arrives, updates its checkpoint, and then requests the feed again with an updated?sincevalue. -
The continuous mode (
?feed=continuous) has a different, line-oriented, response format. Each change is reported as a separate JSON object, delimited by a newline (\n). The server sends all current changes, but never ends the response; instead it sends more changes as they occur.
Continuous mode is more efficient than longpoll, but can be harder to use since the response is sent using Transfer-Encoding: chunked.
Not all HTTP client libraries support this properly; some will wait until the response is complete and then decode it, which doesn’t work here because the response is never complete.
Both these modes support two options that help work around network issues or server crashes:
-
?heartbeat=Nrequests that the server send a newline character over the socket everyNmilliseconds. -
?timeout=Nrequests that the server close the connection if nothing’s happened forNmilliseconds.
If neither of these is given, the server will use a default timeout interval.
Examples
In the command line examples:
-
$USERand$PASSWORDare the credentials for Couchbase Edge Server. -
$CERTis the name and path to a TLS certificate file, for examplecert.cer. -
$HOSTand$PORTare the host and port to connect to Couchbase Edge Server, for examplelocalhost:59840.
Note that the following cURL examples use a self-signed TLS server certificate. In production, you are strongly recommended to use a TLS certificate generated by a well-known authority.
List All Changes
The following request lists all the changes for the specified keyspace.
shcurl --cacert $CERT --user $USER:$PASSWORD \
"https://$HOST:$PORT/travel-sample.inventory.airport/_changes"
The response is a JSON object similar to the following. The results below are truncated to save space.
json{
"results": [
{
"seq": 0,
"id": "~XEltbV2jxLN04FDFsZED5_",
"changes": [
{
"rev": "1-22f5be403d75646a0758fab6731d7fa87c197666"
}
]
},
{
"seq": 1,
"id": "~AxF827yGbOQprwFMNaotw2",
"changes": [
{
"rev": "1-22855783cf597c31c37ec3815d8027f3706ef6f9"
}
]
},
// ...
{
"seq": 1986,
"id": "~nfhr-PhlAOo-WyzVvrpRpN",
"deleted": true,
"changes": [
{
"rev": "2-cd8cfb870756c1116ae91ca64772f7f05be502b5"
}
]
}
],
"last_seq": 1986
}
Note the last_seq property.
You can use this in a subsequent request to check for changes since this checkpoint.
List Changes Since Last Checkpoint
The following request lists all the changes that have been made to the specified keyspace since the specified checkpoint.
shcurl --cacert $CERT --user $USER:$PASSWORD \
"https://$HOST:$PORT/travel-sample.inventory.airport/_changes?since=1986"
The response is a JSON object similar to the following. In this case, only one change has been made to one document since the specified checkpoint.
json{
"results": [
{
"seq": 1987,
"id": "~aN-Bmy8YthJlRuBOSYWfU-",
"changes": [
{
"rev": "1-22855783cf597c31c37ec3815d8027f3706ef6f9"
}
]
}
],
"last_seq": 1987
}
Get Continuous Changes Feed
The following request returns a continuous feed of changes that have been made to the specified keyspace since the specified checkpoint.
shcurl --cacert $CERT --user $USER:$PASSWORD \
"https://$HOST:$PORT/travel-sample.inventory.airport/_changes?since=1986&feed=continuous&timeout=5000"
The response is a JSON object similar to the following.
json{
"seq": 1987,
"id": "~aN-Bmy8YthJlRuBOSYWfU-",
"changes": [
{
"rev": "1-22855783cf597c31c37ec3815d8027f3706ef6f9"
}
]
}
The REST API client then waits for the specified duration before timing out. If any further changes occur in the keyspace during that time, they are listed as they occur.