Merge pull request #1832 from appwrite/update-logging-doc

ebenezerdon · web-flow · commit 813c3b531ed1 · 2025-03-13T17:30:35.000Z
Update logging doc to match Appwrite migration to DSN syntax
diff --git a/src/routes/docs/advanced/self-hosting/environment-variables/+page.markdoc b/src/routes/docs/advanced/self-hosting/environment-variables/+page.markdoc
@@ -38,8 +38,8 @@ docker compose exec appwrite vars
 | `_APP_SYSTEM_RESPONSE_FORMAT` | Use this environment variable to set the default Appwrite HTTP response format to support an older version of Appwrite. This option is useful to overcome breaking changes between versions. You can also use the `X-Appwrite-Response-Format` HTTP request header to overwrite the response for a specific request. This variable accepts any valid Appwrite version. To use the current version format, leave the value of the variable empty. |
 | `_APP_SYSTEM_SECURITY_EMAIL_ADDRESS` | This is the email address used to issue SSL certificates for custom domains or the user agent in your webhooks payload. |
 | `_APP_USAGE_STATS` | This variable allows you to disable the collection and displaying of usage stats. This value is set to 'enabled' by default, to disable the usage stats set the value to 'disabled'. When disabled, it's recommended to turn off the Worker Usage container to reduce resource usage. |
-| `_APP_LOGGING_PROVIDER` |  **(version >= 0.12.0)** This variable allows you to enable logging errors to 3rd party providers. This value is empty by default, set the value to one of 'sentry', 'raygun', 'appSignal', 'logOwl' to enable the logger. |
-| `_APP_LOGGING_CONFIG`  | **(version >= 0.12.0)** This variable configures authentication to 3rd party error logging providers. If using Sentry, this should be 'SENTRY_PROJECT_ID;SENTRY_PUBLIC_KEY@SENTRY_HOST'. If using Raygun, this should be Raygun API key. If using AppSignal, this should be AppSignal API key. If using LogOwl, this should be LogOwl Service Ticket. |
+| `_APP_LOGGING_PROVIDER` |  Deprecated since 1.6.0, use `_APP_LOGGING_CONFIG` with DSN value instead. This variable allows you to enable logging errors to 3rd party providers. This value is empty by default, set the value to one of \'sentry\', \'raygun\', \'appSignal\', \'logOwl\' to enable the logger. |
+| `_APP_LOGGING_CONFIG`  | This variable allows you to enable logging errors to third party providers. This value is empty by default, set a DSN value to one of the following `sentry://PROJECT_ID:SENTRY_API_KEY@SENTRY_HOST/`, , `logowl://SERVICE_TICKET@SERIVCE_HOST/` `raygun://RAYGUN_API_KEY/`, `appSignal://API_KEY/` to enable the logger. For versions prior `1.5.6` you can use the old syntax. Old syntax: If using Sentry, this should be \'SENTRY_API_KEY;SENTRY_APP_ID\'. If using Raygun, this should be Raygun API key. If using AppSignal, this should be AppSignal API key. If using LogOwl, this should be LogOwl Service Ticket. |
 | `_APP_USAGE_AGGREGATION_INTERVAL` | **(version >= 1.1.0)** Interval value containing the number of seconds that the Appwrite usage process should wait before aggregating stats and syncing it to Database from TimeSeries data. The default value is 30 seconds. Reintroduced in 1.1.0. |
 | `_APP_USAGE_TIMESERIES_INTERVAL` | **(version >= 1.0.0)** Deprecated since 1.1.0 use _APP_USAGE_AGGREGATION_INTERVAL instead. |
 | `_APP_USAGE_DATABASE_INTERVAL` |  **(version >= 1.0.0)** Deprecated since 1.1.0 use _APP_USAGE_AGGREGATION_INTERVAL instead. |
diff --git a/src/routes/docs/advanced/self-hosting/production/+page.markdoc b/src/routes/docs/advanced/self-hosting/production/+page.markdoc
@@ -15,7 +15,7 @@ You **must** set `_APP_OPENSSL_KEY_V1` immediately after installation of a produ
 Make sure to keep this key in a safe place and never make it publicly accessible.
 
 {% info title="Best practice" %}
-You should always prefer **HTTPS** over HTTP in production environments. This keeps your APIs secure and prevents any redirects from interfering with your requests. 
+You should always prefer **HTTPS** over HTTP in production environments. This keeps your APIs secure and prevents any redirects from interfering with your requests.
 You can force the use of HTTPS with the [_APP_OPTIONS_FORCE_HTTPS](/docs/advanced/self-hosting/environment-variables) environment variable.
 {% /info %}
 
