feat(WIP): add opentelemetry

.web/docs/.vitepress/config.ts

@@ -174,6 +174,20 @@ export default defineConfig({
               text: 'Rate Limiting',
               link: '/guide/rate-limiting',
             },
+            {
+              text: 'OpenTelemetry',
+              link: '/guide/otel/',
+              items: [
+                {
+                  text: 'Grafana Cloud',
+                  link: '/guide/otel/grafana-cloud/',
+                },
+                {
+                  text: 'Honeycomb',
+                  link: '/guide/otel/honeycomb/',
+                },
+              ],
+            },
           ],
         },
         {

.web/docs/developers/api/go/index.md

@@ -47,7 +47,7 @@ go run .
 }
 ```
 
-This example project is located in the [`docs/developers/api/go`](https://github.com/minekube/gate/tree/main/.web/docs/developers/api/go) directory.
+This example project is located in the [`docs/developers/api/go`](https://github.com/minekube/gate/tree/master/.web/docs/developers/api/go) directory.
 
 ::: info Learn More
 For more details on using ConnectRPC with Go, check out the [ConnectRPC Documentation](https://connectrpc.com/docs/go/getting-started#make-requests).

.web/docs/developers/api/java/index.md

@@ -102,7 +102,7 @@ Here's a basic example of using the Gate Java API to connect to Gate and list se
 ## Running the Example
 
 1. Run Gate with the API enabled
-2. Navigate to the [docs/developers/api/java](https://github.com/minekube/gate/tree/main/.web/docs/developers/api/java) directory
+2. Navigate to the [docs/developers/api/java](https://github.com/minekube/gate/tree/master/.web/docs/developers/api/java) directory
 3. Run the following commands:
 
 ```bash

.web/docs/developers/api/kotlin/index.md

@@ -156,13 +156,15 @@ Here's a basic example of using the Gate Kotlin API to connect to Gate and list
 ## Running the Example
 
 1. Run Gate with the API enabled
