Replication logger commands

All data-modification operations are written to the server’s write-ahead log and are not handled by a separate replication logger.

You can query the current state of the logger and fetch the latest changes written by the logger with the logger-state method. The operations return the state and data from the write-ahead log.

To query the latest changes logged by the replication logger, the HTTP interface also provides the logger-follow method. This method should be used by replication clients to incrementally fetch updates from an ArangoDB database.

To check what range of changes is available (identified by tick values), the HTTP interface provides the methods logger-first-tick and logger-tick-ranges. Replication clients can use the methods to determine if certain data (identified by a tick date) is still available on the Leader.

Return replication logger state

returns the state of the replication logger

GET /_api/replication/logger-state

Returns the current state of the server’s replication logger. The state will include information about whether the logger is running and about the last logged tick value. This tick value is important for incremental fetching of data.

The body of the response contains a JSON object with the following attributes:

state: the current logger state as a JSON object with the following sub-attributes:
- running: whether or not the logger is running
- lastLogTick: the tick value of the latest tick the logger has logged. This value can be used for incremental fetching of log data.
- totalEvents: total number of events logged since the server was started. The value is not reset between multiple stops and re-starts of the logger.
- time: the current date and time on the logger server
server: a JSON object with the following sub-attributes:
- version: the logger server’s version
- serverId: the logger server’s id
clients: returns the last fetch status by replication clients connected to the logger. Each client is returned as a JSON object with the following attributes:
- syncerId: id of the client syncer
- serverId: server id of client
- lastServedTick: last tick value served to this client via the WAL tailing API
- time: date and time when this client last called the WAL tailing API

Responses

HTTP 200: is returned if the logger state could be determined successfully.

HTTP 405: is returned when an invalid HTTP method is used.

HTTP 500: is returned if the logger state could not be determined.

Examples

Returns the state of the replication logger.

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-state

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 225
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "state" : { 
    "running" : true, 
    "lastLogTick" : "185816", 
    "lastUncommittedLogTick" : "185816", 
    "totalEvents" : 185816, 
    "time" : "2023-04-04T12:47:44Z" 
  }, 
  "server" : { 
    "version" : "3.10.6", 
    "serverId" : "232992565677151", 
    "engine" : "rocksdb" 
  }, 
  "clients" : [ ] 
}

Hide response body

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-state

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 225
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Show response body

Returns log entries

Fetch log lines from the server

GET /_api/replication/logger-follow

This route should no longer be used. It is considered as deprecated from version 3.4.0 on. Client applications should use the REST API endpoint /_api/wal/tail instead.

Query Parameters

from (number, optional): Exclusive lower bound tick value for results.
to (number, optional): Inclusive upper bound tick value for results.
chunkSize (number, optional): Approximate maximum size of the returned result.
includeSystem (boolean, optional): Include system collections in the result. The default value is true.

Returns data from the server’s replication log. This method can be called by replication clients after an initial synchronization of data. The method will return all “recent” log entries from the logger server, and the clients can replay and apply these entries locally so they get to the same data state as the logger server.

Clients can call this method repeatedly to incrementally fetch all changes from the logger server. In this case, they should provide the from value so they will only get returned the log events since their last fetch.

When the from query parameter is not used, the logger server will return log entries starting at the beginning of its replication log. When the from parameter is used, the logger server will only return log entries which have higher tick values than the specified from value (note: the log entry with a tick value equal to from will be excluded). Use the from value when incrementally fetching log data.

The to query parameter can be used to optionally restrict the upper bound of the result to a certain tick value. If used, the result will contain only log events with tick values up to (including) to. In incremental fetching, there is no need to use the to parameter. It only makes sense in special situations, when only parts of the change log are required.

The chunkSize query parameter can be used to control the size of the result. It must be specified in bytes. The chunkSize value will only be honored approximately. Otherwise a too low chunkSize value could cause the server to not be able to put just one log entry into the result and return it. Therefore, the chunkSize value will only be consulted after a log entry has been written into the result. If the result size is then bigger than chunkSize, the server will respond with as many log entries as there are in the response already. If the result size is still smaller than chunkSize, the server will try to return more data if there’s more data left to return.