@@ -30,7 +30,7 @@ Appwrite provides three different methods to limit access to your Appwrite Conso
 By default, only the first user can sign up on the Appwrite instance's dashboard. All other users must be added to the dashboard through invitation.
 
 {% arrow_link href="/docs/advanced/self-hosting/environment-variables" %}
-Learn more about environment variables 
+Learn more about environment variables
 {% /arrow_link %}
 
 # Scaling {% #scaling %}
@@ -50,7 +50,7 @@ If you disabled rate limits during development, make sure you re-enable them whe
 Rate limits are an important mechanism to protect your app. Without rate limits, malicious actors can spam your APIs to perform [denial-of-service type attacks](https://en.wikipedia.org/wiki/Denial-of-service_attack) or brute-force user passwords.
 
 {% arrow_link href="/docs/advanced/self-hosting/environment-variables" %}
-Learn more about environment variables 
+Learn more about environment variables
 {% /arrow_link %}
 
 # Emails {% #emails %}
@@ -75,14 +75,17 @@ Do not back up any stateful container using a docker volume backup, such as data
 
 By default, your Appwrite installation comes with error reporting turned off. You can [enable dev mode](/docs/advanced/self-hosting/debug#development-mode) to get access to more verbose error logs and stack traces.
 
-In production, it is highly recommended to turn error reporting off. To do so, make sure the Appwrite container environment variable `_APP_ENV` value from is set to `production` and not `development`.
+In production, it is highly recommended to turn error reporting off. To do so, make sure the Appwrite container environment variable `_APP_ENV` is set to `production` and not `development`.
 
-To monitor errors in production, add a third party monitoring service by setting the `_APP_LOGGING_PROVIDER` and `_APP_LOGGING_CONFIG`.
+To monitor errors in production, configure the `_APP_LOGGING_CONFIG` environment variable with your provider's DSN. The supported DSN formats are:
 
-In production, it is highly recommended to turn error reporting off. To do so, make sure the Appwrite container environment variable `_APP_ENV` is set to `production` and not `development`.
+- Sentry: `sentry://PUBLIC_KEY@HOST:PORT/PROJECT_ID`
+- LogOwl: `logowl://SERVICE_TICKET@SERVICE_HOST/`
+- Raygun: `raygun://RAYGUN_API_KEY/`
+- AppSignal: `appsignal://API_KEY/`
 
 {% arrow_link href="/docs/advanced/self-hosting/environment-variables" %}
-Learn more about environment variables 
+Learn more about environment variables
 {% /arrow_link %}
 
 # Security {% #security %}
diff --git a/src/routes/integrations/logging-appsignal/+page.markdoc b/src/routes/integrations/logging-appsignal/+page.markdoc
@@ -8,13 +8,13 @@ isPartner: true
 isNew: true
 cover: /images/integrations/logging-appsignal/cover.png
 category: logging
-product: 
+product:
     avatar: '/images/integrations/avatars/appsignal.png'
     vendor: AppSignal
     description: 'AppSignal is a comprehensive monitoring and error-tracking tool designed for developers to gain insights into the performance of their applications.'
-platform: 
+platform:
     - 'Self-hosted'
-images: 
+images:
     - /images/integrations/logging-appsignal/cover.png
     - /images/integrations/logging-appsignal/api-key.png
     - /images/integrations/logging-appsignal/errors-list.png
@@ -39,14 +39,23 @@ First, [sign up on AppSignal](https://appsignal.com/users/sign_up) and create yo
 
 ## Step 2: Add AppSignal provider to your Appwrite instance
 
-For this step, you must [self-host Appwrite](https://appwrite.io/docs/advanced/self-hosting) if you haven’t already.
+For this step, you must [self-host Appwrite](https://appwrite.io/docs/advanced/self-hosting) if you haven't already.
 
-Visit the `.env` file created for your Appwrite instance and update the following environment variables:
+The Appwrite logging configuration uses a DSN format that follows the pattern `appsignal://API_KEY/`. Use your AppSignal Push API key as the API_KEY in the DSN.
 
+Visit the `.env` file created for your Appwrite instance and update the following environment variable:
+
+```bash
+_APP_LOGGING_CONFIG=appsignal://API_KEY/
+```
+
+{% info title="Using Appwrite < 1.5.6?" %}
+For versions prior to 1.5.6, use the old syntax format:
 ```bash
 _APP_LOGGING_PROVIDER=appSignal
 _APP_LOGGING_CONFIG=APPSIGNAL_API_KEY
 ```
+{% /info %}
 
 After that, run the following Docker Compose commands in your terminal to restart your Appwrite containers and verify if the changes have been successfully applied:
 
diff --git a/src/routes/integrations/logging-raygun/+page.markdoc b/src/routes/integrations/logging-raygun/+page.markdoc
@@ -33,20 +33,29 @@ To implement the Raygun provider for logging, there are several steps you must c
 
 ## Step 1: Sign up for Raygun
 
-First, [sign up on Raygun](https://app.raygun.com/signup?product=cr) (pick **Crash Reporting** as the product you’re most interested in) and create your first application. Head to **Application settings** from the left-side navbar and copy your **API Key**.
+First, [sign up on Raygun](https://app.raygun.com/signup?product=cr) (pick **Crash Reporting** as the product you're most interested in) and create your first application. Head to **Application settings** from the left-side navbar and copy your **API Key**.
 
 ![API key](/images/integrations/logging-raygun/api-key.png)
 
 ## Step 2: Add Raygun provider to your Appwrite instance
 
-For this step, you must [self-host Appwrite](https://appwrite.io/docs/advanced/self-hosting) if you haven’t already.
+For this step, you must [self-host Appwrite](https://appwrite.io/docs/advanced/self-hosting) if you haven't already.
 
-Visit the `.env` file created for your Appwrite instance and update the following environment variables:
+The Appwrite logging configuration uses a DSN format that follows the pattern `raygun://API_KEY/`. Use your Raygun API key in the DSN.
 
+Visit the `.env` file created for your Appwrite instance and update the following environment variable:
+
+```bash
+_APP_LOGGING_CONFIG=raygun://API_KEY/
+```
+
+{% info title="Using Appwrite < 1.5.6?" %}
+For versions prior to 1.5.6, use the old syntax format:
 ```bash
 _APP_LOGGING_PROVIDER=raygun
 _APP_LOGGING_CONFIG=RAYGUN_API_KEY
 ```
+{% /info %}
 
 After that, run the following Docker Compose commands in your terminal to restart your Appwrite containers and verify if the changes have been successfully applied:
 
diff --git a/src/routes/integrations/logging-sentry/+page.markdoc b/src/routes/integrations/logging-sentry/+page.markdoc
@@ -8,13 +8,13 @@ isPartner: true
 isNew: true
 cover: /images/integrations/logging-sentry/cover.png
 category: logging
-product: 
+product:
     avatar: '/images/integrations/avatars/sentry.png'
     vendor: Sentry
     description: 'Sentry is an open-source error-tracking and performance-monitoring tool designed to help developers identify, diagnose, and fix issues in real-time.'
-platform: 
+platform:
     - 'Self-hosted'
-images: 
+images:
     - /images/integrations/logging-sentry/cover.png
     - /images/integrations/logging-sentry/project.png
     - /images/integrations/logging-sentry/issues.png
@@ -41,16 +41,23 @@ Head to **Settings** > **Projects** > Select your Sentry project > **Client Keys
 
 ## Step 2: Add Sentry provider to your Appwrite instance
 
-For this step, you must [self-host Appwrite](https://appwrite.io/docs/advanced/self-hosting) if you haven’t already.
+For this step, you must [self-host Appwrite](https://appwrite.io/docs/advanced/self-hosting) if you haven't already.
 
-To add the Sentry provider, you need to slightly reconfigure your DSN. Your Sentry DSN is made up of 3 parts: **project ID**, **public key**, and **host**. The Appwrite logging configuration expects a string in the format `SENTRY_PROJECT_ID;SENTRY_PUBLIC_KEY@SENTRY_HOST`. For example, if your Sentry DSN is `https://public@sentry.example.com/1`, then the Appwrite logging configuration will be `1;public@sentry.example.com`.
+The Appwrite logging configuration uses a DSN format that follows the pattern `sentry://PROJECT_ID:SENTRY_API_KEY@SENTRY_HOST/`. For example, if your Sentry DSN is `https://abcdef@sentry.example.com/1`, then the Appwrite logging configuration will be `sentry://1:abcdef@sentry.example.com/`.
 
-Visit the `.env` file created for your Appwrite instance and update the following environment variables:
+Visit the `.env` file created for your Appwrite instance and update the following environment variable:
 
+```bash
+_APP_LOGGING_CONFIG=sentry://PROJECT_ID:SENTRY_API_KEY@SENTRY_HOST/
+```
+
+{% info title="Using Appwrite < 1.5.6?" %}
+For versions prior to 1.5.6, use the old syntax format:
 ```bash
 _APP_LOGGING_PROVIDER=sentry
 _APP_LOGGING_CONFIG=SENTRY_PROJECT_ID;SENTRY_PUBLIC_KEY@SENTRY_HOST
 ```
+{% /info %}
 
 After that, run the following Docker Compose commands in your terminal to restart your Appwrite containers and verify if the changes have been successfully applied:
 