-2. Navigate to the [docs/developers/api/kotlin](https://github.com/minekube/gate/tree/main/.web/docs/developers/api/kotlin) directory
+2. Navigate to the [docs/developers/api/kotlin](https://github.com/minekube/gate/tree/master/.web/docs/developers/api/kotlin) directory
 3. Initialize the Gradle wrapper (only needed once):
+
 ```bash
 gradle wrapper
 ```
 
 4. Run one of the following commands:
+
 ```bash
 # For Connect example (recommended)
 ./gradlew runConnect
@@ -193,7 +195,6 @@ servers {
 For more details on using ConnectRPC with Kotlin, check out the [ConnectRPC Documentation](https://connectrpc.com/docs/kotlin/using-clients).
 :::
 
-
 <style>
 .tech-icon {
   width: 32px;

.web/docs/developers/api/rust/index.md

@@ -40,7 +40,7 @@ cargo add tonic --features tls-roots # Enable the features we need
 cargo add tokio --features macros,rt-multi-thread # Async runtime
 ```
 
-This is the sample `Cargo.toml` file from the [`docs/developers/api/rust`](https://github.com/minekube/gate/tree/main/.web/docs/developers/api/rust) directory:
+This is the sample `Cargo.toml` file from the [`docs/developers/api/rust`](https://github.com/minekube/gate/tree/master/.web/docs/developers/api/rust) directory:
 
 ```toml
 <!--@include: ./Cargo.toml -->

.web/docs/developers/api/typescript/bun/index.md

@@ -50,7 +50,7 @@ To use the Gate API in the browser, check out the [Web](/developers/api/typescri
 
 ## Sample project
 
-This sample project is located in the [`docs/developers/api/typescript/bun`](https://github.com/minekube/gate/tree/main/.web/docs/developers/api/typescript/bun) directory.
+This sample project is located in the [`docs/developers/api/typescript/bun`](https://github.com/minekube/gate/tree/master/.web/docs/developers/api/typescript/bun) directory.
 
 To install dependencies:
 

.web/docs/developers/api/typescript/node/index.md

@@ -66,7 +66,7 @@ import { GateService } from '@buf/minekube_gate.connectrpc_es/minekube/gate/v1/g
 
 ## Sample project
 
-This sample project is located in the [`docs/developers/api/typescript/node`](https://github.com/minekube/gate/tree/main/.web/docs/developers/api/typescript/node) directory.
+This sample project is located in the [`docs/developers/api/typescript/node`](https://github.com/minekube/gate/tree/master/.web/docs/developers/api/typescript/node) directory.
 
 To install dependencies:
 

.web/docs/developers/api/typescript/web/index.md

@@ -66,7 +66,7 @@ import { GateService } from '@buf/minekube_gate.connectrpc_es/minekube/gate/v1/g
 
 ## Sample project
 
-This sample project is located in the [`docs/developers/api/typescript/node`](https://github.com/minekube/gate/tree/main/.web/docs/developers/api/typescript/node) directory.
+This sample project is located in the [`docs/developers/api/typescript/node`](https://github.com/minekube/gate/tree/master/.web/docs/developers/api/typescript/node) directory.
 
 To install dependencies:
 

.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

.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)

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

@@ -0,0 +1,134 @@
+# 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.
+
+## 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   |
+
+Additional environment variables for exporters:
+
+| Environment Variable                | Required | Default          | Description                          |
+| ----------------------------------- | -------- | ---------------- | ------------------------------------ |
+| 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_RESOURCE_ATTRIBUTES            | No       | -                | Additional resource attributes       |
+
+## Example Configuration
+
+Here's an example configuration for sending telemetry to a local OpenTelemetry collector:
+
+```env
+OTEL_SERVICE_NAME="my-gate-service"
+OTEL_EXPORTER_OTLP_ENDPOINT="localhost:4317"
+OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
+OTEL_RESOURCE_ATTRIBUTES="deployment.environment=production"
+```
+
+## Observability Solutions
+
+You can use various solutions to collect and visualize OpenTelemetry data. Here are some popular options:
+
+### Cloud Solutions
+
+::: info <VPBadge>Our recommendations</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
+
+:::
+
+- [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
+- [AWS X-Ray](https://aws.amazon.com/xray/) - Distributed tracing system for AWS applications
+- [Google Cloud Operations Suite](https://cloud.google.com/operations) - Formerly Stackdriver, for monitoring, logging, and diagnostics
+
+### Self-Hosted Solutions
+
+#### Tracing
+
+- [Tempo](https://grafana.com/oss/tempo/) - Grafana Tempo is a high-scale distributed tracing backend
+- [Jaeger](https://www.jaegertracing.io/) - Open source, end-to-end distributed tracing
+
+#### Metrics
+
+- [Mimir](https://grafana.com/oss/mimir/) - Grafana Mimir is a highly scalable Prometheus solution
+
+#### Visualization
+
+- [Grafana](https://grafana.com/oss/grafana/) - The open and composable observability and data visualization platform
+
+## Best Practices
+
+1. **Service Name**: Always set a meaningful `OTEL_SERVICE_NAME` that clearly identifies your service.
+
+   ```env
+   # Good examples:
+   OTEL_SERVICE_NAME="gate-proxy-eu"
+   OTEL_SERVICE_NAME="gate-proxy-lobby"
+
+   # Bad examples:
+   OTEL_SERVICE_NAME="proxy"  # too generic
+   OTEL_SERVICE_NAME="gate"   # not specific enough
+   ```
+
+2. **Service Version**: Set `OTEL_SERVICE_VERSION` to track your application version:
+
+   ```env
+   # Semantic versioning
+   OTEL_SERVICE_VERSION="v1.2.3"
+
+   # Git commit hash
+   OTEL_SERVICE_VERSION="git-8f45d91"
+
+   # Build number
+   OTEL_SERVICE_VERSION="build-1234"
+   ```
+
+3. **Resource Attributes**: Use `OTEL_RESOURCE_ATTRIBUTES` to add important context like environment, region, or deployment info.
+
+   ```env
+   # Single attribute
+   OTEL_RESOURCE_ATTRIBUTES="deployment.environment=production"
+
+   # Multiple attributes
+   OTEL_RESOURCE_ATTRIBUTES="deployment.environment=production,cloud.region=eu-west-1,kubernetes.namespace=game-servers"
+
+   # With detailed context
+   OTEL_RESOURCE_ATTRIBUTES="deployment.environment=production,service.instance.id=gate-1,cloud.provider=aws,cloud.region=us-east-1"
+   ```
+
+4. **Security**: In production environments:
+
+   ```env
+   # 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
+
+- [OpenTelemetry Documentation](https://opentelemetry.io/docs/)
+- [otel-config-go Repository](https://github.com/honeycombio/otel-config-go)
+- [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)