If chunkSize is not specified, some server-side default value will be used.

The Content-Type of the result is application/x-arango-dump. This is an easy-to-process format, with all log events going onto separate lines in the response body. Each log event itself is a JSON object, with at least the following attributes:

tick: the log event tick value
type: the log event type

Individual log events will also have additional attributes, depending on the event type. A few common attributes which are used for multiple events types are:

cid: id of the collection the event was for
tid: id of the transaction the event was contained in
key: document key
rev: document revision id
data: the original document data

The response will also contain the following HTTP headers:

x-arango-replication-active: whether or not the logger is active. Clients can use this flag as an indication for their polling frequency. If the logger is not active and there are no more replication events available, it might be sensible for a client to abort, or to go to sleep for a long time and try again later to check whether the logger has been activated.
x-arango-replication-lastincluded: the tick value of the last included value in the result. In incremental log fetching, this value can be used as the from value for the following request. Note that if the result is empty, the value will be 0. This value should not be used as from value by clients in the next request (otherwise the server would return the log events from the start of the log again).
x-arango-replication-lasttick: the last tick value the logger server has logged (not necessarily included in the result). By comparing the last tick and last included tick values, clients have an approximate indication of how many events there are still left to fetch.
x-arango-replication-checkmore: whether or not there already exists more log data which the client could fetch immediately. If there is more log data available, the client could call logger-follow again with an adjusted from value to fetch remaining log entries until there are no more.

If there isn’t any more log data to fetch, the client might decide to go to sleep for a while before calling the logger again.

Note: this method is not supported on a Coordinator in a cluster.

Responses

HTTP 200: is returned if the request was executed successfully, and there are log events available for the requested range. The response body will not be empty in this case.

HTTP 204: is returned if the request was executed successfully, but there are no log events available for the requested range. The response body will be empty in this case.

HTTP 400: is returned if either the from or to values are invalid.

HTTP 405: is returned when an invalid HTTP method is used.

HTTP 500: is returned if an error occurred while assembling the response.

HTTP 501: is returned when this operation is called on a Coordinator in a cluster.

Examples

No log events available

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-follow?from=185786

HTTP/1.1 204 No Content
content-type: application/x-arango-dump
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 0
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-arango-replication-active: true
x-arango-replication-checkmore: false
x-arango-replication-frompresent: true
x-arango-replication-lastincluded: 0
x-arango-replication-lastscanned: 185783
x-arango-replication-lasttick: 185786
x-content-type-options: nosniff

A few log events (One JSON document per line)

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-follow?from=185786

HTTP/1.1 200 OK
content-type: application/x-arango-dump
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 1612
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-arango-replication-active: true
x-arango-replication-checkmore: false
x-arango-replication-frompresent: true
x-arango-replication-lastincluded: 185816
x-arango-replication-lastscanned: 185816
x-arango-replication-lasttick: 185816
x-content-type-options: nosniff

