From 33ed5a8eec40c67f1ff0dc244a0f355cd2229454 Mon Sep 17 00:00:00 2001
From: Ziinc <Ziinc@users.noreply.github.com>
Date: Wed, 7 Aug 2024 20:40:09 +0800
Subject: [PATCH] docs: allowlist of api logs (#28446)

* docs: allowlist of api logs

* docs: remove x-custom-metadata

* docs: add note about header passthrough

* docs: add in user agent enriching docs
---
 apps/docs/content/guides/platform/logs.mdx | 56 ++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/apps/docs/content/guides/platform/logs.mdx b/apps/docs/content/guides/platform/logs.mdx
index 5b9184ffc6b..a81f6029ecc 100644
--- a/apps/docs/content/guides/platform/logs.mdx
+++ b/apps/docs/content/guides/platform/logs.mdx
@@ -87,6 +87,62 @@ Edge Function log messages have a max length of 10,000 characters. If you try to
 
 ---
 
+## Working with API logs
+
+[API logs](https://supabase.com/dashboard/project/_/logs/edge-logs) run through the Cloudflare edge servers and will have attached Cloudflare metadata under the `metadata.request.cf.*` fields.
+
+### Allowed headers
+
+A strict list of request and response headers are permitted in the API logs. Request and response headers will still be received by the server(s) and client(s), but will not be attached to the API logs generated.
+
+Request headers:
+
+- `accept`
+- `cf-connecting-ip`
+- `cf-ipcountry`
+- `host`
+- `user-agent`
+- `x-forwarded-proto`
+- `referer`
+- `content-length`
+- `x-real-ip`
+- `x-client-info`
+- `x-forwarded-user-agent`
+- `range`
+- `prefer`
+
+Response headers:
+
+- `cf-cache-status`
+- `cf-ray`
+- `content-location`
+- `content-range`
+- `content-type`
+- `content-length`
+- `date`
+- `transfer-encoding`
+- `x-kong-proxy-latency`
+- `x-kong-upstream-latency`
+- `sb-gateway-mode`
+- `sb-gateway-version`
+
+### Additional request metadata
+
+To attach additional metadata to a request, it is recommended to use the `User-Agent` header for purposes such as device or version identification.
+
+For example:
+
+```
+node MyApp/1.2.3 (device-id:abc123)
+Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 MyApp/1.2.3 (Foo v1.3.2; Bar v2.2.2)
+```
+
+<Admonition type="note">
+
+Do not log Personal Identifiable Information (PII) within the `User-Agent` header, to avoid infringing data protection privacy laws. Overly fine-grained and detailed user agents may allow fingerprinting and identification of the end user through PII.
+
+</Admonition>
+
 ## Logging Postgres queries
 
 To enable query logs for other categories of statements: