Merge branch 'DOC-1867-Document-feature-AI-Gateway-help-cloud-team-polish-clean-up' into adp-pkg1

paulohtb6 · paulohtb6 · commit 7764ca784b6e · 2026-02-03T12:11:36.000-03:00
diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc
@@ -52,10 +52,10 @@
 **** xref:ai-agents:ai-gateway/builders/connect-your-agent.adoc[Connect Your Agent]
 **** xref:ai-agents:ai-gateway/cel-routing-cookbook.adoc[CEL Routing Patterns]
 **** xref:ai-agents:ai-gateway/mcp-aggregation-guide.adoc[MCP Aggregation]
-*** Observability
-**** xref:ai-agents:ai-gateway/observability-logs.adoc[Request Logs]
-**** xref:ai-agents:ai-gateway/observability-metrics.adoc[Metrics and Analytics]
-*** xref:ai-agents:ai-gateway/migration-guide.adoc[Migrate]
+//*** Observability
+//**** xref:ai-agents:ai-gateway/observability-logs.adoc[Request Logs]
+//**** xref:ai-agents:ai-gateway/observability-metrics.adoc[Metrics and Analytics]
+//*** xref:ai-agents:ai-gateway/migration-guide.adoc[Migrate]
 *** xref:ai-agents:ai-gateway/integrations/index.adoc[Integrations]
 **** Claude Code
 ***** xref:ai-agents:ai-gateway/integrations/claude-code-admin.adoc[Admin Guide]
diff --git a/modules/ai-agents/pages/ai-gateway/admin/setup-guide.adoc b/modules/ai-agents/pages/ai-gateway/admin/setup-guide.adoc
@@ -316,10 +316,8 @@ Users can then discover and connect to the gateway using the information provide
 * xref:ai-gateway/cel-routing-cookbook.adoc[CEL Routing Cookbook] - Advanced routing patterns
 // * xref:ai-gateway/admin/networking-configuration.adoc[Networking Configuration] - Configure private endpoints and connectivity
 
-*Monitor and observe:*
-
-* xref:ai-gateway/observability-metrics.adoc[Monitor Usage] - Track costs and usage across all gateways
-* xref:ai-gateway/observability-logs.adoc[Request Logs] - View and filter request logs
+//*Monitor and observe:*
+//
 
 *Integrate tools:*
 
diff --git a/modules/ai-agents/pages/ai-gateway/cel-routing-cookbook.adoc b/modules/ai-agents/pages/ai-gateway/cel-routing-cookbook.adoc
@@ -951,4 +951,3 @@ Each request evaluates CEL expression once. Total latency impact:
 == Next steps
 
 * *Apply CEL routing*: See the gateway configuration options available in the Redpanda Cloud console.
-* *Monitor routing decisions*: xref:ai-agents:ai-gateway/observability-logs.adoc[]
diff --git a/modules/ai-agents/pages/ai-gateway/gateway-architecture.adoc b/modules/ai-agents/pages/ai-gateway/gateway-architecture.adoc
@@ -147,4 +147,3 @@ The gateway only loads and exposes specific tools when requested, which dramatic
 
 * xref:ai-agents:ai-gateway/gateway-quickstart.adoc[]: Route your first request through AI Gateway
 * xref:ai-agents:ai-gateway/mcp-aggregation-guide.adoc[]: Configure MCP server aggregation for AI agents
-* xref:ai-agents:ai-gateway/observability-logs.adoc[]: Monitor request logs, token usage, and costs
diff --git a/modules/ai-agents/pages/ai-gateway/gateway-quickstart.adoc b/modules/ai-agents/pages/ai-gateway/gateway-quickstart.adoc
@@ -561,8 +561,6 @@ Explore advanced AI Gateway features:
 
 * xref:ai-agents:ai-gateway/cel-routing-cookbook.adoc[]: Advanced CEL routing patterns for traffic distribution and cost optimization
 * xref:ai-agents:ai-gateway/mcp-aggregation-guide.adoc[]: Configure MCP server aggregation and deferred tool loading
