From 73c759e4f723b9f333f42943a4832f6e72c1146b Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Fri, 13 Sep 2024 16:21:48 +0100
Subject: [PATCH] Add some documentation on the log fields

---
 README.md           |  4 +++-
 docs/log_format.md  | 20 ++++++++++++++++++++
 internal/context.go |  4 ++++
 3 files changed, 27 insertions(+), 1 deletion(-)
 create mode 100644 docs/log_format.md

diff --git a/README.md b/README.md
index 101e103f..ccdb6605 100644
--- a/README.md
+++ b/README.md
@@ -99,7 +99,7 @@ docker run --rm -e "SYNCV3_SERVER=https://matrix-client.matrix.org" -e "SYNCV3_S
 
 Download the binary for your architcture (eg. `syncv3_linux_amd64` for 64-bit AMD/Intel) from https://github.com/matrix-org/sliding-sync/releases/latest
 ```
-$ SYNCV3_SECRET=$(cat .secret) SYNCV3_SERVER="https://matrix-client.matrix.org" SYNCV3_DB="user=$(whoami) dbname=syncv3 sslmode=disable password='DATABASE_PASSWORD_HERE'" SYNCV3_BINDADDR=0.0.0.0:8008 ./syncv3_linux_amd64 
+$ SYNCV3_SECRET=$(cat .secret) SYNCV3_SERVER="https://matrix-client.matrix.org" SYNCV3_DB="user=$(whoami) dbname=syncv3 sslmode=disable password='DATABASE_PASSWORD_HERE'" SYNCV3_BINDADDR=0.0.0.0:8008 ./syncv3_linux_amd64
 ```
 
 Optionally also set `SYNCV3_TLS_CERT=path/to/cert.pem` and `SYNCV3_TLS_KEY=path/to/key.pem` to listen on HTTPS instead of HTTP.
@@ -119,6 +119,8 @@ Wait for the first initial v2 sync to be processed (this can take minutes!) and
 
 Note that some clients might require that your home server advertises support for sliding-sync in the `.well-known/matrix/client` endpoint; details are in [the work-in-progress specification document](https://github.com/matrix-org/matrix-spec-proposals/blob/kegan/sync-v3/proposals/3575-sync.md#unstable-prefix).
 
+There are some notes on the log format in [docs/log_format.md](./docs/log_format.md).
+
 ### Prometheus
 
 To enable metrics, pass `SYNCV3_PROM=:2112` to listen on that port and expose a scraping endpoint `GET /metrics`.
diff --git a/docs/log_format.md b/docs/log_format.md
new file mode 100644
index 00000000..991c80f5
--- /dev/null
+++ b/docs/log_format.md
@@ -0,0 +1,20 @@
+# Log line format
+
+Log lines may contain the following fields:
+
+ * `u`: user ID.
+ * `dev`: device ID.
+ * `p`: `pos` parameter from incoming requests.
+ * `q`: `pos` value from outgoing responses.
+ * `t`: transaction ID.
+ * `c`: connection ID.
+ * `b`: buffer summary.
+ * Update counts in outgoing responses, each of which are omitted if zero:
+   * `r`: rooms.
+   * `d`: to-device events.
+   * `ag`: global account data updates.
+   * `dl-c`: changed devices.
+   * `dl-l`: left devices.
+   * `sub`: room subscriptions.
+   * `usub`: room unsubscriptions.
+   * `l`: lists.
diff --git a/internal/context.go b/internal/context.go
index e0cc3458..d3226b42 100644
--- a/internal/context.go
+++ b/internal/context.go
@@ -106,6 +106,10 @@ func DecorateLogger(ctx context.Context, l *zerolog.Event) *zerolog.Event {
 		return l
 	}
 	da := d.(*data)
+
+	// NOTE: These log fields are documented in `docs/log_format.md`: remember to
+	// keep that document up-to-date.
+
 	if da.userID != "" {
 		l = l.Str("u", da.userID)
 	}