minekube · robinbraemer · May 16, 2025 · Nov 27, 2024 · Nov 27, 2024 · Dec 12, 2024
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -0,0 +1,33 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug",
+      "type": "go",
+      "request": "launch",
+      "mode": "debug",
+      "program": "${workspaceFolder}/gate.go",
+      "args": ["-d"],
+      "console": "integratedTerminal"
+    },
+    {
+      "name": "Debug with OTEL (Self-hosted)",
+      "type": "go",
+      "request": "launch",
+      "mode": "debug",
+      "program": "${workspaceFolder}/gate.go",
+      "args": ["
F438
-d"],
+      "console": "integratedTerminal",
+      "env": {
+        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318",
+        "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
+        "OTEL_TRACES_ENABLED": "true",
+        "OTEL_METRICS_ENABLED": "true",
+        "OTEL_SERVICE_NAME": "gate-dev"
+      }
+    }
+  ]
+}
diff --git a/.web/docs/.vitepress/config.ts b/.web/docs/.vitepress/config.ts
@@ -48,9 +48,11 @@ export default defineConfig({
   ],
 
   vue: {
-    reactivityTransform: true,
+    // reactivityTransform: true, // This option is deprecated
   },
 
+  ignoreDeadLinks: 'localhostLinks',
+
   themeConfig: {
     logo: '/minekube-logo.png',
 
@@ -176,6 +178,44 @@ export default defineConfig({
             },
           ],
         },
+        {
+          text: 'OpenTelemetry',
+          items: [
+            {
+              text: 'Overview',
+              link: '/guide/otel/',
+            },
+            {
+              text: 'Grafana',
+              items: [
+                {
+                  text: 'Grafana Cloud',
+                  link: '/guide/otel/grafana-cloud/',
+                },
+                {
+                  text: 'Self-hosted Grafana Stack',
+                  link: '/guide/otel/self-hosted/grafana-stack.md',
+                },
+                {
+                  text: 'Grafana Dashboards',
+                  link: '/guide/otel/self-hosted/dashboard',
+                },
+              ],
+            },
+            {
+              text: 'Honeycomb',
+              link: '/guide/otel/honeycomb/',
+            },
+            {
+              text: 'Self-hosted Jaeger',
+              link: '/guide/otel/self-hosted/jaeger',
+            },
+            {
+              text: 'FAQ',
+              link: '/guide/otel/faq/',
+            },
+          ],
+        },
         {
           text: 'Security',
           items: [

diff --git a/.web/docs/guide/otel/faq.md b/.web/docs/guide/otel/faq.md
@@ -0,0 +1,56 @@
+# OpenTelemetry FAQ
+
+This FAQ addresses common questions about using OpenTelemetry with Gate, particularly in conjunction with Grafana Mimir, Grafana Tempo, and the OpenTelemetry Collector.
+
+## What does a recommended scalable OpenTelemetry setup for Gate look like?
+
+A recommended scalable setup involves:
+
+1.  **Gate**: Your application, instrumented with OpenTelemetry, emitting metrics and traces via OTLP.
+2.  **OpenTelemetry Collector**: Receives OTLP data from Gate, processes it (batching, filtering, enrichment), and exports it.
+3.  **Grafana Mimir**: A scalable, long-term storage backend for metrics, receiving data from the OTel Collector (e.g., via Prometheus remote write or OTLP). It's queried using PromQL.
+4.  **Grafana Tempo**: A scalable backend for traces, receiving OTLP traces from the OTel Collector.
+5.  **Grafana OSS**: The visualization platform, connecting to Mimir (for metrics) and Tempo (for traces).
+
+The data flow generally looks like this:
+`Gate (OTLP) -> OTel Collector -> Grafana Mimir (Metrics) & Grafana Tempo (Traces) -> Grafana OSS (Visualization)`
+
+## In a setup with Grafana Mimir, is a separate Prometheus server still deployed?
+
+Generally, no. Grafana Mimir takes on the role of the scalable metrics backend, handling storage and PromQL querying. You wouldn't typically deploy and manage a separate, standalone Prometheus server for its own data storage in this scenario. However, Prometheus concepts and technologies are still integral:
+
+- **PromQL**: Used to query metrics from Mimir.
+- **Exposition Format**: Applications might still expose metrics in the Prometheus format.
+- **Collection Mechanisms**: The OTel Collector might use its Prometheus receiver, or Mimir ingests data via Prometheus remote write.
+
+Mimir effectively becomes your Prometheus-compatible, scalable metrics datastore and query engine.
+
+## What is the role of the OpenTelemetry Collector? Can applications like Gate push data directly to backends like Prometheus or Mimir?
+
+The OpenTelemetry Collector is a crucial component that acts as a telemetry processing and routing pipeline. While some backends (including newer versions of Prometheus and potentially Mimir) can accept OTLP data directly, the Collector offers significant advantages:
+
+- **Decoupling**: Applications only need to send data to the Collector, which then handles routing to various backends. This simplifies application configuration and makes it easier to change or add backends.
+- **Processing**: The Collector can batch data for efficiency, filter unwanted telemetry, enrich data with additional attributes (e.g., Kubernetes metadata), and handle export retries.
+- **Protocol Translation**: It can convert telemetry data between different protocols if needed.
+- **Standardization**: It promotes a standardized way of handling telemetry data before it reaches the backends.
+
+For these reasons, even if direct sending is possible, using the OTel Collector is often the recommended approach for flexibility and robustness.
+
+## How do Grafana Mimir and Grafana Tempo fit into this?
+
+- **Grafana Mimir**: Serves as a highly scalable, long-term storage solution for Prometheus metrics. It addresses potential scaling limitations of a single Prometheus instance for large data volumes and long retention periods. It remains compatible with PromQL for querying.
+- **Grafana Tempo**: Is a highly scalable, easy-to-operate distributed tracing backend. It's optimized for ingesting and retrieving traces by ID and integrates well with Grafana for visualization and correlation with metrics and logs.
+
+## Why does my OpenTelemetry `service.name` appear as the `job` label in Prometheus?
+
+When you send telemetry from an application (like Gate) instrumented with OpenTelemetry to an OpenTelemetry Collector, and then the Collector forwards this data to Prometheus (typically using the `prometheusremotewrite` exporter), a common and intentional translation occurs:
+
+1.  **OTLP Transmits Resource Attributes**: Your application sends `service.name` (along with other details like `service.version`, `host.name`, etc.) as "resource attributes" within the OTLP (OpenTelemetry Protocol) data. These attributes describe the entity generating the telemetry.
+
+2.  **Collector's Role (`prometheusremotewrite` Exporter)**: The OpenTelemetry Collector receives this OTLP data. When configured to send metrics to Prometheus, its `prometheusremotewrite` exporter takes on the task of converting the OpenTelemetry data model into the format Prometheus understands.
+
+3.  **Default Convention: `service.name` to `job`**: By default, and in line with common Prometheus conventions, this exporter maps the OpenTelemetry `service.name` resource attribute to the `job` label in Prometheus. Similarly, `service.instance.id` is often mapped to the `instance` label.
+
+**In essence, if you see `job="your-service-name"` in Prometheus, this _is_ your OpenTelemetry `service.name` attribute.** It has been translated to the standard Prometheus `job` label, which is the conventional way to identify a service or application in Prometheus.
+
+You generally do **not** need to add special processing in the Collector (e.g., using an `attributes` processor) to achieve this mapping; it's a standard behavior of the `prometheusremotewrite` exporter. This design choice simplifies integration and aligns with how Prometheus users typically organize and query their metrics.
diff --git a/.web/docs/guide/otel/grafana-cloud/index.md b/.web/docs/guide/otel/grafana-cloud/index.md
@@ -0,0 +1,78 @@
+# Grafana Cloud
+
+[Grafana Cloud](https://grafana.com/products/cloud/) is a fully managed observability platform that supports OpenTelemetry. Follow these steps to set up Gate with Grafana Cloud:
+
+1. **Create a Grafana Cloud Account**
+
+   - Sign up at [Grafana.com](https://grafana.com/auth/sign-up/create-user)
+   - Navigate to your organization
+   - Create an Access Policy with write permissions at [Access Policies](https://grafana.com/orgs/your-org/access-policies)
+   - Generate and save your API token
+
+2. **Configure Stack**
+
+   Navigate to your Grafana Cloud Stack (e.g., grafana.com/orgs/your-org/stacks/xxxxx) and:
+
+   - Click "Send Traces" in the Tempo section to get your traces endpoint
+   - Click "Send Metrics" in the Prometheus section to get your metrics endpoint
+
+   ![Stack](./stack.png)
+
+3. **Prepare Your Authentication**
+
+   You'll need to encode your credentials in base64 format. Use one of these methods:
+
+   - Using the command line:
+
+     ```bash
+     echo "YOUR_INSTANCE_ID:YOUR_API_TOKEN" | base64
+     ```
+
+   - Or visit an online base64 encoder like [base64encode.org](https://www.base64encode.org/)
+
+4. **Configure Gate**
+
+   Export the following environment variables before starting Gate:
+
+   ```bash
+   # For traces (Tempo)
+   export OTEL_EXPORTER_OTLP_ENDPOINT="https://tempo-prod-XX-prod-XX-XXXXX.grafana.net/tempo"
+   export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic YOUR_BASE64_ENCODED_CREDENTIALS"
+
+   # For metrics (Prometheus)
+   export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
+   export OTEL_METRICS_EXPORTER="otlp"
+   export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT="https://prometheus-prod-XX-prod-XX-XXXXX.grafana.net/api/prom/push"
+   export OTEL_EXPORTER_OTLP_METRICS_HEADERS="Authorization=Basic YOUR_BASE64_ENCODED_CREDENTIALS"
+   ```
+
+   ::: tip
+   For production deployments, consider setting these environment variables in your system configuration or container orchestration platform rather than exporting them manually.
+   :::
+
+5. **Start Gate**
+
+   Once the environment variables are set, start Gate normally. It will automatically begin sending telemetry data to Grafana Cloud.
+
+   ```bash
+   gate
+   ```
+
+   See [Install](/guide/install/) for more information on how to start Gate.
+
+6. **View Your Data**
+
+   Log into your Grafana Cloud account and click on the "Launch" button for Grafana:
+
+   - Navigate to the Tempo service to view your traces
+   - Navigate to the Prometheus service to view your metrics
+
+   ![Launch](./launch.png)
+
+   - Go to the "Explore" section and select "Tempo" to in the sources
+
+   ![tempo-source](./tempo-source.png)
+
+   ![Trace](./trace.png)
+
+   - Or select "Prometheus" to view your metrics
diff --git a/.web/docs/guide/otel/grafana-cloud/launch.png b/.web/docs/guide/otel/grafana-cloud/launch.png
diff --git a/.web/docs/guide/otel/grafana-cloud/stack.png b/.web/docs/guide/otel/grafana-cloud/stack.png
diff --git a/.web/docs/guide/otel/grafana-cloud/tempo-source.png b/.web/docs/guide/otel/grafana-cloud/tempo-source.png
diff --git a/.web/docs/guide/otel/grafana-cloud/trace.png b/.web/docs/guide/otel/grafana-cloud/trace.png
diff --git a/.web/docs/guide/otel/honeycomb/index.md b/.web/docs/guide/otel/honeycomb/index.md
@@ -0,0 +1,49 @@
+# Honeycomb
+
+[Honeycomb](https://www.honeycomb.io/) is an OpenTelemetry-compatible observability platform that requires minimal setup - just sign up, create an environment, and get your API key to start collecting telemetry data. Here's how to get started:
+
+1. **Create a Honeycomb Account**
+
+   - Sign up at [Honeycomb.io](https://ui.honeycomb.io/signup)
+   - Create a new environment (or use an existing one)
+   - Get your API key from Environment Settings
+
+2. **Configure Gate**
+
+   Export the following environment variables before starting Gate:
+
+   ::: code-group
+
+   ```bash [US Region]
+   export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.honeycomb.io:443"
+   export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=your-api-key"
+   ```
+
+   ```bash [EU Region]
+   export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.eu1.honeycomb.io:443"
+   export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=your-api-key"
+   ```
+
+   :::
+
+   ::: tip
+   For production deployments, consider setting these environment variables in your system configuration or container orchestration platform rather than exporting them manually.
+   :::
+
+3. **Start Gate**
+
+   Once the environment variables are set, start Gate normally. It will automatically begin sending telemetry data to Honeycomb.
+
+   ```bash
+   gate
+   ```
+
+   See [Install](/guide/install/) for more information on how to start Gate.
+
+4. **View Your Data**
+
+   Log into your Honeycomb account and navigate to your environment. You should see your Gate service appearing in the list of services, and you can start creating queries and visualizations to analyze your data.
+
+   ![Trace](trace.png)
+
+   ![Metric](metric.png)
diff --git a/.web/docs/guide/otel/honeycomb/metric.png b/.web/docs/guide/otel/honeycomb/metric.png
diff --git a/.web/docs/guide/otel/honeycomb/trace.png b/.web/docs/guide/otel/honeycomb/trace.png