-* xref:ai-agents:ai-gateway/observability-logs.adoc[]: Monitor request logs, token usage, and costs
-* xref:ai-agents:ai-gateway/migration-guide.adoc[]: Migrate existing LLM integrations to AI Gateway
 * xref:ai-agents:ai-gateway/integrations/index.adoc[]: Connect more AI development tools
 
 Learn about the architecture:
diff --git a/modules/ai-agents/pages/ai-gateway/integrations/claude-code-admin.adoc b/modules/ai-agents/pages/ai-gateway/integrations/claude-code-admin.adoc
@@ -299,7 +299,7 @@ Implement token rotation for security:
 
 . Create a new token before the existing token expires
 . Distribute the new token to users
-. Monitor usage of the old token in xref:ai-agents:ai-gateway/observability-logs.adoc[request logs]
+. Monitor usage of the old token in (observability dashboard)
 . Revoke the old token after all users have migrated
 
 == Configure Claude Code clients
@@ -393,7 +393,6 @@ Track Claude Code activity through gateway observability features.
 |Identify failing requests or misconfigured clients
 |===
 
-For detailed metrics configuration, see xref:ai-agents:ai-gateway/observability-metrics.adoc[].
 
 === Query logs via API
 
@@ -498,7 +497,5 @@ Causes and solutions:
 
 == Next steps
 
-* xref:ai-agents:ai-gateway/observability-logs.adoc[]: Analyze detailed request logs
-* xref:ai-agents:ai-gateway/observability-metrics.adoc[]: Set up metrics dashboards
 * xref:ai-agents:ai-gateway/cel-routing-cookbook.adoc[]: Implement advanced routing rules
 * xref:ai-agents:mcp/remote/overview.adoc[]: Deploy Remote MCP servers for custom tools
diff --git a/modules/ai-agents/pages/ai-gateway/integrations/claude-code-user.adoc b/modules/ai-agents/pages/ai-gateway/integrations/claude-code-user.adoc
@@ -413,7 +413,6 @@ chmod 600 ~/.claude.json
 == Next steps
 
 * xref:ai-agents:ai-gateway/mcp-aggregation-guide.adoc[]: Configure deferred tool loading to reduce token costs
-* xref:ai-agents:ai-gateway/observability-logs.adoc[]: Monitor Claude Code requests in the gateway dashboard
 * xref:ai-agents:ai-gateway/cel-routing-cookbook.adoc[]: Use CEL expressions to route Claude Code requests based on context
 
 == Related pages
diff --git a/modules/ai-agents/pages/ai-gateway/integrations/cline-admin.adoc b/modules/ai-agents/pages/ai-gateway/integrations/cline-admin.adoc
@@ -320,7 +320,7 @@ Implement token rotation for security:
 
 . Create a new token before the existing token expires
 . Distribute the new token to users
-. Monitor usage of the old token in xref:ai-agents:ai-gateway/observability-logs.adoc[request logs]
+. Monitor usage of the old token in (observability dashboard)
 . Revoke the old token after all users have migrated
 
 == Configure Cline clients
@@ -447,7 +447,6 @@ Cline autonomous operations may generate request sequences. Look for patterns to
 |Identify failing requests or misconfigured clients
 |===
 
-For detailed metrics configuration, see xref:ai-agents:ai-gateway/observability-metrics.adoc[].
 
 === Query logs via API
 
@@ -584,7 +583,5 @@ Causes and solutions:
 
 == Next steps
 
-* xref:ai-agents:ai-gateway/observability-logs.adoc[]: Analyze detailed request logs
-* xref:ai-agents:ai-gateway/observability-metrics.adoc[]: Set up metrics dashboards
 * xref:ai-agents:ai-gateway/cel-routing-cookbook.adoc[]: Implement advanced routing rules
 * xref:ai-agents:mcp/remote/overview.adoc[]: Deploy Remote MCP servers for custom tools
diff --git a/modules/ai-agents/pages/ai-gateway/integrations/cline-user.adoc b/modules/ai-agents/pages/ai-gateway/integrations/cline-user.adoc
@@ -752,7 +752,6 @@ The gateway automatically blocks requests that would exceed the limit.
 == Next steps
 
 * xref:ai-agents:ai-gateway/mcp-aggregation-guide.adoc[]: Configure deferred tool loading to reduce token costs