{ 
  "tick" : "185789", 
  "type" : 2300, 
  "database" : "1", 
  "tid" : "0", 
  "cid" : "4", 
  "cname" : "_users", 
  "data" : { 
    "_key" : "83", 
    "_id" : "_users/83", 
    "_rev" : "_fyvNDKO---", 
    "user" : "root", 
    "source" : "LOCAL", 
    "authData" : { 
      "active" : true, 
      "simple" : { 
        "hash" : "a086cd958473665634e960336f6b1431b0780eb6bfc86b9c1fb9fe3811a6494c", 
        "salt" : "59ce3ee3", 
        "method" : "sha256" 
      } 
    }, 
    "databases" : { 
      "*" : { 
        "permissions" : { 
          "read" : true, 
          "write" : true 
        }, 
        "collections" : { 
          "*" : { 
            "permissions" : { 
              "read" : true, 
              "write" : true 
            } 
          } 
        } 
      }, 
      "_system" : { 
        "permissions" : { 
          "read" : true, 
          "write" : true 
        }, 
        "collections" : { 
          "animals" : { 
            "permissions" : { 
              "read" : true, 
              "write" : true 
            } 
          }, 
          "*" : { 
            "permissions" : { 
              "read" : true, 
              "write" : true 
            } 
          }, 
          "demo" : { 
            "permissions" : { 
              "read" : true, 
              "write" : true 
            } 
          }, 
          "products" : { 
            "permissions" : { 
              "read" : true, 
              "write" : true 
            } 
          }, 
          "products1" : { 
            "permissions" : { 
              "read" : true, 
              "write" : true 
            } 
          } 
        } 
      } 
    } 
  } 
}↩
{ 
  "tick" : "185802", 
  "type" : 2001, 
  "database" : "1", 
  "cuid" : "hD3E7CF1CCC5F/70735", 
  "cid" : "70735", 
  "data" : { 
    "id" : "70735", 
    "name" : "" 
  } 
}↩
{ 
  "tick" : "185810", 
  "type" : 2300, 
  "database" : "1", 
  "tid" : "0", 
  "cid" : "4", 
  "cname" : "_users", 
  "data" : { 
    "_key" : "83", 
    "_id" : "_users/83", 
    "_rev" : "_fyvNDKa---", 
    "user" : "root", 
    "source" : "LOCAL", 
    "authData" : { 
      "active" : true, 
      "simple" : { 
        "hash" : "a086cd958473665634e960336f6b1431b0780eb6bfc86b9c1fb9fe3811a6494c", 
        "salt" : "59ce3ee3", 
        "method" : "sha256" 
      } 
    }, 
    "databases" : { 
      "_system" : { 
        "permissions" : { 
          "read" : true, 
          "write" : true 
        }, 
        "collections" : { 
          "products1" : { 
            "permissions" : { 
              "read" : true, 
              "write" : true 
            } 
          }, 
          "demo" : { 
            "permissions" : { 
              "read" : true, 
              "write" : true 
            } 
          }, 
          "*" : { 
            "permissions" : { 
              "read" : true, 
              "write" : true 
            } 
          }, 
          "animals" : { 
            "permissions" : { 
              "read" : true, 
              "write" : true 
            } 
          } 
        } 
      }, 
      "*" : { 
        "permissions" : { 
          "read" : true, 
          "write" : true 
        }, 
        "collections" : { 
          "*" : { 
            "permissions" : { 
              "read" : true, 
              "write" : true 
            } 
          } 
        } 
      } 
    } 
  } 
}↩

Hide response body

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-follow?from=185786

HTTP/1.1 200 OK
content-type: application/x-arango-dump
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 1612
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-arango-replication-active: true
x-arango-replication-checkmore: false
x-arango-replication-frompresent: true
x-arango-replication-lastincluded: 185816
x-arango-replication-lastscanned: 185816
x-arango-replication-lasttick: 185816
x-content-type-options: nosniff

Show response body

More events than would fit into the response

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-follow?from=185760&chunkSize=400

HTTP/1.1 200 OK
content-type: application/x-arango-dump
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 773
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-arango-replication-active: true
x-arango-replication-checkmore: true
x-arango-replication-frompresent: true
x-arango-replication-lastincluded: 185765
x-arango-replication-lastscanned: 185762
x-arango-replication-lasttick: 185786
x-content-type-options: nosniff

