From 9be044e8766ebca76580774f125d6fe8abb095b5 Mon Sep 17 00:00:00 2001 From: Documentation Writer Bot Date: Wed, 24 Sep 2025 16:38:51 +0000 Subject: [PATCH] docs: add guide documentation Generated for change 58a130b9 from envoyproxy/ai-gateway Type: guide Priority: medium New feature detected that would benefit from user guide --- site/docs/guides/main-guide.md | 176 +++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 site/docs/guides/main-guide.md diff --git a/site/docs/guides/main-guide.md b/site/docs/guides/main-guide.md new file mode 100644 index 0000000000..8cbf4f2c5f --- /dev/null +++ b/site/docs/guides/main-guide.md @@ -0,0 +1,176 @@ +# OpenTelemetry Metrics Export Guide + +This guide explains how to configure OpenTelemetry (OTEL) metrics export in AI Gateway, including support for native OTEL systems and console output for debugging. + +## Overview + +AI Gateway now supports exporting metrics directly to OpenTelemetry collectors, eliminating the need for Prometheus in OTEL-native environments. This feature enables integration with systems like Elastic Stack, OTEL TUI, and other OTEL-compatible monitoring solutions. + +## Configuration + +### Environment Variables + +Configure metrics export using these environment variables: + +```bash +# Enable OTEL metrics export (replaces Prometheus listener) +OTEL_METRICS_EXPORTER=otlp + +# Console output for debugging (no external dependencies) +OTEL_METRICS_EXPORTER=console + +# Disable metrics export (useful for Phoenix users who only need traces) +OTEL_METRICS_EXPORTER=none + +# Separate OTLP endpoints for traces and metrics +OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces +OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://localhost:4318/v1/metrics +``` + +### Export Types + +#### OTLP Export +Exports metrics to OpenTelemetry Protocol (OTLP) collectors: + +```bash +OTEL_METRICS_EXPORTER=otlp +OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://your-otel-collector:4318/v1/metrics +``` + +#### Console Export +Outputs metrics to console for immediate debugging: + +```bash +OTEL_METRICS_EXPORTER=console +``` + +#### Disabled Export +Disables metrics export entirely: + +```bash +OTEL_METRICS_EXPORTER=none +``` + +## Usage Examples + +### Docker Compose with OTEL TUI + +Example configuration for using OTEL TUI for metrics visualization: + +```yaml +# docker-compose.yaml +services: + ai-gateway: + environment: + - OTEL_METRICS_EXPORTER=otlp + - OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://otel-collector:4318/v1/metrics + - OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://otel-collector:4318/v1/traces + + otel-collector: + image: otel/opentelemetry-collector:latest + ports: + - "4317:4317" + - "4318:4318" + + otel-tui: + image: ymtdzzz/otel-tui:latest + ports: + - "8080:8080" +``` + +### Environment File Profiles + +Use profile-based environment file selection for different configurations: + +```bash +# .env.otel.console +OTEL_METRICS_EXPORTER=console +OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces + +# .env.otel.otlp +OTEL_METRICS_EXPORTER=otlp +OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://localhost:4318/v1/metrics +OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces + +# .env.otel.phoenix +OTEL_METRICS_EXPORTER=none +OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://phoenix:4317/v1/traces +``` + +Load the appropriate profile: +```bash +COMPOSE_PROFILES=console docker-compose up +COMPOSE_PROFILES=otlp docker-compose up +COMPOSE_PROFILES=phoenix docker-compose up +``` + +## Integration Examples + +### Elastic Stack Integration + +Configure for Elastic APM: + +```bash +OTEL_METRICS_EXPORTER=otlp +OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://your-elastic-apm:8200/intake/v2/otlp/v1/metrics +OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-secret-token" +``` + +### Phoenix Integration + +For Phoenix users who only need tracing: + +```bash +OTEL_METRICS_EXPORTER=none +OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://phoenix:4317/v1/traces +``` + +### Development and Debugging + +For local development with immediate feedback: + +```bash +OTEL_METRICS_EXPORTER=console +``` + +This outputs metrics directly to the console without requiring external services. + +## Migration from Prometheus + +When migrating from Prometheus-based metrics: + +1. **Before**: Metrics were exposed via Prometheus endpoint +2. **After**: Set `OTEL_METRICS_EXPORTER=otlp` to export via OTEL +3. **Compatibility**: Both can coexist during migration period + +## Troubleshooting + +### Common Issues + +**Metrics not appearing in collector:** +- Verify `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` is correctly set +- Check collector configuration accepts OTLP metrics +- Ensure network connectivity between AI Gateway and collector + +**Console output too verbose:** +- Use `OTEL_METRICS_EXPORTER=none` to disable metrics +- Consider using OTLP export with filtering in the collector + +**Phoenix compatibility:** +- Always set `OTEL_METRICS_EXPORTER=none` for Phoenix deployments +- Phoenix only supports trace data, not metrics + +### Verification + +Verify metrics export is working: + +1. **Console mode**: Check application logs for metric output +2. **OTLP mode**: Verify metrics appear in your OTEL collector/backend +3. **None mode**: Confirm no metrics-related errors in logs + +## Best Practices + +1. **Environment-specific configuration**: Use profile-based env files for different deployment environments +2. **Resource optimization**: Use `none` export type when metrics aren't needed +3. **Debugging**: Start with `console` export for initial setup and troubleshooting +4. **Production**: Use `otlp` export with appropriate collector configuration for production deployments \ No newline at end of file