forked from superfly/docs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
events.html.markerb
91 lines (73 loc) · 2.79 KB
/
events.html.markerb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
---
title: Reading the LiteFS event stream
layout: docs
sitemap: false
nav: litefs
toc: true
---
LiteFS provides mechanisms for reading the [replication position](position) and
[current primary status](primary) through the FUSE file system mount. However,
this involves polling the file system which has overhead and some delay.
If you need real-time updates of replication or primary changes, you can also
use the LiteFS event stream. The event stream is an HTTP endpoint that sends
a [newline-delimited JSON stream](http://ndjson.org/) of events to the client.
## Usage
The event stream is accessible at `GET /events` on your LiteFS node:
```
$ curl localhost:20202/events
{"type":"init","data":{"isPrimary":true}}
{"type":"tx","db":"db","data":{"txID":"0000000000000027","postApplyChecksum":"83b05248774ce767","pageSize":4096,"commit":2,"timestamp":"2023-09-06T19:12:34.985Z"}}
{"type":"tx","db":"db","data":{"txID":"0000000000000028","postApplyChecksum":"8467267f644a1b66","pageSize":4096,"commit":2,"timestamp":"2023-09-06T19:12:39.586Z"}}
```
## Event Types
### `init`
The `init` event is always the first event published to an event stream. It includes
basic information about whether the local node is the primary and, if not, the
hostname of the current primary. More fields may be added to this event in the future.
```
{
"type": "init",
"data": {
"isPrimary": false,
"hostname": "myPrimaryHost:20202"
}
}
```
### `tx`
This event is published every time a new transaction is written to LiteFS. This
event will fire whether the transaction is performed locally as the primary or
if the transaction was received by a replica.
The `txID` field is a hex-formatted transaction ID. The `postApplyChecksum` is
a checksum of the entire database after the transaction has been applied. These
two fields form the [replication position](position).
The `commit` field is the size of the database in pages and can be multiplied by
the `pageSize` field to give you the total size of the database file in bytes.
The `timestamp` field is the timestamp of when the transaction was originally
written on the primary node. This is not always reliable as clocks can skew
between different servers.
```
{
"type": "tx",
"db": "db",
"data": {
"txID": "0000000000000027",
"postApplyChecksum": "83b05248774ce767",
"pageSize": 4096,
"commit": 2,
"timestamp": "2023-09-06T19:12:34.985Z"
}
}
```
### `primaryChange`
This event shows information about the current primary status. It is delivered
whenever the status changes such as when the node becomes primary, loses its
primary status, connects to a primary, or loses its connection to the primary.
```
{
"type": "init",
"data": {
"isPrimary": false,
"hostname": "myPrimaryHost:20202"
}
}
```