-* xref:ai-agents:ai-gateway/observability-logs.adoc[]: Monitor Cline requests in the gateway dashboard
 * xref:ai-agents:ai-gateway/cel-routing-cookbook.adoc[]: Use CEL expressions to route Cline requests based on task complexity
 
 == Related pages
diff --git a/modules/ai-agents/pages/ai-gateway/integrations/continue-admin.adoc b/modules/ai-agents/pages/ai-gateway/integrations/continue-admin.adoc
@@ -412,7 +412,7 @@ Implement token rotation for security:
 
 . Create a new token before the existing token expires
 . Distribute the new token to users
-. Monitor usage of the old token in xref:ai-agents:ai-gateway/observability-logs.adoc[request logs]
+. Monitor usage of the old token in (observability dashboard)
 . Revoke the old token after all users have migrated
 
 == Configure Continue.dev clients
@@ -600,7 +600,6 @@ Continue.dev generates different request patterns:
 |Identify failing providers or misconfigured backends
 |===
 
-For detailed metrics configuration, see xref:ai-agents:ai-gateway/observability-metrics.adoc[].
 
 === Query logs via API
 
@@ -757,7 +756,5 @@ This is expected behavior, not a configuration issue:
 
 == Next steps
 
-* xref:ai-agents:ai-gateway/observability-logs.adoc[]: Analyze detailed request logs
-* xref:ai-agents:ai-gateway/observability-metrics.adoc[]: Set up metrics dashboards
 * xref:ai-agents:ai-gateway/cel-routing-cookbook.adoc[]: Implement advanced routing rules
 * xref:ai-agents:mcp/remote/overview.adoc[]: Deploy Remote MCP servers for custom tools
diff --git a/modules/ai-agents/pages/ai-gateway/integrations/continue-user.adoc b/modules/ai-agents/pages/ai-gateway/integrations/continue-user.adoc
@@ -932,7 +932,6 @@ Autocomplete rarely needs more than 256 tokens, while chat responses can vary.
 == Next steps
 
 * xref:ai-agents:ai-gateway/mcp-aggregation-guide.adoc[]: Configure deferred tool loading to reduce token costs
-* xref:ai-agents:ai-gateway/observability-logs.adoc[]: Monitor Continue.dev requests in the gateway dashboard
 * xref:ai-agents:ai-gateway/cel-routing-cookbook.adoc[]: Use CEL expressions to route Continue.dev requests based on context
 
 == Related pages
diff --git a/modules/ai-agents/pages/ai-gateway/integrations/cursor-admin.adoc b/modules/ai-agents/pages/ai-gateway/integrations/cursor-admin.adoc
@@ -373,7 +373,7 @@ Implement token rotation for security:
 
 . Create a new token before the existing token expires
 . Distribute the new token to users
-. Monitor usage of the old token in xref:ai-agents:ai-gateway/observability-logs.adoc[request logs]
+. Monitor usage of the old token in (observability dashboard)
 . Revoke the old token after all users have migrated
 
 == Multi-tenant deployment strategies
@@ -647,7 +647,6 @@ Cursor generates different request patterns:
 |Monitor OpenAI-to-provider format conversion success
 |===
 
-For detailed metrics configuration, see xref:ai-agents:ai-gateway/observability-metrics.adoc[].
 
 === Query logs via API
 
@@ -811,7 +810,5 @@ Causes and solutions:
 
 == Next steps
 
-* xref:ai-agents:ai-gateway/observability-logs.adoc[]: Analyze detailed request logs and transform operations
-* xref:ai-agents:ai-gateway/observability-metrics.adoc[]: Set up metrics dashboards
 * xref:ai-agents:ai-gateway/cel-routing-cookbook.adoc[]: Implement advanced routing rules for model prefix routing
 * xref:ai-agents:mcp/remote/overview.adoc[]: Deploy Remote MCP servers for custom tools
