From 74007ef5eee52d565048a68f870200c84a3e5721 Mon Sep 17 00:00:00 2001 From: richvdh Date: Wed, 7 Jul 2021 09:44:14 +0000 Subject: deploy: 7c823789921ac34f1fee670be7ef7f6c8266832b --- latest/usage/administration/admin_api/index.html | 273 +++++++++++++++++++++ latest/usage/administration/index.html | 262 ++++++++++++++++++++ latest/usage/administration/request_log.html | 290 +++++++++++++++++++++++ 3 files changed, 825 insertions(+) create mode 100644 latest/usage/administration/admin_api/index.html create mode 100644 latest/usage/administration/index.html create mode 100644 latest/usage/administration/request_log.html (limited to 'latest/usage/administration') diff --git a/latest/usage/administration/admin_api/index.html b/latest/usage/administration/admin_api/index.html new file mode 100644 index 0000000000..01d168d32b --- /dev/null +++ b/latest/usage/administration/admin_api/index.html @@ -0,0 +1,273 @@ + + + + + + Admin API - Synapse + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + + + + +
+
+ +
+ +
+ +

The Admin API

+

Authenticate as a server admin

+

Many of the API calls in the admin api will require an access_token for a +server admin. (Note that a server admin is distinct from a room admin.)

+

A user can be marked as a server admin by updating the database directly, e.g.:

+
UPDATE users SET admin = 1 WHERE name = '@foo:bar.com';
+
+

A new server admin user can also be created using the register_new_matrix_user +command. This is a script that is located in the scripts/ directory, or possibly +already on your $PATH depending on how Synapse was installed.

+

Finding your user's access_token is client-dependent, but will usually be shown in the client's settings.

+

Making an Admin API request

+

Once you have your access_token, you will need to authenticate each request to an Admin API endpoint by +providing the token as either a query parameter or a request header. To add it as a request header in cURL:

+
curl --header "Authorization: Bearer <access_token>" <the_rest_of_your_API_request>
+
+

For more details on access tokens in Matrix, please refer to the complete +matrix spec documentation.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/latest/usage/administration/index.html b/latest/usage/administration/index.html new file mode 100644 index 0000000000..56e81b30a8 --- /dev/null +++ b/latest/usage/administration/index.html @@ -0,0 +1,262 @@ + + + + + + Administration - Synapse + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + + + + +
+
+ +
+ +
+ +

Administration

+

This section contains information on managing your Synapse homeserver. This includes:

+
    +
  • Managing users, rooms and media via the Admin API.
    • +
  • Setting up metrics and monitoring to give you insight into your homeserver's health.
    • +
  • Configuring structured logging.
    • +
+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/latest/usage/administration/request_log.html b/latest/usage/administration/request_log.html new file mode 100644 index 0000000000..1235d1cd8f --- /dev/null +++ b/latest/usage/administration/request_log.html @@ -0,0 +1,290 @@ + + + + + + Request log format - Synapse + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + + + + +
+
+ +
+ +
+ +

Request log format

+

HTTP request logs are written by synapse (see site.py for details).

+

See the following for how to decode the dense data available from the default logging configuration.

+
2020-10-01 12:00:00,000 - synapse.access.http.8008 - 311 - INFO - PUT-1000- 192.168.0.1 - 8008 - {another-matrix-server.com} Processed request: 0.100sec/-0.000sec (0.000sec, 0.000sec) (0.001sec/0.090sec/3) 11B !200 "PUT /_matrix/federation/v1/send/1600000000000 HTTP/1.1" "Synapse/1.20.1" [0 dbevts]
+-AAAAAAAAAAAAAAAAAAAAA-   -BBBBBBBBBBBBBBBBBBBBBB-   -C-   -DD-   -EEEEEE-  -FFFFFFFFF-   -GG-    -HHHHHHHHHHHHHHHHHHHHHHH-                     -IIIIII- -JJJJJJJ-  -KKKKKK-, -LLLLLL-  -MMMMMMM- -NNNNNN- O  -P- -QQ-  -RRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRR-   -SSSSSSSSSSSS-   -TTTTTT-
+
+ + + + + + + + + + + + + + + + + + + + + +
PartExplanation
AAAATimestamp request was logged (not recieved)
BBBBLogger name (synapse.access.(http\|https).<tag>, where 'tag' is defined in the listeners config section, normally the port)
CCCCLine number in code
DDDDLog Level
EEEERequest Identifier (This identifier is shared by related log lines)
FFFFSource IP (Or X-Forwarded-For if enabled)
GGGGServer Port
HHHHFederated Server or Local User making request (blank if unauthenticated or not supplied)
IIIITotal Time to process the request
JJJJTime to send response over network once generated (this may be negative if the socket is closed before the response is generated)
KKKKUserland CPU time
LLLLSystem CPU time
MMMMTotal time waiting for a free DB connection from the pool across all parallel DB work from this request
NNNNTotal time waiting for response to DB queries across all parallel DB work from this request
OOOOCount of DB transactions performed
PPPPResponse body size
QQQQResponse status code (prefixed with ! if the socket was closed before the response was generated)
RRRRRequest
SSSSUser-agent
TTTTEvents fetched from DB to service this request (note that this does not include events fetched from the cache)
+

MMMM / NNNN can be greater than IIII if there are multiple slow database queries +running in parallel.

+

Some actions can result in multiple identical http requests, which will return +the same data, but only the first request will report time/transactions in +KKKK/LLLL/MMMM/NNNN/OOOO - the others will be awaiting the first query to return a +response and will simultaneously return with the first request, but with very +small processing times.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file -- cgit 1.5.1