feat(docs): update OpenTelemetry self-hosted guide with new metrics and dashboard features

Enhanced the self-hosted OpenTelemetry documentation by adding a sample Grafana dashboard for visualizing metrics from Gate. Updated configuration details for the OpenTelemetry Collector, including new metrics endpoints and improved instructions for setting up Prometheus scraping. Removed outdated Kubernetes configuration examples and added new YAML files for the OpenTelemetry Collector setup. Updated the documentation to reflect changes in metrics collection and visualization capabilities.

Author: robinbraemer

.web/docs/.vitepress/config.ts

@@ -48,7 +48,7 @@ export default defineConfig({
   ],
 
   vue: {
-    reactivityTransform: true,
+    // reactivityTransform: true, // This option is deprecated
   },
 
   themeConfig: {
@@ -190,6 +190,10 @@ export default defineConfig({
                   text: 'Self-hosted',
                   link: '/guide/otel/self-hosted/',
                 },
+                {
+                  text: 'Dashboards',
+                  link: '/guide/otel/self-hosted/dashboard',
+                },
                 {
                   text: 'FAQ',
                   link: '/guide/otel/faq/',

.web/docs/guide/otel/index.md

@@ -1,27 +1,28 @@
 # OpenTelemetry
 
-Gate uses OpenTelemetry for observability, leveraging the [otel-config-go](https://github.com/honeycombio/otel-config-go) library for configuration. This provides a simple way to configure tracing and metrics collection through environment variables.
+OpenTelemetry is an observability framework and toolkit designed to facilitate the generation, export, and collection of telemetry data such as traces, metrics, and logs. It is an open-source and vendor-agnostic project, meaning it can be used with a broad variety of observability backends, including open-source tools like Jaeger and Prometheus, as well as commercial offerings. A major goal of OpenTelemetry is to enable easy instrumentation of applications and systems, regardless of the programming language, infrastructure, and runtime environments used. OpenTelemetry itself is not an observability backend; the storage and visualization of telemetry data are intentionally left to other tools. ([Source](https://opentelemetry.io/docs/what-is-opentelemetry/))
+
+::: info
+Gate utilizes OpenTelemetry for its observability capabilities. For configuration, Gate leverages the [otel-config-go](https://github.com/honeycombio/otel-config-go) library, which offers a straightforward method to set up tracing and metrics collection via [environment variables](#configuration).
+:::
 
 # Start Generation Here
 
 ![OpenTelemetry Architecture](https://mermaid.ink/svg/pako:eNp9kl1vgjAUhv9Kc65cgoYvGXCxRNF4o9FNsouJFx1UbEZbUiCZGv_7CrhJ1KxX7XPe856e9pwgFgkBH1KJ8z2av0UcqVVUny2IYJTnGY1xSQWPoI3Wa7SZ4ZJsW0B4EvG7zJBkhJFSHlAgsozEtxbjzTIn_E4l5L-uC8Gp0lCeojGOv5So6JoGmwhmEu8wx2hBGZWot1DuNC6eIthedZOOLiQsF6gXShyTjuxx_XdaVDijx7sXmXYcl-v1I5sR6vfRMpyv0LXrfv8FjdvwuA5fbtvwoMPb2zV40uKgxisp2Ou8wdMWT27UU9CAEckwTdQ_n2pRBOVelY_AV9uMpvuybuSshLgqxfrAY_BLWRENpKjSPfg7nBXqVOWJ-vQJxeox2B_NMf8Qgv2mpLIudElXzRMZiIqX4FtOowX_BN_ge87AdoaGZViOZ1qO_azBAXzbGHiOaerPumXZpqsbw7MGx8ZdH7i6Z1i27jiGbruupwFJ6lFYtBPcDPL5B1Gd2L4)
 
 ## Configuration
 
-Gate's OpenTelemetry implementation can be configured using the following environment variables:
-
-| Environment Variable        | Required | Default                | Description                           |
-| --------------------------- | -------- | ---------------------- | ------------------------------------- |
-| OTEL_SERVICE_NAME           | No       | `gate`                 | Name of your service                  |
-| OTEL_SERVICE_VERSION        | No       | -                      | Version of your service               |
-| OTEL_EXPORTER_OTLP_ENDPOINT | No       | `localhost:4317`       | Endpoint for OTLP export              |
-| OTEL_LOG_LEVEL              | No       | `info`                 | Logging level                         |
-| OTEL_PROPAGATORS            | No       | `tracecontext,baggage` | Configured propagators                |
-| OTEL_METRICS_ENABLED        | No       | `true`                 | Enable metrics collection             |
-| OTEL_TRACES_ENABLED         | No       | `true`                 | Enable trace collection               |
-| OTEL_METRICS_SERVER_ENABLED | No       | `false`                | Enable Prometheus metrics server      |
-| OTEL_METRICS_SERVER_PATH    | No       | `/metrics`             | Path for Prometheus metrics endpoint  |
-| OTEL_METRICS_SERVER_ADDR    | No       | `:9464`                | Address for Prometheus metrics server |
+Gate's OpenTelemetry implementation can be configured using the following [environment variables](https://github.com/honeycombio/otel-config-go/blob/127951890a85db4effad9fbc961d0f09ddd8a818/otelconfig/otelconfig.go#L304):
+
+| Environment Variable        | Required | Default                | Description               |
+| --------------------------- | -------- | ---------------------- | ------------------------- |
+| OTEL_SERVICE_NAME           | No       | `gate`                 | Name of your service      |
+| OTEL_SERVICE_VERSION        | No       | -                      | Version of your service   |
+| OTEL_EXPORTER_OTLP_ENDPOINT | No       | `localhost:4317`       | Endpoint for OTLP export  |
+| OTEL_LOG_LEVEL              | No       | `info`                 | Logging level             |
+| OTEL_PROPAGATORS            | No       | `tracecontext,baggage` | Configured propagators    |
+| OTEL_METRICS_ENABLED        | No       | `true`                 | Enable metrics collection |
+| OTEL_TRACES_ENABLED         | No       | `true`                 | Enable trace collection   |
 
 Additional environment variables for exporters:
 
@@ -30,12 +31,12 @@ Additional environment variables for exporters:
 | OTEL_EXPORTER_OTLP_HEADERS          | No       | `{}`             | Global headers for OTLP exporter     |
 | OTEL_EXPORTER_OTLP_TRACES_HEADERS   | No       | `{}`             | Headers specific to trace exporter   |
 | OTEL_EXPORTER_OTLP_METRICS_HEADERS  | No       | `{}`             | Headers specific to metrics exporter |
-| OTEL_EXPORTER_OTLP_PROTOCOL         | No       | `grpc`           | Protocol for OTLP export (grpc/http) |
 | OTEL_EXPORTER_OTLP_TRACES_ENDPOINT  | No       | `localhost:4317` | Endpoint for trace export            |
 | OTEL_EXPORTER_OTLP_TRACES_INSECURE  | No       | `false`          | Allow insecure trace connections     |
 | OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | No       | `localhost:4317` | Endpoint for metrics export          |
 | OTEL_EXPORTER_OTLP_METRICS_INSECURE | No       | `false`          | Allow insecure metrics connections   |
 | OTEL_EXPORTER_OTLP_METRICS_PERIOD   | No       | `30s`            | Metrics reporting interval           |
+| OTEL_EXPORTER_OTLP_PROTOCOL         | No       | `grpc`           | Protocol for OTLP export             |
 | OTEL_RESOURCE_ATTRIBUTES            | No       | -                | Additional resource attributes       |
 
 ## Example Configuration
@@ -53,15 +54,19 @@ OTEL_RESOURCE_ATTRIBUTES="deployment.environment=production"
 
 You can use various solutions to collect and visualize OpenTelemetry data. Here are some popular options:
 
-### Cloud Solutions
+### Detailed Setup Guides
 
-::: info <VPBadge>Our recommendations</VPBadge>
+::: info <VPBadge>We provide detailed guides for these three solutions</VPBadge>
 
 - [Grafana Cloud](/guide/otel/grafana-cloud/) - Fully managed observability platform with support for metrics, logs, and traces
 - [Honeycomb](/guide/otel/honeycomb/) - Observability platform designed for debugging complex systems
+- [Self-hosted](/guide/otel/self-hosted/) - Run your own OpenTelemetry collector and visualize data with Grafana
 
 :::
 
+### Other Cloud Solutions
+
+- [Signoz](https://signoz.io/) - Open source observability platform with support for metrics, logs, and traces
 - [New Relic](https://newrelic.com/) - Full-stack observability platform with APM capabilities
 - [Datadog](https://www.datadog.com/) - Cloud monitoring and analytics platform
 - [Azure Monitor](https://azure.microsoft.com/services/monitor/) - Microsoft's cloud-native monitoring solution
@@ -129,9 +134,6 @@ You can use various solutions to collect and visualize OpenTelemetry data. Here
    # Secure endpoint configuration
    OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-collector.example.com:4317"
    OTEL_EXPORTER_OTLP_HEADERS="api-key=secret123,tenant=team-a"
-
-   # Ensure TLS is enabled
-   OTEL_EXPORTER_OTLP_INSECURE=false
    ```
 
 ## Further Reading

.web/docs/guide/otel/self-hosted/dashboard.md

@@ -0,0 +1,3 @@
+# Sample Gate Dashboard
+
+<!--@include: ./grafana-dash.md -->

.web/docs/guide/otel/self-hosted/grafana-dash.md

@@ -0,0 +1,37 @@
+
+We provide a sample Grafana dashboard to help you get started with visualizing Gate's metrics.
+
+::: info <VPBadge>You are expected to make your own dashboard, this is just a starting point.</VPBadge>
+
+![Grafana Dashboard](/images/grafana-gate-dash.png)
+
+:::
+
+**Dashboard Features:**
+
+- Total Player Count (`proxy_player_count`)
+- Gate Instance Status (`up`)
+- Go Goroutines (`go_goroutines`)
+- Go Memory Usage (`go_memstats_alloc_bytes`)
+
+**Get the Dashboard JSON:**
+
+- **Download Raw JSON:** [Download Dashboard JSON](https://raw.githubusercontent.com/minekube/gate/master/.web/docs/guide/otel/self-hosted/grafana-dashboards/gate-overview-dashboard.json)
+- **View on GitHub:** [gate-overview-dashboard.json](https://github.com/minekube/gate/blob/master/.web/docs/guide/otel/self-hosted/grafana-dashboards/gate-overview-dashboard.json)
+
+If you have cloned the repository, you can also find the dashboard at `.web/docs/guide/otel/self-hosted/grafana-dashboards/gate-overview-dashboard.json` within your local copy.
+
+**Importing the Dashboard:**
+
+1.  Navigate to your Grafana instance (usually http://localhost:3000).
+2.  Log in (default: admin/admin, then change the password).
+3.  On the left-hand menu, go to **Dashboards**.
+4.  On the Dashboards page, click the **"New"** button in the top right and select **"Import"**.
+    ![Grafana Menu Dashboards](/images/grafana-new-dash.png)
+5.  Click the **"Upload JSON file"** button and select the `gate-overview-dashboard.json` file you downloaded, or paste the JSON content directly into the text area.
+6.  On the next screen, you can change the dashboard name if desired.
+7.  **Important:** Select your Prometheus data source from the dropdown (usually named "Prometheus").
+    ![Grafana Import Dashboard](/images/grafana-import-dash.png)
+8.  Click **"Import"**.
+
+You should now see the "Gate Overview" dashboard with panels visualizing metrics from your Gate instance(s).

.web/docs/guide/otel/self-hosted/grafana-dashboards/gate-overview-dashboard.json

@@ -99,7 +99,7 @@
             "type": "prometheus",
             "uid": "${DS_PROMETHEUS}"
           },
-          "expr": "sum(proxy_player_count{job=\"gate\"}) by (job)",
+          "expr": "sum(otel_gate_player_count_ratio{job=\"otel-collector\", service_name=~\"$service_name_filter\"})",
           "legendFormat": "Total Players",
           "refId": "A"
         }
@@ -117,23 +117,7 @@
           "color": {
             "mode": "thresholds"
           },
-          "mappings": [
-            {
-              "options": {
-                "0": {
-                  "color": "red",
-                  "index": 0,
-                  "text": "Down"
-                },
-                "1": {
-                  "color": "green",
-                  "index": 1,
-                  "text": "Up"
-                }
-              },
-              "type": "value"
-            }
-          ],
+          "mappings": [],
           "thresholds": {
             "mode": "absolute",
             "steps": [
@@ -155,15 +139,13 @@
       },
       "id": 4,
       "options": {
-        "colorMode": "value",
-        "graphMode": "area",
-        "justifyMode": "auto",
-        "orientation": "auto",
         "reduceOptions": {
           "calcs": ["lastNotNull"],
-          "fields": "/^up$/",
+          "fields": "",
           "values": false
         },
+        "showThresholdLabels": false,
+        "showThresholdMarkers": true,
         "textMode": "auto"
       },
       "pluginVersion": "10.2.2",
@@ -173,12 +155,12 @@
             "type": "prometheus",
             "uid": "${DS_PROMETHEUS}"
           },
-          "expr": "up{job=\"gate\"}",
-          "legendFormat": "{{instance}}",
+          "expr": "sum(otel_gate_registered_servers_ratio{job=\"otel-collector\", service_name=~\"$service_name_filter\"})",
+          "legendFormat": "Registered Servers",
           "refId": "A"
         }
       ],
-      "title": "Gate Instance Status (up)",
+      "title": "Registered Servers",
       "type": "stat"
     },
     {
@@ -264,8 +246,8 @@
             "type": "prometheus",
             "uid": "${DS_PROMETHEUS}"
           },
-          "expr": "sum(go_goroutines{job=\"gate\"}) by (instance)",
-          "legendFormat": "{{instance}}",
+          "expr": "sum(otel_process_runtime_go_goroutines{job=\"otel-collector\", service_name=~\"$service_name_filter\"}) by (service_name, instance, exported_job)",
+          "legendFormat": "{{service_name}} {{exported_job}} {{instance}}",
           "refId": "A"
         }
       ],
@@ -355,8 +337,8 @@
             "type": "prometheus",
             "uid": "${DS_PROMETHEUS}"
           },
-          "expr": "sum(go_memstats_alloc_bytes{job=\"gate\"}) by (instance)",
-          "legendFormat": "{{instance}}",
+          "expr": "sum(otel_process_runtime_go_mem_heap_alloc_bytes{job=\"otel-collector\", service_name=~\"$service_name_filter\"}) by (service_name, instance, exported_job)",
+          "legendFormat": "{{service_name}} {{exported_job}} {{instance}}",
           "refId": "A"
         }
       ],
@@ -394,16 +376,16 @@
           "type": "prometheus",
           "uid": "${DS_PROMETHEUS}"
         },
-        "definition": "label_values(up{job=\"gate\"}, job)",
+        "definition": "label_values(otel_process_runtime_go_goroutines{job=\"otel-collector\"}, service_name)",
         "hide": 0,
         "includeAll": true,
-        "label": "Job",
+        "label": "Service Name",
         "multi": true,
-        "name": "job",
+        "name": "service_name_filter",
         "options": [],
         "query": {
-          "query": "label_values(up{job=\"gate\"}, job)",
-          "refId": "StandardVariableQuery"
+          "query": "label_values(otel_process_runtime_go_goroutines{job=\"otel-collector\"}, service_name)",
+          "refId": "StandardVariableQuery_ServiceName"
         },
         "refresh": 1,
         "regex": "",