diff --git a/modules/ai-agents/pages/ai-gateway/integrations/cursor-user.adoc b/modules/ai-agents/pages/ai-gateway/integrations/cursor-user.adoc
@@ -869,7 +869,6 @@ This sends only search + orchestrator tools initially, reducing token usage sign
 == Next steps
 
 * xref:ai-agents:ai-gateway/mcp-aggregation-guide.adoc[]: Configure deferred tool loading to work within Cursor's 40-tool limit
-* xref:ai-agents:ai-gateway/observability-logs.adoc[]: Monitor Cursor requests in the gateway dashboard
 * xref:ai-agents:ai-gateway/cel-routing-cookbook.adoc[]: Use CEL expressions to route Cursor requests based on context
 
 == Related pages
diff --git a/modules/ai-agents/pages/ai-gateway/integrations/github-copilot-admin.adoc b/modules/ai-agents/pages/ai-gateway/integrations/github-copilot-admin.adoc
@@ -321,7 +321,7 @@ Implement token rotation for security:
 
 . Create a new token before the existing token expires
 . Update organization-level GitHub Copilot configuration with the new token
-. Monitor usage of the old token in xref:ai-agents:ai-gateway/observability-logs.adoc[request logs]
+. Monitor usage of the old token in (observability dashboard)
 . Revoke the old token after the configuration update propagates
 
 == Multi-tenant deployment strategies
@@ -647,7 +647,6 @@ GitHub Copilot generates distinct request patterns:
 |Track usage by team (if using multi-tenant strategies)
 |===
 
-For detailed metrics configuration, see xref:ai-agents:ai-gateway/observability-metrics.adoc[].
 
 === Query logs via API
 
@@ -824,7 +823,5 @@ Causes and solutions:
 
 == Next steps
 
-* xref:ai-agents:ai-gateway/observability-logs.adoc[]: Analyze detailed request logs and transform operations
-* xref:ai-agents:ai-gateway/observability-metrics.adoc[]: Set up metrics dashboards
 * xref:ai-agents:ai-gateway/cel-routing-cookbook.adoc[]: Implement advanced routing rules for model aliasing
-* xref:ai-agents:ai-gateway/migration-guide.adoc[]: Migrate from direct provider access to AI Gateway
+
diff --git a/modules/ai-agents/pages/ai-gateway/integrations/github-copilot-user.adoc b/modules/ai-agents/pages/ai-gateway/integrations/github-copilot-user.adoc
@@ -953,7 +953,6 @@ Generate project-specific cost reports from the gateway dashboard.
 
 == Next steps
 
-* xref:ai-agents:ai-gateway/observability-logs.adoc[]: Monitor GitHub Copilot requests in the gateway dashboard
 * xref:ai-agents:ai-gateway/cel-routing-cookbook.adoc[]: Use CEL expressions to route Copilot requests based on context
 * xref:ai-agents:ai-gateway/mcp-aggregation-guide.adoc[]: Learn about MCP tool integration (if using Copilot Workspace)
 
diff --git a/modules/ai-agents/pages/ai-gateway/mcp-aggregation-guide.adoc b/modules/ai-agents/pages/ai-gateway/mcp-aggregation-guide.adoc
@@ -1024,5 +1024,3 @@ response = agent.run("Find all premium users in the database")
 
 == Next steps
 
-* xref:ai-agents:ai-gateway/observability-logs.adoc[]: Monitor MCP usage in request logs.
-* xref:ai-agents:ai-gateway/observability-metrics.adoc[]: Track MCP metrics and costs.
diff --git a/modules/ai-agents/pages/ai-gateway/what-is-ai-gateway.adoc b/modules/ai-agents/pages/ai-gateway/what-is-ai-gateway.adoc
@@ -26,7 +26,7 @@ Finally, observability is fragmented across provider dashboards. You cannot reco
 
 Redpanda AI Gateway addresses these challenges through four core capabilities:
 
-=== 1. Unified LLM access (single endpoint for all providers)
+=== Unified LLM access (single endpoint for all providers)
 
 AI Gateway provides a single OpenAI-compatible endpoint that routes requests to multiple LLM providers. Instead of integrating with each provider's SDK separately, you configure your application once and switch providers by changing only the model parameter.
 
