Merge pull request #463 from matrix-org/rav/log_docs

Add some documentation on the log fields

README.md

@@ -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`.

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.

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)
 	}