{ 
  "tick" : "185763", 
  "type" : 2300, 
  "database" : "1", 
  "tid" : "0", 
  "cid" : "4", 
  "cname" : "_users", 
  "data" : { 
    "_key" : "83", 
    "_id" : "_users/83", 
    "_rev" : "_fyvNCJS---", 
    "user" : "root", 
    "source" : "LOCAL", 
    "authData" : { 
      "active" : true, 
      "simple" : { 
        "hash" : "a086cd958473665634e960336f6b1431b0780eb6bfc86b9c1fb9fe3811a6494c", 
        "salt" : "59ce3ee3", 
        "method" : "sha256" 
      } 
    }, 
    "databases" : { 
      "*" : { 
        "permissions" : { 
          "read" : true, 
          "write" : true 
        }, 
        "collections" : { 
          "*" : { 
            "permissions" : { 
              "read" : true, 
              "write" : true 
            } 
          } 
        } 
      }, 
      "_system" : { 
        "permissions" : { 
          "read" : true, 
          "write" : true 
        }, 
        "collections" : { 
          "animals" : { 
            "permissions" : { 
              "read" : true, 
              "write" : true 
            } 
          }, 
          "*" : { 
            "permissions" : { 
              "read" : true, 
              "write" : true 
            } 
          }, 
          "demo" : { 
            "permissions" : { 
              "read" : true, 
              "write" : true 
            } 
          }, 
          "products" : { 
            "permissions" : { 
              "read" : true, 
              "write" : true 
            } 
          }, 
          "products1" : { 
            "permissions" : { 
              "read" : true, 
              "write" : true 
            } 
          } 
        } 
      } 
    } 
  } 
}

Hide response body

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-follow?from=185760&chunkSize=400

HTTP/1.1 200 OK
content-type: application/x-arango-dump
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 773
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-arango-replication-active: true
x-arango-replication-checkmore: true
x-arango-replication-frompresent: true
x-arango-replication-lastincluded: 185765
x-arango-replication-lastscanned: 185762
x-arango-replication-lasttick: 185786
x-content-type-options: nosniff

Show response body

Returns the first available tick value

Return the first available tick value from the server

GET /_api/replication/logger-first-tick

Returns the first available tick value that can be served from the server’s replication log. This method can be called by replication clients after to determine if certain data (identified by a tick value) is still available for replication.

The result is a JSON object containing the attribute firstTick. This attribute contains the minimum tick value available in the server’s replication log.

Note: this method is not supported on a Coordinator in a cluster.

Responses

HTTP 200: is returned if the request was executed successfully.

HTTP 405: is returned when an invalid HTTP method is used.

HTTP 500: is returned if an error occurred while assembling the response.

HTTP 501: is returned when this operation is called on a Coordinator in a cluster.

Examples

Returning the first available tick

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-first-tick

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 22
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "firstTick" : "180684" 
}

Return the tick ranges available in the WAL logfiles

returns the tick value ranges available in the logfiles

GET /_api/replication/logger-tick-ranges

Returns the currently available ranges of tick values for all currently available WAL logfiles. The tick values can be used to determine if certain data (identified by tick value) are still available for replication.

The body of the response contains a JSON array. Each array member is an object that describes a single logfile. Each object has the following attributes:

datafile: name of the logfile
status: status of the datafile, in textual form (e.g. “sealed”, “open”)
tickMin: minimum tick value contained in logfile
tickMax: maximum tick value contained in logfile

Responses

HTTP 200: is returned if the tick ranges could be determined successfully.

HTTP 405: is returned when an invalid HTTP method is used.

HTTP 500: is returned if the logger state could not be determined.

HTTP 501: is returned when this operation is called on a Coordinator in a cluster.

Examples

Returns the available tick ranges.

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-tick-ranges

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 458
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

[ 
  { 
    "datafile" : "/archive/000086.log", 
    "status" : "collected", 
    "tickMin" : "180684", 
    "tickMax" : "180774" 
  }, 
  { 
    "datafile" : "/archive/000110.log", 
    "status" : "collected", 
    "tickMin" : "180774", 
    "tickMax" : "180817" 
  }, 
  { 
    "datafile" : "/archive/000117.log", 
    "status" : "collected", 
    "tickMin" : "180817", 
    "tickMax" : "181380" 
  }, 
  { 
    "datafile" : "/archive/000119.log", 
    "status" : "collected", 
    "tickMin" : "181380", 
    "tickMax" : "181399" 
  }, 
  { 
    "datafile" : "/000126.log", 
    "status" : "open", 
    "tickMin" : "181399", 
    "tickMax" : "185816" 
  } 
]

Hide response body

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-tick-ranges

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 458
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Show response body

❮ Replication Dump Replication Applier ❯