@@ -80,7 +80,7 @@ response = client.chat.completions.create(
 
 To switch providers, you change only the `model` parameter from `openai/gpt-4o` to `anthropic/claude-sonnet-3.5`. No code changes or redeployment needed.
 
-=== 2. Policy-based routing and cost control
+=== Policy-based routing and cost control
 
 AI Gateway lets you define routing rules, rate limits, and budgets once, then enforces them automatically for all requests.
 
@@ -98,7 +98,7 @@ You can also set different rate limits and spend limits per environment to preve
 
 For reliability, you can configure provider pools with automatic failover. If you configure OpenAI GPT-4 as your primary model and Anthropic Claude Opus as the fallback, the gateway automatically routes requests to the fallback when it detects rate limits or timeouts from the primary provider. This configuration can significantly improve uptime (potentially up to 99.9% in some configurations) even during provider outages.
 
-=== 3. MCP aggregation and orchestration
+=== MCP aggregation and orchestration
 
 AI Gateway aggregates multiple MCP (Model Context Protocol) servers and provides deferred tool loading, which dramatically reduces token costs for AI agents.
 
@@ -108,14 +108,15 @@ With AI Gateway, you configure approved MCP servers once, and the gateway loads
 
 For complex workflows, AI Gateway provides a JavaScript-based orchestrator tool that reduces multi-step workflows from multiple round trips to a single call. For example, you can create a workflow that searches a vector database and, if the results are insufficient, falls back to web search—all in one orchestration step.
 
-=== 4. Unified observability and cost tracking
+=== Unified observability and cost tracking
 
 AI Gateway provides a single dashboard that tracks all LLM traffic across providers, eliminating the need to switch between multiple provider dashboards.
 
 The dashboard tracks request volume per gateway, model, and provider, along with token usage for both prompt and completion tokens. You can view estimated spend per model with cross-provider comparisons, latency metrics (p50, p95, p99), and errors broken down by type, provider, and model.
 
 This unified view helps you answer critical questions such as which model is the most cost-effective for your use case, why a specific user request failed, how much your staging environment costs per week, and what the latency difference is between providers for your workload.
 
+ifdef::show-gateway-patterns[]
 == Common gateway patterns
 
 === Team isolation
@@ -145,6 +146,8 @@ request.headers["x-customer-tier"] == "pro" ? "anthropic/claude-sonnet-3.5" :
 "anthropic/claude-haiku"
 ----
 
+endif::[]
+
 == When to use AI Gateway
 
 AI Gateway is ideal for organizations that:
diff --git a/modules/ai-agents/partials/migration-guide.adoc b/modules/ai-agents/partials/migration-guide.adoc
diff --git a/modules/ai-agents/partials/observability-logs.adoc b/modules/ai-agents/partials/observability-logs.adoc
diff --git a/modules/ai-agents/partials/observability-metrics.adoc b/modules/ai-agents/partials/observability-metrics.adoc

Original file line number	Diff line number	Diff line change
`@@ -951,4 +951,3 @@ Each request evaluates CEL expression once. Total latency impact:`
`951`	`951`	`== Next steps`
`952`	`952`
`953`	`953`	`* Apply CEL routing: See the gateway configuration options available in the Redpanda Cloud console.`
`954`		`-* Monitor routing decisions: xref:ai-agents:ai-gateway/observability-logs.adoc[]`
Original file line number	Diff line number	Diff line change
`@@ -147,4 +147,3 @@ The gateway only loads and exposes specific tools when requested, which dramatic`
`147`	`147`
`148`	`148`	`* xref:ai-agents:ai-gateway/gateway-quickstart.adoc[]: Route your first request through AI Gateway`
`149`	`149`	`* xref:ai-agents:ai-gateway/mcp-aggregation-guide.adoc[]: Configure MCP server aggregation for AI agents`
`150`		`-* xref:ai-agents:ai-gateway/observability-logs.adoc[]: Monitor request logs, token usage, and costs`