docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages

[janiussyafiq]

Summary

Fixes six new-developer onboarding gaps surfaced by an end-to-end walkthrough of the 7-page onboarding flow (docs/index.md → docs/configuration/bootstrap-config.md) against main at 1a744ee. Three of the fixes (#1, #2, #3) close hard blockers on a clean machine (missing cargo / npm / provider-API-key prerequisites; model_not_found from display_name/model_name ambiguity; an Observability Exporter section whose second sentence is style-guide advice rather than user content). The remaining three (#4, #5, #6) close friction points along the same path (bootstrap-config.md field tables missing a Default column and an observability subsection; two credential-handling operational callouts; a cold-build duration note).

Doc-only diff. No code, schemas, configs, or test fixtures touched.

Closes#325.

Changes

File	Change
docs/quickstart/self-hosted.md	Prerequisites: add Rust 1.93+ with cargo (via rustup) as the leading prerequisite. After cargo run …: add a one-sentence note that the first-time build typically takes 3–5 minutes and that subsequent runs are incremental.
docs/quickstart/first-model-first-key-first-request.md	Prerequisites: replace "A reachable upstream OpenAI-compatible endpoint" with explicit credential-acquisition guidance (supported providers, sign-up link with cost order-of-magnitude, sk-... format hint, placeholder pointer). After the ProviderKey create-time response example: add a :::warning callout that the secret field is plaintext and that GET /admin/v1/provider_keys/:id also returns the plaintext.
docs/quickstart/openai-sdk.md	New ## Prerequisites section placed between the "If you have not done that yet…" intro and the first ## What Changes In The SDK section. Lists a running gateway with provider key / model / API key already created, and Node.js 18+ with npm (the OpenAI SDK floor).
docs/overview/core-concepts.md	Model field-list bullet: inline-annotate display_name as the alias callers send in the API request's model field and model_name as the upstream model ID forwarded to the provider. API Key section: append a sentence after the key_hash description noting the plaintext is unrecoverable post-create and pointing at POST /admin/v1/apikeys/:id/rotate. Observability Exporter section: replace the documentation-author-facing second sentence with a user-facing description of what the resource does (OTLP-compatible export to external backends) and when to configure one.
docs/configuration/bootstrap-config.md	Add a Default column to the field tables on etcd, proxy, admin. Build out the observability section with a new field table covering service_name, log_level, access_log, metrics.prometheus.*, metrics.otlp.*, and tracing.otlp.*, plus a pointer to the dynamic Observability Exporters page. Build out the cache section with a small field table covering backend and redis.

Net diff: 5 files, +58 / -35. Source: git diff --stat.

Test plan

Doc-only diff — no .rs files, schemas, configs, or test fixtures touched. The cargo trio was still run end-to-end as the canonical pre-merge gate.

• cargo fmt --check — PASS (exit 0).
• cargo clippy --workspace --all-targets -- -D warnings — PASS (exit 0; full tail captured below).
• cargo test --workspace — PASS (exit 0; full crate-suite results captured below).
• grep -rln <each affected page> tests/e2e/ for all 5 pages returns empty. pnpm test under tests/e2e/ is not applicable for this diff.

cargo clippy tail

 Checking aisix-proxy v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-proxy)
Checking aisix-admin v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-admin)
Checking aisix-server v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-server)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 40.28s

cargo test summary

33 test-suite-result lines, all 'ok'. Aggregate: 1029 tests passed, 0 failed, 3 ignored across the workspace (unit suites + doc-tests). Sample tail (last 3 named tests + last result line):
test keyword::tests::invalid_regex_is_a_clean_error_not_a_panic ... ok
test usage::tests::full_channel_drop_does_not_panic ... ok
test dispatch::tests::build_v1_url_rejects_path_without_leading_slash - should panic ... ok
test result: ok. <N> passed; 0 failed; <N> ignored; 0 measured; 0 filtered out

Affected pages

• docs/quickstart/self-hosted.md
• docs/quickstart/first-model-first-key-first-request.md
• docs/quickstart/openai-sdk.md
• docs/overview/core-concepts.md
• docs/configuration/bootstrap-config.md

Pre-merge-check verification log

The three pre-merge checks called out in #325 were resolved as follows:

1. Rust / Node minimum versions. Verified Rust against rust-toolchain.toml (channel = "1.93.1") and Cargo.toml (rust-version = "1.93"). The issue body's tentative "Rust 1.79+" floor was bumped to Rust 1.93 or newer in the doc, and a note added that rustup will pull the right channel automatically because rust-toolchain.toml pins it. For Node.js, neither tests/e2e/package.json nor a top-level package.json declares an engines floor, so the doc cites Node.js 18 or newer (the OpenAI SDK's published floor at version 4.x shipped in tests/e2e/package.json).
2. Bootstrap-config Default column. Pulled all default values from crates/aisix-core/src/config.rs (this repo's config crate lives in aisix-core, not in a separate aisix-config crate as the issue body tentatively listed). Values pulled: EtcdConfig::default_prefix → "/aisix", default_dial_timeout / default_request_timeout → 5000ms, ProxyConfig::default_body_limit → 10 * 1024 * 1024, AdminConfig::default → addr "127.0.0.1:0" / admin_keys [] / tls None, ObservabilityConfig::default_service_name → "aisix", default_log_level → "info", default_access_log → true, PrometheusConfig::default → { enabled: true, path: "/metrics" }, OtlpConfig::default → { enabled: false, endpoint: None }, OtlpTracingConfig::default → { enabled: false, endpoint: None, sample_ratio: 1.0 }, CacheConfig::default → { backend: Memory, redis: None }. For fields without an explicit default and with Config::validate enforcement (etcd.endpoints, proxy.addr), the column reads required. For fields whose Default is None, the column reads none.
3. Provider-key GET response shape.crates/aisix-core/src/models/provider_key.rs:39 defines pub secret: String without #[serde(skip_serializing)], and crates/aisix-admin/src/provider_keys_handlers.rs:29-38 (get_provider_key) returns Json<ResourceEntry<ProviderKey>> — so GET /admin/v1/provider_keys/:iddoes include the plaintext secret in the response body, every time. The original draft callout in docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #325 read "subsequent reads via GET do not include it", which was empirically incorrect. The callout in this PR was adjusted to reflect actual behavior: the warning now states that the plaintext is in both the create response and any subsequent GET, and that the same handling applies any time you read the resource.

References

• docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #325 — docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages (this PR closes it)
• docs: replace GET /health references with /livez and /admin/v1/health across configuration, reference, and operations docs #293 — docs: replace GET /health references with /livez and /admin/v1/health (predecessor doc-correction; merged as docs: replace stale GET /health references with /livez and /admin/v1/health #294)
• docs: remove max_budget_usd references from standalone docs (managed-only field) #295 — docs: remove max_budget_usd references from standalone docs (predecessor doc-correction; merged as docs: remove max_budget_usd references from standalone docs (managed-only field) #296)
• docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials #249 — docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials (the docs rebuild whose pages this PR amends)

Summary by CodeRabbit

• Documentation
  • Converted narrative configuration sections into structured tables for bootstrap, observability, and cache settings (including defaults and required/optional status)
  • Clarified core concepts: model display vs upstream identifiers, API key lifecycle/rotation, and observability exporter behavior
  • Added quickstart prerequisites: upstream provider API key, Node.js 18+ for OpenAI SDK, Rust 1.93+ for self-hosted
  • Added warning to treat provider API secrets as sensitive

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 2f8aa0cb-5faa-4a13-a703-ebe2423802be

📥 Commits

Reviewing files that changed from the base of the PR and between 5401ff1 and 1094aac.

📒 Files selected for processing (1)

• docs/configuration/bootstrap-config.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/configuration/bootstrap-config.md

---

📝 Walkthrough

Walkthrough

This PR updates documentation: restructures bootstrap configuration sections into tables with defaults and optional flags, refines core concept fields and observability exporter text, and adds explicit quickstart prerequisites plus an API-key secrecy warning.

Changes

Documentation Clarity Improvements

Layer / File(s)	Summary
Bootstrap configuration tables docs/configuration/bootstrap-config.md	etcd, proxy, admin, observability, and cache "Important fields" are converted from narrative lists into tables that show default values, optional fields (e.g., tls), reserved telemetry keys, and conditional nested blocks (e.g., redis when backend: redis).
Core concept refinements docs/overview/core-concepts.md	Model section now documents display_name, provider, and model_name; API Key section notes plaintext bearer tokens cannot be retrieved after creation and must be rotated; Observability Exporter text focuses on OTLP-compatible telemetry export.
Quickstart prerequisites and security guidance docs/quickstart/openai-sdk.md, docs/quickstart/self-hosted.md, docs/quickstart/first-model-first-key-first-request.md	OpenAI SDK quickstart adds a Prerequisites section (gateway + Node.js 18+); self-hosted quickstart requires Rust 1.93+ and notes first cargo run compile time; first-model guide adds upstream provider API key prerequisite and warns that admin API returns secret in plaintext and it must be treated as sensitive.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This doc-only PR improves new-developer onboarding by clarifying prerequisites, model naming, credential handling, and bootstrap configuration defaults across the quickstart and overview/configuration docs.

Changes:

• Adds Rust/Node/provider-key prerequisite guidance and build-time expectations.
• Clarifies model alias vs upstream model ID and credential visibility.
• Expands bootstrap configuration tables, especially observability and cache fields.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/quickstart/self-hosted.md	Adds Rust/cargo prerequisite and first-build duration note.
docs/quickstart/openai-sdk.md	Adds gateway and Node.js/npm prerequisites.
docs/quickstart/first-model-first-key-first-request.md	Clarifies provider API key prerequisite and plaintext provider-key handling.
docs/overview/core-concepts.md	Clarifies model fields, API-key plaintext handling, and observability exporter description.
docs/configuration/bootstrap-config.md	Adds defaults and expanded observability/cache bootstrap field tables.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[janiussyafiq]

Applied. Rewrote the appended paragraph to reflect actual behavior: the plaintext bearer is chosen (or generated) by the caller and SHA-256-hashed locally before submission, the gateway never sees or returns the plaintext at create time, and POST /admin/v1/apikeys/:id/rotate is the only endpoint that emits a server-generated plaintext (verified against apikeys_handlers.rs:97-104 for create and :155-178 for rotate). Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Confirmed against code: install_otlp_tracer (crates/aisix-obs/src/otlp.rs:26-58) validates the endpoint and emits a startup log line but defers the real exporter pipeline ("The real exporter wires up in a follow-up PR" per the inline code comment); no install_otlp_metrics function exists in the workspace. The bootstrap-config observability table now carries a Status column marking metrics.otlp.* as reserved (not yet wired) and tracing.otlp.* as partial (validation only). Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against otlp_http_sink.rs:184/:249 (the exporter builds OTLP traces payloads from UsageEvent records — per-request spans, not general metrics or logs). Rewrote the section to: "ships per-request span telemetry — derived from gateway UsageEvent records — to an OTLP/HTTP-compatible backend". Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against crates/aisix-admin/src/lib.rs:68 (/metrics route is hardcoded with no conditional gating). The bootstrap-config observability table now marks metrics.prometheus.enabled and metrics.prometheus.path as reserved (not yet consulted), with a footnote that the Prometheus exporter is currently mounted unconditionally at the hardcoded admin /metrics path. Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against crates/aisix-obs/src/access_log.rs:32-50 (AccessLog::emit() always calls tracing::info! with no config gate) and the unconditional emit_access_log call sites in every proxy handler. The bootstrap-config observability table now marks access_log as reserved (not yet consulted), with a footnote that access logs are emitted unconditionally by every proxy handler today. Pushed in commit 5401ff1.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

docs/configuration/bootstrap-config.md:164

• The tracing endpoint is described as validated at boot, but the implementation only checks that tracing.otlp.enabled=true has a non-empty endpoint; it does not parse or validate the endpoint URL/protocol before returning a handle. Calling this "validated" overstates the current behavior.

| `tracing.otlp.enabled` | enabling this validates the endpoint at boot and emits a startup log line; the OTLP traces pipeline itself is deferred to a future release | `false` | partial (validation only) |
| `tracing.otlp.endpoint` | OTLP/gRPC collector endpoint for traces; validated at boot when `tracing.otlp.enabled` is `true` | none | partial (validation only) |

[janiussyafiq]

Summary

Fixes six new-developer onboarding gaps surfaced by an end-to-end walkthrough of the 7-page onboarding flow (docs/index.md → docs/configuration/bootstrap-config.md) against main at 1a744ee. Three of the fixes (#1, #2, #3) close hard blockers on a clean machine (missing cargo / npm / provider-API-key prerequisites; model_not_found from display_name/model_name ambiguity; an Observability Exporter section whose second sentence is style-guide advice rather than user content). The remaining three (#4, #5, #6) close friction points along the same path (bootstrap-config.md field tables missing a Default column and an observability subsection; two credential-handling operational callouts; a cold-build duration note).

Doc-only diff. No code, schemas, configs, or test fixtures touched.

Closes#325.

Changes

File	Change
docs/quickstart/self-hosted.md	Prerequisites: add Rust 1.93+ with cargo (via rustup) as the leading prerequisite. After cargo run …: add a one-sentence note that the first-time build typically takes 3–5 minutes and that subsequent runs are incremental.
docs/quickstart/first-model-first-key-first-request.md	Prerequisites: replace "A reachable upstream OpenAI-compatible endpoint" with explicit credential-acquisition guidance (supported providers, sign-up link with cost order-of-magnitude, sk-... format hint, placeholder pointer). After the ProviderKey create-time response example: add a :::warning callout that the secret field is plaintext and that GET /admin/v1/provider_keys/:id also returns the plaintext.
docs/quickstart/openai-sdk.md	New ## Prerequisites section placed between the "If you have not done that yet…" intro and the first ## What Changes In The SDK section. Lists a running gateway with provider key / model / API key already created, and Node.js 18+ with npm (the OpenAI SDK floor).
docs/overview/core-concepts.md	Model field-list bullet: inline-annotate display_name as the alias callers send in the API request's model field and model_name as the upstream model ID forwarded to the provider. API Key section: append a sentence after the key_hash description noting the plaintext is unrecoverable post-create and pointing at POST /admin/v1/apikeys/:id/rotate. Observability Exporter section: replace the documentation-author-facing second sentence with a user-facing description of what the resource does (OTLP-compatible export to external backends) and when to configure one.
docs/configuration/bootstrap-config.md	Add a Default column to the field tables on etcd, proxy, admin. Build out the observability section with a new field table covering service_name, log_level, access_log, metrics.prometheus.*, metrics.otlp.*, and tracing.otlp.*, plus a pointer to the dynamic Observability Exporters page. Build out the cache section with a small field table covering backend and redis.

Net diff: 5 files, +58 / -35. Source: git diff --stat.

Test plan

Doc-only diff — no .rs files, schemas, configs, or test fixtures touched. The cargo trio was still run end-to-end as the canonical pre-merge gate.

• cargo fmt --check — PASS (exit 0).
• cargo clippy --workspace --all-targets -- -D warnings — PASS (exit 0; full tail captured below).
• cargo test --workspace — PASS (exit 0; full crate-suite results captured below).
• grep -rln <each affected page> tests/e2e/ for all 5 pages returns empty. pnpm test under tests/e2e/ is not applicable for this diff.

cargo clippy tail

 Checking aisix-proxy v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-proxy)
Checking aisix-admin v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-admin)
Checking aisix-server v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-server)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 40.28s

cargo test summary

33 test-suite-result lines, all 'ok'. Aggregate: 1029 tests passed, 0 failed, 3 ignored across the workspace (unit suites + doc-tests). Sample tail (last 3 named tests + last result line):
test keyword::tests::invalid_regex_is_a_clean_error_not_a_panic ... ok
test usage::tests::full_channel_drop_does_not_panic ... ok
test dispatch::tests::build_v1_url_rejects_path_without_leading_slash - should panic ... ok
test result: ok. <N> passed; 0 failed; <N> ignored; 0 measured; 0 filtered out

Affected pages

• docs/quickstart/self-hosted.md
• docs/quickstart/first-model-first-key-first-request.md
• docs/quickstart/openai-sdk.md
• docs/overview/core-concepts.md
• docs/configuration/bootstrap-config.md

Pre-merge-check verification log

The three pre-merge checks called out in #325 were resolved as follows:

1. Rust / Node minimum versions. Verified Rust against rust-toolchain.toml (channel = "1.93.1") and Cargo.toml (rust-version = "1.93"). The issue body's tentative "Rust 1.79+" floor was bumped to Rust 1.93 or newer in the doc, and a note added that rustup will pull the right channel automatically because rust-toolchain.toml pins it. For Node.js, neither tests/e2e/package.json nor a top-level package.json declares an engines floor, so the doc cites Node.js 18 or newer (the OpenAI SDK's published floor at version 4.x shipped in tests/e2e/package.json).
2. Bootstrap-config Default column. Pulled all default values from crates/aisix-core/src/config.rs (this repo's config crate lives in aisix-core, not in a separate aisix-config crate as the issue body tentatively listed). Values pulled: EtcdConfig::default_prefix → "/aisix", default_dial_timeout / default_request_timeout → 5000ms, ProxyConfig::default_body_limit → 10 * 1024 * 1024, AdminConfig::default → addr "127.0.0.1:0" / admin_keys [] / tls None, ObservabilityConfig::default_service_name → "aisix", default_log_level → "info", default_access_log → true, PrometheusConfig::default → { enabled: true, path: "/metrics" }, OtlpConfig::default → { enabled: false, endpoint: None }, OtlpTracingConfig::default → { enabled: false, endpoint: None, sample_ratio: 1.0 }, CacheConfig::default → { backend: Memory, redis: None }. For fields without an explicit default and with Config::validate enforcement (etcd.endpoints, proxy.addr), the column reads required. For fields whose Default is None, the column reads none.
3. Provider-key GET response shape.crates/aisix-core/src/models/provider_key.rs:39 defines pub secret: String without #[serde(skip_serializing)], and crates/aisix-admin/src/provider_keys_handlers.rs:29-38 (get_provider_key) returns Json<ResourceEntry<ProviderKey>> — so GET /admin/v1/provider_keys/:iddoes include the plaintext secret in the response body, every time. The original draft callout in docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #325 read "subsequent reads via GET do not include it", which was empirically incorrect. The callout in this PR was adjusted to reflect actual behavior: the warning now states that the plaintext is in both the create response and any subsequent GET, and that the same handling applies any time you read the resource.

References

• docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #325 — docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages (this PR closes it)
• docs: replace GET /health references with /livez and /admin/v1/health across configuration, reference, and operations docs #293 — docs: replace GET /health references with /livez and /admin/v1/health (predecessor doc-correction; merged as docs: replace stale GET /health references with /livez and /admin/v1/health #294)
• docs: remove max_budget_usd references from standalone docs (managed-only field) #295 — docs: remove max_budget_usd references from standalone docs (predecessor doc-correction; merged as docs: remove max_budget_usd references from standalone docs (managed-only field) #296)
• docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials #249 — docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials (the docs rebuild whose pages this PR amends)

Summary by CodeRabbit

• Documentation
  • Converted narrative configuration sections into structured tables for bootstrap, observability, and cache settings (including defaults and required/optional status)
  • Clarified core concepts: model display vs upstream identifiers, API key lifecycle/rotation, and observability exporter behavior
  • Added quickstart prerequisites: upstream provider API key, Node.js 18+ for OpenAI SDK, Rust 1.93+ for self-hosted
  • Added warning to treat provider API secrets as sensitive

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 2f8aa0cb-5faa-4a13-a703-ebe2423802be

📥 Commits

Reviewing files that changed from the base of the PR and between 5401ff1 and 1094aac.

📒 Files selected for processing (1)

• docs/configuration/bootstrap-config.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/configuration/bootstrap-config.md

---

📝 Walkthrough

Walkthrough

This PR updates documentation: restructures bootstrap configuration sections into tables with defaults and optional flags, refines core concept fields and observability exporter text, and adds explicit quickstart prerequisites plus an API-key secrecy warning.

Changes

Documentation Clarity Improvements

Layer / File(s)	Summary
Bootstrap configuration tables docs/configuration/bootstrap-config.md	etcd, proxy, admin, observability, and cache "Important fields" are converted from narrative lists into tables that show default values, optional fields (e.g., tls), reserved telemetry keys, and conditional nested blocks (e.g., redis when backend: redis).
Core concept refinements docs/overview/core-concepts.md	Model section now documents display_name, provider, and model_name; API Key section notes plaintext bearer tokens cannot be retrieved after creation and must be rotated; Observability Exporter text focuses on OTLP-compatible telemetry export.
Quickstart prerequisites and security guidance docs/quickstart/openai-sdk.md, docs/quickstart/self-hosted.md, docs/quickstart/first-model-first-key-first-request.md	OpenAI SDK quickstart adds a Prerequisites section (gateway + Node.js 18+); self-hosted quickstart requires Rust 1.93+ and notes first cargo run compile time; first-model guide adds upstream provider API key prerequisite and warns that admin API returns secret in plaintext and it must be treated as sensitive.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This doc-only PR improves new-developer onboarding by clarifying prerequisites, model naming, credential handling, and bootstrap configuration defaults across the quickstart and overview/configuration docs.

Changes:

• Adds Rust/Node/provider-key prerequisite guidance and build-time expectations.
• Clarifies model alias vs upstream model ID and credential visibility.
• Expands bootstrap configuration tables, especially observability and cache fields.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/quickstart/self-hosted.md	Adds Rust/cargo prerequisite and first-build duration note.
docs/quickstart/openai-sdk.md	Adds gateway and Node.js/npm prerequisites.
docs/quickstart/first-model-first-key-first-request.md	Clarifies provider API key prerequisite and plaintext provider-key handling.
docs/overview/core-concepts.md	Clarifies model fields, API-key plaintext handling, and observability exporter description.
docs/configuration/bootstrap-config.md	Adds defaults and expanded observability/cache bootstrap field tables.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[janiussyafiq]

Applied. Rewrote the appended paragraph to reflect actual behavior: the plaintext bearer is chosen (or generated) by the caller and SHA-256-hashed locally before submission, the gateway never sees or returns the plaintext at create time, and POST /admin/v1/apikeys/:id/rotate is the only endpoint that emits a server-generated plaintext (verified against apikeys_handlers.rs:97-104 for create and :155-178 for rotate). Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Confirmed against code: install_otlp_tracer (crates/aisix-obs/src/otlp.rs:26-58) validates the endpoint and emits a startup log line but defers the real exporter pipeline ("The real exporter wires up in a follow-up PR" per the inline code comment); no install_otlp_metrics function exists in the workspace. The bootstrap-config observability table now carries a Status column marking metrics.otlp.* as reserved (not yet wired) and tracing.otlp.* as partial (validation only). Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against otlp_http_sink.rs:184/:249 (the exporter builds OTLP traces payloads from UsageEvent records — per-request spans, not general metrics or logs). Rewrote the section to: "ships per-request span telemetry — derived from gateway UsageEvent records — to an OTLP/HTTP-compatible backend". Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against crates/aisix-admin/src/lib.rs:68 (/metrics route is hardcoded with no conditional gating). The bootstrap-config observability table now marks metrics.prometheus.enabled and metrics.prometheus.path as reserved (not yet consulted), with a footnote that the Prometheus exporter is currently mounted unconditionally at the hardcoded admin /metrics path. Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against crates/aisix-obs/src/access_log.rs:32-50 (AccessLog::emit() always calls tracing::info! with no config gate) and the unconditional emit_access_log call sites in every proxy handler. The bootstrap-config observability table now marks access_log as reserved (not yet consulted), with a footnote that access logs are emitted unconditionally by every proxy handler today. Pushed in commit 5401ff1.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

docs/configuration/bootstrap-config.md:164

• The tracing endpoint is described as validated at boot, but the implementation only checks that tracing.otlp.enabled=true has a non-empty endpoint; it does not parse or validate the endpoint URL/protocol before returning a handle. Calling this "validated" overstates the current behavior.

| `tracing.otlp.enabled` | enabling this validates the endpoint at boot and emits a startup log line; the OTLP traces pipeline itself is deferred to a future release | `false` | partial (validation only) |
| `tracing.otlp.endpoint` | OTLP/gRPC collector endpoint for traces; validated at boot when `tracing.otlp.enabled` is `true` | none | partial (validation only) |

[janiussyafiq]

Summary

Fixes six new-developer onboarding gaps surfaced by an end-to-end walkthrough of the 7-page onboarding flow (docs/index.md → docs/configuration/bootstrap-config.md) against main at 1a744ee. Three of the fixes (#1, #2, #3) close hard blockers on a clean machine (missing cargo / npm / provider-API-key prerequisites; model_not_found from display_name/model_name ambiguity; an Observability Exporter section whose second sentence is style-guide advice rather than user content). The remaining three (#4, #5, #6) close friction points along the same path (bootstrap-config.md field tables missing a Default column and an observability subsection; two credential-handling operational callouts; a cold-build duration note).

Doc-only diff. No code, schemas, configs, or test fixtures touched.

Closes#325.

Changes

File	Change
docs/quickstart/self-hosted.md	Prerequisites: add Rust 1.93+ with cargo (via rustup) as the leading prerequisite. After cargo run …: add a one-sentence note that the first-time build typically takes 3–5 minutes and that subsequent runs are incremental.
docs/quickstart/first-model-first-key-first-request.md	Prerequisites: replace "A reachable upstream OpenAI-compatible endpoint" with explicit credential-acquisition guidance (supported providers, sign-up link with cost order-of-magnitude, sk-... format hint, placeholder pointer). After the ProviderKey create-time response example: add a :::warning callout that the secret field is plaintext and that GET /admin/v1/provider_keys/:id also returns the plaintext.
docs/quickstart/openai-sdk.md	New ## Prerequisites section placed between the "If you have not done that yet…" intro and the first ## What Changes In The SDK section. Lists a running gateway with provider key / model / API key already created, and Node.js 18+ with npm (the OpenAI SDK floor).
docs/overview/core-concepts.md	Model field-list bullet: inline-annotate display_name as the alias callers send in the API request's model field and model_name as the upstream model ID forwarded to the provider. API Key section: append a sentence after the key_hash description noting the plaintext is unrecoverable post-create and pointing at POST /admin/v1/apikeys/:id/rotate. Observability Exporter section: replace the documentation-author-facing second sentence with a user-facing description of what the resource does (OTLP-compatible export to external backends) and when to configure one.
docs/configuration/bootstrap-config.md	Add a Default column to the field tables on etcd, proxy, admin. Build out the observability section with a new field table covering service_name, log_level, access_log, metrics.prometheus.*, metrics.otlp.*, and tracing.otlp.*, plus a pointer to the dynamic Observability Exporters page. Build out the cache section with a small field table covering backend and redis.

Net diff: 5 files, +58 / -35. Source: git diff --stat.

Test plan

Doc-only diff — no .rs files, schemas, configs, or test fixtures touched. The cargo trio was still run end-to-end as the canonical pre-merge gate.

• cargo fmt --check — PASS (exit 0).
• cargo clippy --workspace --all-targets -- -D warnings — PASS (exit 0; full tail captured below).
• cargo test --workspace — PASS (exit 0; full crate-suite results captured below).
• grep -rln <each affected page> tests/e2e/ for all 5 pages returns empty. pnpm test under tests/e2e/ is not applicable for this diff.

cargo clippy tail

 Checking aisix-proxy v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-proxy)
Checking aisix-admin v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-admin)
Checking aisix-server v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-server)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 40.28s

cargo test summary

33 test-suite-result lines, all 'ok'. Aggregate: 1029 tests passed, 0 failed, 3 ignored across the workspace (unit suites + doc-tests). Sample tail (last 3 named tests + last result line):
test keyword::tests::invalid_regex_is_a_clean_error_not_a_panic ... ok
test usage::tests::full_channel_drop_does_not_panic ... ok
test dispatch::tests::build_v1_url_rejects_path_without_leading_slash - should panic ... ok
test result: ok. <N> passed; 0 failed; <N> ignored; 0 measured; 0 filtered out

Affected pages

• docs/quickstart/self-hosted.md
• docs/quickstart/first-model-first-key-first-request.md
• docs/quickstart/openai-sdk.md
• docs/overview/core-concepts.md
• docs/configuration/bootstrap-config.md

Pre-merge-check verification log

The three pre-merge checks called out in #325 were resolved as follows:

1. Rust / Node minimum versions. Verified Rust against rust-toolchain.toml (channel = "1.93.1") and Cargo.toml (rust-version = "1.93"). The issue body's tentative "Rust 1.79+" floor was bumped to Rust 1.93 or newer in the doc, and a note added that rustup will pull the right channel automatically because rust-toolchain.toml pins it. For Node.js, neither tests/e2e/package.json nor a top-level package.json declares an engines floor, so the doc cites Node.js 18 or newer (the OpenAI SDK's published floor at version 4.x shipped in tests/e2e/package.json).
2. Bootstrap-config Default column. Pulled all default values from crates/aisix-core/src/config.rs (this repo's config crate lives in aisix-core, not in a separate aisix-config crate as the issue body tentatively listed). Values pulled: EtcdConfig::default_prefix → "/aisix", default_dial_timeout / default_request_timeout → 5000ms, ProxyConfig::default_body_limit → 10 * 1024 * 1024, AdminConfig::default → addr "127.0.0.1:0" / admin_keys [] / tls None, ObservabilityConfig::default_service_name → "aisix", default_log_level → "info", default_access_log → true, PrometheusConfig::default → { enabled: true, path: "/metrics" }, OtlpConfig::default → { enabled: false, endpoint: None }, OtlpTracingConfig::default → { enabled: false, endpoint: None, sample_ratio: 1.0 }, CacheConfig::default → { backend: Memory, redis: None }. For fields without an explicit default and with Config::validate enforcement (etcd.endpoints, proxy.addr), the column reads required. For fields whose Default is None, the column reads none.
3. Provider-key GET response shape.crates/aisix-core/src/models/provider_key.rs:39 defines pub secret: String without #[serde(skip_serializing)], and crates/aisix-admin/src/provider_keys_handlers.rs:29-38 (get_provider_key) returns Json<ResourceEntry<ProviderKey>> — so GET /admin/v1/provider_keys/:iddoes include the plaintext secret in the response body, every time. The original draft callout in docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #325 read "subsequent reads via GET do not include it", which was empirically incorrect. The callout in this PR was adjusted to reflect actual behavior: the warning now states that the plaintext is in both the create response and any subsequent GET, and that the same handling applies any time you read the resource.

References

• docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #325 — docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages (this PR closes it)
• docs: replace GET /health references with /livez and /admin/v1/health across configuration, reference, and operations docs #293 — docs: replace GET /health references with /livez and /admin/v1/health (predecessor doc-correction; merged as docs: replace stale GET /health references with /livez and /admin/v1/health #294)
• docs: remove max_budget_usd references from standalone docs (managed-only field) #295 — docs: remove max_budget_usd references from standalone docs (predecessor doc-correction; merged as docs: remove max_budget_usd references from standalone docs (managed-only field) #296)
• docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials #249 — docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials (the docs rebuild whose pages this PR amends)

Summary by CodeRabbit

• Documentation
  • Converted narrative configuration sections into structured tables for bootstrap, observability, and cache settings (including defaults and required/optional status)
  • Clarified core concepts: model display vs upstream identifiers, API key lifecycle/rotation, and observability exporter behavior
  • Added quickstart prerequisites: upstream provider API key, Node.js 18+ for OpenAI SDK, Rust 1.93+ for self-hosted
  • Added warning to treat provider API secrets as sensitive

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 2f8aa0cb-5faa-4a13-a703-ebe2423802be

📥 Commits

Reviewing files that changed from the base of the PR and between 5401ff1 and 1094aac.

📒 Files selected for processing (1)

• docs/configuration/bootstrap-config.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/configuration/bootstrap-config.md

---

📝 Walkthrough

Walkthrough

This PR updates documentation: restructures bootstrap configuration sections into tables with defaults and optional flags, refines core concept fields and observability exporter text, and adds explicit quickstart prerequisites plus an API-key secrecy warning.

Changes

Documentation Clarity Improvements

Layer / File(s)	Summary
Bootstrap configuration tables docs/configuration/bootstrap-config.md	etcd, proxy, admin, observability, and cache "Important fields" are converted from narrative lists into tables that show default values, optional fields (e.g., tls), reserved telemetry keys, and conditional nested blocks (e.g., redis when backend: redis).
Core concept refinements docs/overview/core-concepts.md	Model section now documents display_name, provider, and model_name; API Key section notes plaintext bearer tokens cannot be retrieved after creation and must be rotated; Observability Exporter text focuses on OTLP-compatible telemetry export.
Quickstart prerequisites and security guidance docs/quickstart/openai-sdk.md, docs/quickstart/self-hosted.md, docs/quickstart/first-model-first-key-first-request.md	OpenAI SDK quickstart adds a Prerequisites section (gateway + Node.js 18+); self-hosted quickstart requires Rust 1.93+ and notes first cargo run compile time; first-model guide adds upstream provider API key prerequisite and warns that admin API returns secret in plaintext and it must be treated as sensitive.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This doc-only PR improves new-developer onboarding by clarifying prerequisites, model naming, credential handling, and bootstrap configuration defaults across the quickstart and overview/configuration docs.

Changes:

• Adds Rust/Node/provider-key prerequisite guidance and build-time expectations.
• Clarifies model alias vs upstream model ID and credential visibility.
• Expands bootstrap configuration tables, especially observability and cache fields.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/quickstart/self-hosted.md	Adds Rust/cargo prerequisite and first-build duration note.
docs/quickstart/openai-sdk.md	Adds gateway and Node.js/npm prerequisites.
docs/quickstart/first-model-first-key-first-request.md	Clarifies provider API key prerequisite and plaintext provider-key handling.
docs/overview/core-concepts.md	Clarifies model fields, API-key plaintext handling, and observability exporter description.
docs/configuration/bootstrap-config.md	Adds defaults and expanded observability/cache bootstrap field tables.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[janiussyafiq]

Applied. Rewrote the appended paragraph to reflect actual behavior: the plaintext bearer is chosen (or generated) by the caller and SHA-256-hashed locally before submission, the gateway never sees or returns the plaintext at create time, and POST /admin/v1/apikeys/:id/rotate is the only endpoint that emits a server-generated plaintext (verified against apikeys_handlers.rs:97-104 for create and :155-178 for rotate). Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Confirmed against code: install_otlp_tracer (crates/aisix-obs/src/otlp.rs:26-58) validates the endpoint and emits a startup log line but defers the real exporter pipeline ("The real exporter wires up in a follow-up PR" per the inline code comment); no install_otlp_metrics function exists in the workspace. The bootstrap-config observability table now carries a Status column marking metrics.otlp.* as reserved (not yet wired) and tracing.otlp.* as partial (validation only). Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against otlp_http_sink.rs:184/:249 (the exporter builds OTLP traces payloads from UsageEvent records — per-request spans, not general metrics or logs). Rewrote the section to: "ships per-request span telemetry — derived from gateway UsageEvent records — to an OTLP/HTTP-compatible backend". Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against crates/aisix-admin/src/lib.rs:68 (/metrics route is hardcoded with no conditional gating). The bootstrap-config observability table now marks metrics.prometheus.enabled and metrics.prometheus.path as reserved (not yet consulted), with a footnote that the Prometheus exporter is currently mounted unconditionally at the hardcoded admin /metrics path. Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against crates/aisix-obs/src/access_log.rs:32-50 (AccessLog::emit() always calls tracing::info! with no config gate) and the unconditional emit_access_log call sites in every proxy handler. The bootstrap-config observability table now marks access_log as reserved (not yet consulted), with a footnote that access logs are emitted unconditionally by every proxy handler today. Pushed in commit 5401ff1.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

docs/configuration/bootstrap-config.md:164

• The tracing endpoint is described as validated at boot, but the implementation only checks that tracing.otlp.enabled=true has a non-empty endpoint; it does not parse or validate the endpoint URL/protocol before returning a handle. Calling this "validated" overstates the current behavior.

| `tracing.otlp.enabled` | enabling this validates the endpoint at boot and emits a startup log line; the OTLP traces pipeline itself is deferred to a future release | `false` | partial (validation only) |
| `tracing.otlp.endpoint` | OTLP/gRPC collector endpoint for traces; validated at boot when `tracing.otlp.enabled` is `true` | none | partial (validation only) |

[janiussyafiq]

Summary

Fixes six new-developer onboarding gaps surfaced by an end-to-end walkthrough of the 7-page onboarding flow (docs/index.md → docs/configuration/bootstrap-config.md) against main at 1a744ee. Three of the fixes (#1, #2, #3) close hard blockers on a clean machine (missing cargo / npm / provider-API-key prerequisites; model_not_found from display_name/model_name ambiguity; an Observability Exporter section whose second sentence is style-guide advice rather than user content). The remaining three (#4, #5, #6) close friction points along the same path (bootstrap-config.md field tables missing a Default column and an observability subsection; two credential-handling operational callouts; a cold-build duration note).

Doc-only diff. No code, schemas, configs, or test fixtures touched.

Closes#325.

Changes

File	Change
docs/quickstart/self-hosted.md	Prerequisites: add Rust 1.93+ with cargo (via rustup) as the leading prerequisite. After cargo run …: add a one-sentence note that the first-time build typically takes 3–5 minutes and that subsequent runs are incremental.
docs/quickstart/first-model-first-key-first-request.md	Prerequisites: replace "A reachable upstream OpenAI-compatible endpoint" with explicit credential-acquisition guidance (supported providers, sign-up link with cost order-of-magnitude, sk-... format hint, placeholder pointer). After the ProviderKey create-time response example: add a :::warning callout that the secret field is plaintext and that GET /admin/v1/provider_keys/:id also returns the plaintext.
docs/quickstart/openai-sdk.md	New ## Prerequisites section placed between the "If you have not done that yet…" intro and the first ## What Changes In The SDK section. Lists a running gateway with provider key / model / API key already created, and Node.js 18+ with npm (the OpenAI SDK floor).
docs/overview/core-concepts.md	Model field-list bullet: inline-annotate display_name as the alias callers send in the API request's model field and model_name as the upstream model ID forwarded to the provider. API Key section: append a sentence after the key_hash description noting the plaintext is unrecoverable post-create and pointing at POST /admin/v1/apikeys/:id/rotate. Observability Exporter section: replace the documentation-author-facing second sentence with a user-facing description of what the resource does (OTLP-compatible export to external backends) and when to configure one.
docs/configuration/bootstrap-config.md	Add a Default column to the field tables on etcd, proxy, admin. Build out the observability section with a new field table covering service_name, log_level, access_log, metrics.prometheus.*, metrics.otlp.*, and tracing.otlp.*, plus a pointer to the dynamic Observability Exporters page. Build out the cache section with a small field table covering backend and redis.

Net diff: 5 files, +58 / -35. Source: git diff --stat.

Test plan

Doc-only diff — no .rs files, schemas, configs, or test fixtures touched. The cargo trio was still run end-to-end as the canonical pre-merge gate.

• cargo fmt --check — PASS (exit 0).
• cargo clippy --workspace --all-targets -- -D warnings — PASS (exit 0; full tail captured below).
• cargo test --workspace — PASS (exit 0; full crate-suite results captured below).
• grep -rln <each affected page> tests/e2e/ for all 5 pages returns empty. pnpm test under tests/e2e/ is not applicable for this diff.

cargo clippy tail

 Checking aisix-proxy v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-proxy)
Checking aisix-admin v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-admin)
Checking aisix-server v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-server)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 40.28s

cargo test summary

33 test-suite-result lines, all 'ok'. Aggregate: 1029 tests passed, 0 failed, 3 ignored across the workspace (unit suites + doc-tests). Sample tail (last 3 named tests + last result line):
test keyword::tests::invalid_regex_is_a_clean_error_not_a_panic ... ok
test usage::tests::full_channel_drop_does_not_panic ... ok
test dispatch::tests::build_v1_url_rejects_path_without_leading_slash - should panic ... ok
test result: ok. <N> passed; 0 failed; <N> ignored; 0 measured; 0 filtered out

Affected pages

• docs/quickstart/self-hosted.md
• docs/quickstart/first-model-first-key-first-request.md
• docs/quickstart/openai-sdk.md
• docs/overview/core-concepts.md
• docs/configuration/bootstrap-config.md

Pre-merge-check verification log

The three pre-merge checks called out in #325 were resolved as follows:

1. Rust / Node minimum versions. Verified Rust against rust-toolchain.toml (channel = "1.93.1") and Cargo.toml (rust-version = "1.93"). The issue body's tentative "Rust 1.79+" floor was bumped to Rust 1.93 or newer in the doc, and a note added that rustup will pull the right channel automatically because rust-toolchain.toml pins it. For Node.js, neither tests/e2e/package.json nor a top-level package.json declares an engines floor, so the doc cites Node.js 18 or newer (the OpenAI SDK's published floor at version 4.x shipped in tests/e2e/package.json).
2. Bootstrap-config Default column. Pulled all default values from crates/aisix-core/src/config.rs (this repo's config crate lives in aisix-core, not in a separate aisix-config crate as the issue body tentatively listed). Values pulled: EtcdConfig::default_prefix → "/aisix", default_dial_timeout / default_request_timeout → 5000ms, ProxyConfig::default_body_limit → 10 * 1024 * 1024, AdminConfig::default → addr "127.0.0.1:0" / admin_keys [] / tls None, ObservabilityConfig::default_service_name → "aisix", default_log_level → "info", default_access_log → true, PrometheusConfig::default → { enabled: true, path: "/metrics" }, OtlpConfig::default → { enabled: false, endpoint: None }, OtlpTracingConfig::default → { enabled: false, endpoint: None, sample_ratio: 1.0 }, CacheConfig::default → { backend: Memory, redis: None }. For fields without an explicit default and with Config::validate enforcement (etcd.endpoints, proxy.addr), the column reads required. For fields whose Default is None, the column reads none.
3. Provider-key GET response shape.crates/aisix-core/src/models/provider_key.rs:39 defines pub secret: String without #[serde(skip_serializing)], and crates/aisix-admin/src/provider_keys_handlers.rs:29-38 (get_provider_key) returns Json<ResourceEntry<ProviderKey>> — so GET /admin/v1/provider_keys/:iddoes include the plaintext secret in the response body, every time. The original draft callout in docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #325 read "subsequent reads via GET do not include it", which was empirically incorrect. The callout in this PR was adjusted to reflect actual behavior: the warning now states that the plaintext is in both the create response and any subsequent GET, and that the same handling applies any time you read the resource.

References

• docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #325 — docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages (this PR closes it)
• docs: replace GET /health references with /livez and /admin/v1/health across configuration, reference, and operations docs #293 — docs: replace GET /health references with /livez and /admin/v1/health (predecessor doc-correction; merged as docs: replace stale GET /health references with /livez and /admin/v1/health #294)
• docs: remove max_budget_usd references from standalone docs (managed-only field) #295 — docs: remove max_budget_usd references from standalone docs (predecessor doc-correction; merged as docs: remove max_budget_usd references from standalone docs (managed-only field) #296)
• docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials #249 — docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials (the docs rebuild whose pages this PR amends)

Summary by CodeRabbit

• Documentation
  • Converted narrative configuration sections into structured tables for bootstrap, observability, and cache settings (including defaults and required/optional status)
  • Clarified core concepts: model display vs upstream identifiers, API key lifecycle/rotation, and observability exporter behavior
  • Added quickstart prerequisites: upstream provider API key, Node.js 18+ for OpenAI SDK, Rust 1.93+ for self-hosted
  • Added warning to treat provider API secrets as sensitive

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 2f8aa0cb-5faa-4a13-a703-ebe2423802be

📥 Commits

Reviewing files that changed from the base of the PR and between 5401ff1 and 1094aac.

📒 Files selected for processing (1)

• docs/configuration/bootstrap-config.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/configuration/bootstrap-config.md

---

📝 Walkthrough

Walkthrough

This PR updates documentation: restructures bootstrap configuration sections into tables with defaults and optional flags, refines core concept fields and observability exporter text, and adds explicit quickstart prerequisites plus an API-key secrecy warning.

Changes

Documentation Clarity Improvements

Layer / File(s)	Summary
Bootstrap configuration tables docs/configuration/bootstrap-config.md	etcd, proxy, admin, observability, and cache "Important fields" are converted from narrative lists into tables that show default values, optional fields (e.g., tls), reserved telemetry keys, and conditional nested blocks (e.g., redis when backend: redis).
Core concept refinements docs/overview/core-concepts.md	Model section now documents display_name, provider, and model_name; API Key section notes plaintext bearer tokens cannot be retrieved after creation and must be rotated; Observability Exporter text focuses on OTLP-compatible telemetry export.
Quickstart prerequisites and security guidance docs/quickstart/openai-sdk.md, docs/quickstart/self-hosted.md, docs/quickstart/first-model-first-key-first-request.md	OpenAI SDK quickstart adds a Prerequisites section (gateway + Node.js 18+); self-hosted quickstart requires Rust 1.93+ and notes first cargo run compile time; first-model guide adds upstream provider API key prerequisite and warns that admin API returns secret in plaintext and it must be treated as sensitive.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This doc-only PR improves new-developer onboarding by clarifying prerequisites, model naming, credential handling, and bootstrap configuration defaults across the quickstart and overview/configuration docs.

Changes:

• Adds Rust/Node/provider-key prerequisite guidance and build-time expectations.
• Clarifies model alias vs upstream model ID and credential visibility.
• Expands bootstrap configuration tables, especially observability and cache fields.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/quickstart/self-hosted.md	Adds Rust/cargo prerequisite and first-build duration note.
docs/quickstart/openai-sdk.md	Adds gateway and Node.js/npm prerequisites.
docs/quickstart/first-model-first-key-first-request.md	Clarifies provider API key prerequisite and plaintext provider-key handling.
docs/overview/core-concepts.md	Clarifies model fields, API-key plaintext handling, and observability exporter description.
docs/configuration/bootstrap-config.md	Adds defaults and expanded observability/cache bootstrap field tables.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[janiussyafiq]

Applied. Rewrote the appended paragraph to reflect actual behavior: the plaintext bearer is chosen (or generated) by the caller and SHA-256-hashed locally before submission, the gateway never sees or returns the plaintext at create time, and POST /admin/v1/apikeys/:id/rotate is the only endpoint that emits a server-generated plaintext (verified against apikeys_handlers.rs:97-104 for create and :155-178 for rotate). Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Confirmed against code: install_otlp_tracer (crates/aisix-obs/src/otlp.rs:26-58) validates the endpoint and emits a startup log line but defers the real exporter pipeline ("The real exporter wires up in a follow-up PR" per the inline code comment); no install_otlp_metrics function exists in the workspace. The bootstrap-config observability table now carries a Status column marking metrics.otlp.* as reserved (not yet wired) and tracing.otlp.* as partial (validation only). Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against otlp_http_sink.rs:184/:249 (the exporter builds OTLP traces payloads from UsageEvent records — per-request spans, not general metrics or logs). Rewrote the section to: "ships per-request span telemetry — derived from gateway UsageEvent records — to an OTLP/HTTP-compatible backend". Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against crates/aisix-admin/src/lib.rs:68 (/metrics route is hardcoded with no conditional gating). The bootstrap-config observability table now marks metrics.prometheus.enabled and metrics.prometheus.path as reserved (not yet consulted), with a footnote that the Prometheus exporter is currently mounted unconditionally at the hardcoded admin /metrics path. Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against crates/aisix-obs/src/access_log.rs:32-50 (AccessLog::emit() always calls tracing::info! with no config gate) and the unconditional emit_access_log call sites in every proxy handler. The bootstrap-config observability table now marks access_log as reserved (not yet consulted), with a footnote that access logs are emitted unconditionally by every proxy handler today. Pushed in commit 5401ff1.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

docs/configuration/bootstrap-config.md:164

• The tracing endpoint is described as validated at boot, but the implementation only checks that tracing.otlp.enabled=true has a non-empty endpoint; it does not parse or validate the endpoint URL/protocol before returning a handle. Calling this "validated" overstates the current behavior.

| `tracing.otlp.enabled` | enabling this validates the endpoint at boot and emits a startup log line; the OTLP traces pipeline itself is deferred to a future release | `false` | partial (validation only) |
| `tracing.otlp.endpoint` | OTLP/gRPC collector endpoint for traces; validated at boot when `tracing.otlp.enabled` is `true` | none | partial (validation only) |

[janiussyafiq]

Summary

Fixes six new-developer onboarding gaps surfaced by an end-to-end walkthrough of the 7-page onboarding flow (docs/index.md → docs/configuration/bootstrap-config.md) against main at 1a744ee. Three of the fixes (#1, #2, #3) close hard blockers on a clean machine (missing cargo / npm / provider-API-key prerequisites; model_not_found from display_name/model_name ambiguity; an Observability Exporter section whose second sentence is style-guide advice rather than user content). The remaining three (#4, #5, #6) close friction points along the same path (bootstrap-config.md field tables missing a Default column and an observability subsection; two credential-handling operational callouts; a cold-build duration note).

Doc-only diff. No code, schemas, configs, or test fixtures touched.

Closes#325.

Changes

File	Change
docs/quickstart/self-hosted.md	Prerequisites: add Rust 1.93+ with cargo (via rustup) as the leading prerequisite. After cargo run …: add a one-sentence note that the first-time build typically takes 3–5 minutes and that subsequent runs are incremental.
docs/quickstart/first-model-first-key-first-request.md	Prerequisites: replace "A reachable upstream OpenAI-compatible endpoint" with explicit credential-acquisition guidance (supported providers, sign-up link with cost order-of-magnitude, sk-... format hint, placeholder pointer). After the ProviderKey create-time response example: add a :::warning callout that the secret field is plaintext and that GET /admin/v1/provider_keys/:id also returns the plaintext.
docs/quickstart/openai-sdk.md	New ## Prerequisites section placed between the "If you have not done that yet…" intro and the first ## What Changes In The SDK section. Lists a running gateway with provider key / model / API key already created, and Node.js 18+ with npm (the OpenAI SDK floor).
docs/overview/core-concepts.md	Model field-list bullet: inline-annotate display_name as the alias callers send in the API request's model field and model_name as the upstream model ID forwarded to the provider. API Key section: append a sentence after the key_hash description noting the plaintext is unrecoverable post-create and pointing at POST /admin/v1/apikeys/:id/rotate. Observability Exporter section: replace the documentation-author-facing second sentence with a user-facing description of what the resource does (OTLP-compatible export to external backends) and when to configure one.
docs/configuration/bootstrap-config.md	Add a Default column to the field tables on etcd, proxy, admin. Build out the observability section with a new field table covering service_name, log_level, access_log, metrics.prometheus.*, metrics.otlp.*, and tracing.otlp.*, plus a pointer to the dynamic Observability Exporters page. Build out the cache section with a small field table covering backend and redis.

Net diff: 5 files, +58 / -35. Source: git diff --stat.

Test plan

Doc-only diff — no .rs files, schemas, configs, or test fixtures touched. The cargo trio was still run end-to-end as the canonical pre-merge gate.

• cargo fmt --check — PASS (exit 0).
• cargo clippy --workspace --all-targets -- -D warnings — PASS (exit 0; full tail captured below).
• cargo test --workspace — PASS (exit 0; full crate-suite results captured below).
• grep -rln <each affected page> tests/e2e/ for all 5 pages returns empty. pnpm test under tests/e2e/ is not applicable for this diff.

cargo clippy tail

 Checking aisix-proxy v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-proxy)
Checking aisix-admin v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-admin)
Checking aisix-server v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-server)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 40.28s

cargo test summary

33 test-suite-result lines, all 'ok'. Aggregate: 1029 tests passed, 0 failed, 3 ignored across the workspace (unit suites + doc-tests). Sample tail (last 3 named tests + last result line):
test keyword::tests::invalid_regex_is_a_clean_error_not_a_panic ... ok
test usage::tests::full_channel_drop_does_not_panic ... ok
test dispatch::tests::build_v1_url_rejects_path_without_leading_slash - should panic ... ok
test result: ok. <N> passed; 0 failed; <N> ignored; 0 measured; 0 filtered out

Affected pages

• docs/quickstart/self-hosted.md
• docs/quickstart/first-model-first-key-first-request.md
• docs/quickstart/openai-sdk.md
• docs/overview/core-concepts.md
• docs/configuration/bootstrap-config.md

Pre-merge-check verification log

The three pre-merge checks called out in #325 were resolved as follows:

1. Rust / Node minimum versions. Verified Rust against rust-toolchain.toml (channel = "1.93.1") and Cargo.toml (rust-version = "1.93"). The issue body's tentative "Rust 1.79+" floor was bumped to Rust 1.93 or newer in the doc, and a note added that rustup will pull the right channel automatically because rust-toolchain.toml pins it. For Node.js, neither tests/e2e/package.json nor a top-level package.json declares an engines floor, so the doc cites Node.js 18 or newer (the OpenAI SDK's published floor at version 4.x shipped in tests/e2e/package.json).
2. Bootstrap-config Default column. Pulled all default values from crates/aisix-core/src/config.rs (this repo's config crate lives in aisix-core, not in a separate aisix-config crate as the issue body tentatively listed). Values pulled: EtcdConfig::default_prefix → "/aisix", default_dial_timeout / default_request_timeout → 5000ms, ProxyConfig::default_body_limit → 10 * 1024 * 1024, AdminConfig::default → addr "127.0.0.1:0" / admin_keys [] / tls None, ObservabilityConfig::default_service_name → "aisix", default_log_level → "info", default_access_log → true, PrometheusConfig::default → { enabled: true, path: "/metrics" }, OtlpConfig::default → { enabled: false, endpoint: None }, OtlpTracingConfig::default → { enabled: false, endpoint: None, sample_ratio: 1.0 }, CacheConfig::default → { backend: Memory, redis: None }. For fields without an explicit default and with Config::validate enforcement (etcd.endpoints, proxy.addr), the column reads required. For fields whose Default is None, the column reads none.
3. Provider-key GET response shape.crates/aisix-core/src/models/provider_key.rs:39 defines pub secret: String without #[serde(skip_serializing)], and crates/aisix-admin/src/provider_keys_handlers.rs:29-38 (get_provider_key) returns Json<ResourceEntry<ProviderKey>> — so GET /admin/v1/provider_keys/:iddoes include the plaintext secret in the response body, every time. The original draft callout in docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #325 read "subsequent reads via GET do not include it", which was empirically incorrect. The callout in this PR was adjusted to reflect actual behavior: the warning now states that the plaintext is in both the create response and any subsequent GET, and that the same handling applies any time you read the resource.

References

• docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #325 — docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages (this PR closes it)
• docs: replace GET /health references with /livez and /admin/v1/health across configuration, reference, and operations docs #293 — docs: replace GET /health references with /livez and /admin/v1/health (predecessor doc-correction; merged as docs: replace stale GET /health references with /livez and /admin/v1/health #294)
• docs: remove max_budget_usd references from standalone docs (managed-only field) #295 — docs: remove max_budget_usd references from standalone docs (predecessor doc-correction; merged as docs: remove max_budget_usd references from standalone docs (managed-only field) #296)
• docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials #249 — docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials (the docs rebuild whose pages this PR amends)

Summary by CodeRabbit

• Documentation
  • Converted narrative configuration sections into structured tables for bootstrap, observability, and cache settings (including defaults and required/optional status)
  • Clarified core concepts: model display vs upstream identifiers, API key lifecycle/rotation, and observability exporter behavior
  • Added quickstart prerequisites: upstream provider API key, Node.js 18+ for OpenAI SDK, Rust 1.93+ for self-hosted
  • Added warning to treat provider API secrets as sensitive

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 2f8aa0cb-5faa-4a13-a703-ebe2423802be

📥 Commits

Reviewing files that changed from the base of the PR and between 5401ff1 and 1094aac.

📒 Files selected for processing (1)

• docs/configuration/bootstrap-config.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/configuration/bootstrap-config.md

---

📝 Walkthrough

Walkthrough

This PR updates documentation: restructures bootstrap configuration sections into tables with defaults and optional flags, refines core concept fields and observability exporter text, and adds explicit quickstart prerequisites plus an API-key secrecy warning.

Changes

Documentation Clarity Improvements

Layer / File(s)	Summary
Bootstrap configuration tables docs/configuration/bootstrap-config.md	etcd, proxy, admin, observability, and cache "Important fields" are converted from narrative lists into tables that show default values, optional fields (e.g., tls), reserved telemetry keys, and conditional nested blocks (e.g., redis when backend: redis).
Core concept refinements docs/overview/core-concepts.md	Model section now documents display_name, provider, and model_name; API Key section notes plaintext bearer tokens cannot be retrieved after creation and must be rotated; Observability Exporter text focuses on OTLP-compatible telemetry export.
Quickstart prerequisites and security guidance docs/quickstart/openai-sdk.md, docs/quickstart/self-hosted.md, docs/quickstart/first-model-first-key-first-request.md	OpenAI SDK quickstart adds a Prerequisites section (gateway + Node.js 18+); self-hosted quickstart requires Rust 1.93+ and notes first cargo run compile time; first-model guide adds upstream provider API key prerequisite and warns that admin API returns secret in plaintext and it must be treated as sensitive.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This doc-only PR improves new-developer onboarding by clarifying prerequisites, model naming, credential handling, and bootstrap configuration defaults across the quickstart and overview/configuration docs.

Changes:

• Adds Rust/Node/provider-key prerequisite guidance and build-time expectations.
• Clarifies model alias vs upstream model ID and credential visibility.
• Expands bootstrap configuration tables, especially observability and cache fields.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/quickstart/self-hosted.md	Adds Rust/cargo prerequisite and first-build duration note.
docs/quickstart/openai-sdk.md	Adds gateway and Node.js/npm prerequisites.
docs/quickstart/first-model-first-key-first-request.md	Clarifies provider API key prerequisite and plaintext provider-key handling.
docs/overview/core-concepts.md	Clarifies model fields, API-key plaintext handling, and observability exporter description.
docs/configuration/bootstrap-config.md	Adds defaults and expanded observability/cache bootstrap field tables.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[janiussyafiq]

Applied. Rewrote the appended paragraph to reflect actual behavior: the plaintext bearer is chosen (or generated) by the caller and SHA-256-hashed locally before submission, the gateway never sees or returns the plaintext at create time, and POST /admin/v1/apikeys/:id/rotate is the only endpoint that emits a server-generated plaintext (verified against apikeys_handlers.rs:97-104 for create and :155-178 for rotate). Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Confirmed against code: install_otlp_tracer (crates/aisix-obs/src/otlp.rs:26-58) validates the endpoint and emits a startup log line but defers the real exporter pipeline ("The real exporter wires up in a follow-up PR" per the inline code comment); no install_otlp_metrics function exists in the workspace. The bootstrap-config observability table now carries a Status column marking metrics.otlp.* as reserved (not yet wired) and tracing.otlp.* as partial (validation only). Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against otlp_http_sink.rs:184/:249 (the exporter builds OTLP traces payloads from UsageEvent records — per-request spans, not general metrics or logs). Rewrote the section to: "ships per-request span telemetry — derived from gateway UsageEvent records — to an OTLP/HTTP-compatible backend". Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against crates/aisix-admin/src/lib.rs:68 (/metrics route is hardcoded with no conditional gating). The bootstrap-config observability table now marks metrics.prometheus.enabled and metrics.prometheus.path as reserved (not yet consulted), with a footnote that the Prometheus exporter is currently mounted unconditionally at the hardcoded admin /metrics path. Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against crates/aisix-obs/src/access_log.rs:32-50 (AccessLog::emit() always calls tracing::info! with no config gate) and the unconditional emit_access_log call sites in every proxy handler. The bootstrap-config observability table now marks access_log as reserved (not yet consulted), with a footnote that access logs are emitted unconditionally by every proxy handler today. Pushed in commit 5401ff1.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

docs/configuration/bootstrap-config.md:164

• The tracing endpoint is described as validated at boot, but the implementation only checks that tracing.otlp.enabled=true has a non-empty endpoint; it does not parse or validate the endpoint URL/protocol before returning a handle. Calling this "validated" overstates the current behavior.

| `tracing.otlp.enabled` | enabling this validates the endpoint at boot and emits a startup log line; the OTLP traces pipeline itself is deferred to a future release | `false` | partial (validation only) |
| `tracing.otlp.endpoint` | OTLP/gRPC collector endpoint for traces; validated at boot when `tracing.otlp.enabled` is `true` | none | partial (validation only) |

[janiussyafiq]

Summary

Fixes six new-developer onboarding gaps surfaced by an end-to-end walkthrough of the 7-page onboarding flow (docs/index.md → docs/configuration/bootstrap-config.md) against main at 1a744ee. Three of the fixes (#1, #2, #3) close hard blockers on a clean machine (missing cargo / npm / provider-API-key prerequisites; model_not_found from display_name/model_name ambiguity; an Observability Exporter section whose second sentence is style-guide advice rather than user content). The remaining three (#4, #5, #6) close friction points along the same path (bootstrap-config.md field tables missing a Default column and an observability subsection; two credential-handling operational callouts; a cold-build duration note).

Doc-only diff. No code, schemas, configs, or test fixtures touched.

Closes#325.

Changes

File	Change
docs/quickstart/self-hosted.md	Prerequisites: add Rust 1.93+ with cargo (via rustup) as the leading prerequisite. After cargo run …: add a one-sentence note that the first-time build typically takes 3–5 minutes and that subsequent runs are incremental.
docs/quickstart/first-model-first-key-first-request.md	Prerequisites: replace "A reachable upstream OpenAI-compatible endpoint" with explicit credential-acquisition guidance (supported providers, sign-up link with cost order-of-magnitude, sk-... format hint, placeholder pointer). After the ProviderKey create-time response example: add a :::warning callout that the secret field is plaintext and that GET /admin/v1/provider_keys/:id also returns the plaintext.
docs/quickstart/openai-sdk.md	New ## Prerequisites section placed between the "If you have not done that yet…" intro and the first ## What Changes In The SDK section. Lists a running gateway with provider key / model / API key already created, and Node.js 18+ with npm (the OpenAI SDK floor).
docs/overview/core-concepts.md	Model field-list bullet: inline-annotate display_name as the alias callers send in the API request's model field and model_name as the upstream model ID forwarded to the provider. API Key section: append a sentence after the key_hash description noting the plaintext is unrecoverable post-create and pointing at POST /admin/v1/apikeys/:id/rotate. Observability Exporter section: replace the documentation-author-facing second sentence with a user-facing description of what the resource does (OTLP-compatible export to external backends) and when to configure one.
docs/configuration/bootstrap-config.md	Add a Default column to the field tables on etcd, proxy, admin. Build out the observability section with a new field table covering service_name, log_level, access_log, metrics.prometheus.*, metrics.otlp.*, and tracing.otlp.*, plus a pointer to the dynamic Observability Exporters page. Build out the cache section with a small field table covering backend and redis.

Net diff: 5 files, +58 / -35. Source: git diff --stat.

Test plan

Doc-only diff — no .rs files, schemas, configs, or test fixtures touched. The cargo trio was still run end-to-end as the canonical pre-merge gate.

• cargo fmt --check — PASS (exit 0).
• cargo clippy --workspace --all-targets -- -D warnings — PASS (exit 0; full tail captured below).
• cargo test --workspace — PASS (exit 0; full crate-suite results captured below).
• grep -rln <each affected page> tests/e2e/ for all 5 pages returns empty. pnpm test under tests/e2e/ is not applicable for this diff.

cargo clippy tail

 Checking aisix-proxy v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-proxy)
Checking aisix-admin v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-admin)
Checking aisix-server v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-server)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 40.28s

cargo test summary

33 test-suite-result lines, all 'ok'. Aggregate: 1029 tests passed, 0 failed, 3 ignored across the workspace (unit suites + doc-tests). Sample tail (last 3 named tests + last result line):
test keyword::tests::invalid_regex_is_a_clean_error_not_a_panic ... ok
test usage::tests::full_channel_drop_does_not_panic ... ok
test dispatch::tests::build_v1_url_rejects_path_without_leading_slash - should panic ... ok
test result: ok. <N> passed; 0 failed; <N> ignored; 0 measured; 0 filtered out

Affected pages

• docs/quickstart/self-hosted.md
• docs/quickstart/first-model-first-key-first-request.md
• docs/quickstart/openai-sdk.md
• docs/overview/core-concepts.md
• docs/configuration/bootstrap-config.md

Pre-merge-check verification log

The three pre-merge checks called out in #325 were resolved as follows:

1. Rust / Node minimum versions. Verified Rust against rust-toolchain.toml (channel = "1.93.1") and Cargo.toml (rust-version = "1.93"). The issue body's tentative "Rust 1.79+" floor was bumped to Rust 1.93 or newer in the doc, and a note added that rustup will pull the right channel automatically because rust-toolchain.toml pins it. For Node.js, neither tests/e2e/package.json nor a top-level package.json declares an engines floor, so the doc cites Node.js 18 or newer (the OpenAI SDK's published floor at version 4.x shipped in tests/e2e/package.json).
2. Bootstrap-config Default column. Pulled all default values from crates/aisix-core/src/config.rs (this repo's config crate lives in aisix-core, not in a separate aisix-config crate as the issue body tentatively listed). Values pulled: EtcdConfig::default_prefix → "/aisix", default_dial_timeout / default_request_timeout → 5000ms, ProxyConfig::default_body_limit → 10 * 1024 * 1024, AdminConfig::default → addr "127.0.0.1:0" / admin_keys [] / tls None, ObservabilityConfig::default_service_name → "aisix", default_log_level → "info", default_access_log → true, PrometheusConfig::default → { enabled: true, path: "/metrics" }, OtlpConfig::default → { enabled: false, endpoint: None }, OtlpTracingConfig::default → { enabled: false, endpoint: None, sample_ratio: 1.0 }, CacheConfig::default → { backend: Memory, redis: None }. For fields without an explicit default and with Config::validate enforcement (etcd.endpoints, proxy.addr), the column reads required. For fields whose Default is None, the column reads none.
3. Provider-key GET response shape.crates/aisix-core/src/models/provider_key.rs:39 defines pub secret: String without #[serde(skip_serializing)], and crates/aisix-admin/src/provider_keys_handlers.rs:29-38 (get_provider_key) returns Json<ResourceEntry<ProviderKey>> — so GET /admin/v1/provider_keys/:iddoes include the plaintext secret in the response body, every time. The original draft callout in docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #325 read "subsequent reads via GET do not include it", which was empirically incorrect. The callout in this PR was adjusted to reflect actual behavior: the warning now states that the plaintext is in both the create response and any subsequent GET, and that the same handling applies any time you read the resource.

References

• docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #325 — docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages (this PR closes it)
• docs: replace GET /health references with /livez and /admin/v1/health across configuration, reference, and operations docs #293 — docs: replace GET /health references with /livez and /admin/v1/health (predecessor doc-correction; merged as docs: replace stale GET /health references with /livez and /admin/v1/health #294)
• docs: remove max_budget_usd references from standalone docs (managed-only field) #295 — docs: remove max_budget_usd references from standalone docs (predecessor doc-correction; merged as docs: remove max_budget_usd references from standalone docs (managed-only field) #296)
• docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials #249 — docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials (the docs rebuild whose pages this PR amends)

Summary by CodeRabbit

• Documentation
  • Converted narrative configuration sections into structured tables for bootstrap, observability, and cache settings (including defaults and required/optional status)
  • Clarified core concepts: model display vs upstream identifiers, API key lifecycle/rotation, and observability exporter behavior
  • Added quickstart prerequisites: upstream provider API key, Node.js 18+ for OpenAI SDK, Rust 1.93+ for self-hosted
  • Added warning to treat provider API secrets as sensitive

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 2f8aa0cb-5faa-4a13-a703-ebe2423802be

📥 Commits

Reviewing files that changed from the base of the PR and between 5401ff1 and 1094aac.

📒 Files selected for processing (1)

• docs/configuration/bootstrap-config.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/configuration/bootstrap-config.md

---

📝 Walkthrough

Walkthrough

This PR updates documentation: restructures bootstrap configuration sections into tables with defaults and optional flags, refines core concept fields and observability exporter text, and adds explicit quickstart prerequisites plus an API-key secrecy warning.

Changes

Documentation Clarity Improvements

Layer / File(s)	Summary
Bootstrap configuration tables docs/configuration/bootstrap-config.md	etcd, proxy, admin, observability, and cache "Important fields" are converted from narrative lists into tables that show default values, optional fields (e.g., tls), reserved telemetry keys, and conditional nested blocks (e.g., redis when backend: redis).
Core concept refinements docs/overview/core-concepts.md	Model section now documents display_name, provider, and model_name; API Key section notes plaintext bearer tokens cannot be retrieved after creation and must be rotated; Observability Exporter text focuses on OTLP-compatible telemetry export.
Quickstart prerequisites and security guidance docs/quickstart/openai-sdk.md, docs/quickstart/self-hosted.md, docs/quickstart/first-model-first-key-first-request.md	OpenAI SDK quickstart adds a Prerequisites section (gateway + Node.js 18+); self-hosted quickstart requires Rust 1.93+ and notes first cargo run compile time; first-model guide adds upstream provider API key prerequisite and warns that admin API returns secret in plaintext and it must be treated as sensitive.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This doc-only PR improves new-developer onboarding by clarifying prerequisites, model naming, credential handling, and bootstrap configuration defaults across the quickstart and overview/configuration docs.

Changes:

• Adds Rust/Node/provider-key prerequisite guidance and build-time expectations.
• Clarifies model alias vs upstream model ID and credential visibility.
• Expands bootstrap configuration tables, especially observability and cache fields.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/quickstart/self-hosted.md	Adds Rust/cargo prerequisite and first-build duration note.
docs/quickstart/openai-sdk.md	Adds gateway and Node.js/npm prerequisites.
docs/quickstart/first-model-first-key-first-request.md	Clarifies provider API key prerequisite and plaintext provider-key handling.
docs/overview/core-concepts.md	Clarifies model fields, API-key plaintext handling, and observability exporter description.
docs/configuration/bootstrap-config.md	Adds defaults and expanded observability/cache bootstrap field tables.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[janiussyafiq]

Applied. Rewrote the appended paragraph to reflect actual behavior: the plaintext bearer is chosen (or generated) by the caller and SHA-256-hashed locally before submission, the gateway never sees or returns the plaintext at create time, and POST /admin/v1/apikeys/:id/rotate is the only endpoint that emits a server-generated plaintext (verified against apikeys_handlers.rs:97-104 for create and :155-178 for rotate). Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Confirmed against code: install_otlp_tracer (crates/aisix-obs/src/otlp.rs:26-58) validates the endpoint and emits a startup log line but defers the real exporter pipeline ("The real exporter wires up in a follow-up PR" per the inline code comment); no install_otlp_metrics function exists in the workspace. The bootstrap-config observability table now carries a Status column marking metrics.otlp.* as reserved (not yet wired) and tracing.otlp.* as partial (validation only). Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against otlp_http_sink.rs:184/:249 (the exporter builds OTLP traces payloads from UsageEvent records — per-request spans, not general metrics or logs). Rewrote the section to: "ships per-request span telemetry — derived from gateway UsageEvent records — to an OTLP/HTTP-compatible backend". Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against crates/aisix-admin/src/lib.rs:68 (/metrics route is hardcoded with no conditional gating). The bootstrap-config observability table now marks metrics.prometheus.enabled and metrics.prometheus.path as reserved (not yet consulted), with a footnote that the Prometheus exporter is currently mounted unconditionally at the hardcoded admin /metrics path. Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against crates/aisix-obs/src/access_log.rs:32-50 (AccessLog::emit() always calls tracing::info! with no config gate) and the unconditional emit_access_log call sites in every proxy handler. The bootstrap-config observability table now marks access_log as reserved (not yet consulted), with a footnote that access logs are emitted unconditionally by every proxy handler today. Pushed in commit 5401ff1.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

docs/configuration/bootstrap-config.md:164

• The tracing endpoint is described as validated at boot, but the implementation only checks that tracing.otlp.enabled=true has a non-empty endpoint; it does not parse or validate the endpoint URL/protocol before returning a handle. Calling this "validated" overstates the current behavior.

| `tracing.otlp.enabled` | enabling this validates the endpoint at boot and emits a startup log line; the OTLP traces pipeline itself is deferred to a future release | `false` | partial (validation only) |
| `tracing.otlp.endpoint` | OTLP/gRPC collector endpoint for traces; validated at boot when `tracing.otlp.enabled` is `true` | none | partial (validation only) |

[janiussyafiq]

Summary

Fixes six new-developer onboarding gaps surfaced by an end-to-end walkthrough of the 7-page onboarding flow (docs/index.md → docs/configuration/bootstrap-config.md) against main at 1a744ee. Three of the fixes (#1, #2, #3) close hard blockers on a clean machine (missing cargo / npm / provider-API-key prerequisites; model_not_found from display_name/model_name ambiguity; an Observability Exporter section whose second sentence is style-guide advice rather than user content). The remaining three (#4, #5, #6) close friction points along the same path (bootstrap-config.md field tables missing a Default column and an observability subsection; two credential-handling operational callouts; a cold-build duration note).

Doc-only diff. No code, schemas, configs, or test fixtures touched.

Closes#325.

Changes

File	Change
docs/quickstart/self-hosted.md	Prerequisites: add Rust 1.93+ with cargo (via rustup) as the leading prerequisite. After cargo run …: add a one-sentence note that the first-time build typically takes 3–5 minutes and that subsequent runs are incremental.
docs/quickstart/first-model-first-key-first-request.md	Prerequisites: replace "A reachable upstream OpenAI-compatible endpoint" with explicit credential-acquisition guidance (supported providers, sign-up link with cost order-of-magnitude, sk-... format hint, placeholder pointer). After the ProviderKey create-time response example: add a :::warning callout that the secret field is plaintext and that GET /admin/v1/provider_keys/:id also returns the plaintext.
docs/quickstart/openai-sdk.md	New ## Prerequisites section placed between the "If you have not done that yet…" intro and the first ## What Changes In The SDK section. Lists a running gateway with provider key / model / API key already created, and Node.js 18+ with npm (the OpenAI SDK floor).
docs/overview/core-concepts.md	Model field-list bullet: inline-annotate display_name as the alias callers send in the API request's model field and model_name as the upstream model ID forwarded to the provider. API Key section: append a sentence after the key_hash description noting the plaintext is unrecoverable post-create and pointing at POST /admin/v1/apikeys/:id/rotate. Observability Exporter section: replace the documentation-author-facing second sentence with a user-facing description of what the resource does (OTLP-compatible export to external backends) and when to configure one.
docs/configuration/bootstrap-config.md	Add a Default column to the field tables on etcd, proxy, admin. Build out the observability section with a new field table covering service_name, log_level, access_log, metrics.prometheus.*, metrics.otlp.*, and tracing.otlp.*, plus a pointer to the dynamic Observability Exporters page. Build out the cache section with a small field table covering backend and redis.

Net diff: 5 files, +58 / -35. Source: git diff --stat.

Test plan

Doc-only diff — no .rs files, schemas, configs, or test fixtures touched. The cargo trio was still run end-to-end as the canonical pre-merge gate.

• cargo fmt --check — PASS (exit 0).
• cargo clippy --workspace --all-targets -- -D warnings — PASS (exit 0; full tail captured below).
• cargo test --workspace — PASS (exit 0; full crate-suite results captured below).
• grep -rln <each affected page> tests/e2e/ for all 5 pages returns empty. pnpm test under tests/e2e/ is not applicable for this diff.

cargo clippy tail

 Checking aisix-proxy v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-proxy)
Checking aisix-admin v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-admin)
Checking aisix-server v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-server)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 40.28s

cargo test summary

33 test-suite-result lines, all 'ok'. Aggregate: 1029 tests passed, 0 failed, 3 ignored across the workspace (unit suites + doc-tests). Sample tail (last 3 named tests + last result line):
test keyword::tests::invalid_regex_is_a_clean_error_not_a_panic ... ok
test usage::tests::full_channel_drop_does_not_panic ... ok
test dispatch::tests::build_v1_url_rejects_path_without_leading_slash - should panic ... ok
test result: ok. <N> passed; 0 failed; <N> ignored; 0 measured; 0 filtered out

Affected pages

• docs/quickstart/self-hosted.md
• docs/quickstart/first-model-first-key-first-request.md
• docs/quickstart/openai-sdk.md
• docs/overview/core-concepts.md
• docs/configuration/bootstrap-config.md

Pre-merge-check verification log

The three pre-merge checks called out in #325 were resolved as follows:

1. Rust / Node minimum versions. Verified Rust against rust-toolchain.toml (channel = "1.93.1") and Cargo.toml (rust-version = "1.93"). The issue body's tentative "Rust 1.79+" floor was bumped to Rust 1.93 or newer in the doc, and a note added that rustup will pull the right channel automatically because rust-toolchain.toml pins it. For Node.js, neither tests/e2e/package.json nor a top-level package.json declares an engines floor, so the doc cites Node.js 18 or newer (the OpenAI SDK's published floor at version 4.x shipped in tests/e2e/package.json).
2. Bootstrap-config Default column. Pulled all default values from crates/aisix-core/src/config.rs (this repo's config crate lives in aisix-core, not in a separate aisix-config crate as the issue body tentatively listed). Values pulled: EtcdConfig::default_prefix → "/aisix", default_dial_timeout / default_request_timeout → 5000ms, ProxyConfig::default_body_limit → 10 * 1024 * 1024, AdminConfig::default → addr "127.0.0.1:0" / admin_keys [] / tls None, ObservabilityConfig::default_service_name → "aisix", default_log_level → "info", default_access_log → true, PrometheusConfig::default → { enabled: true, path: "/metrics" }, OtlpConfig::default → { enabled: false, endpoint: None }, OtlpTracingConfig::default → { enabled: false, endpoint: None, sample_ratio: 1.0 }, CacheConfig::default → { backend: Memory, redis: None }. For fields without an explicit default and with Config::validate enforcement (etcd.endpoints, proxy.addr), the column reads required. For fields whose Default is None, the column reads none.
3. Provider-key GET response shape.crates/aisix-core/src/models/provider_key.rs:39 defines pub secret: String without #[serde(skip_serializing)], and crates/aisix-admin/src/provider_keys_handlers.rs:29-38 (get_provider_key) returns Json<ResourceEntry<ProviderKey>> — so GET /admin/v1/provider_keys/:iddoes include the plaintext secret in the response body, every time. The original draft callout in docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #325 read "subsequent reads via GET do not include it", which was empirically incorrect. The callout in this PR was adjusted to reflect actual behavior: the warning now states that the plaintext is in both the create response and any subsequent GET, and that the same handling applies any time you read the resource.

References

• docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #325 — docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages (this PR closes it)
• docs: replace GET /health references with /livez and /admin/v1/health across configuration, reference, and operations docs #293 — docs: replace GET /health references with /livez and /admin/v1/health (predecessor doc-correction; merged as docs: replace stale GET /health references with /livez and /admin/v1/health #294)
• docs: remove max_budget_usd references from standalone docs (managed-only field) #295 — docs: remove max_budget_usd references from standalone docs (predecessor doc-correction; merged as docs: remove max_budget_usd references from standalone docs (managed-only field) #296)
• docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials #249 — docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials (the docs rebuild whose pages this PR amends)

Summary by CodeRabbit

• Documentation
  • Converted narrative configuration sections into structured tables for bootstrap, observability, and cache settings (including defaults and required/optional status)
  • Clarified core concepts: model display vs upstream identifiers, API key lifecycle/rotation, and observability exporter behavior
  • Added quickstart prerequisites: upstream provider API key, Node.js 18+ for OpenAI SDK, Rust 1.93+ for self-hosted
  • Added warning to treat provider API secrets as sensitive

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 2f8aa0cb-5faa-4a13-a703-ebe2423802be

📥 Commits

Reviewing files that changed from the base of the PR and between 5401ff1 and 1094aac.

📒 Files selected for processing (1)

• docs/configuration/bootstrap-config.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/configuration/bootstrap-config.md

---

📝 Walkthrough

Walkthrough

This PR updates documentation: restructures bootstrap configuration sections into tables with defaults and optional flags, refines core concept fields and observability exporter text, and adds explicit quickstart prerequisites plus an API-key secrecy warning.

Changes

Documentation Clarity Improvements

Layer / File(s)	Summary
Bootstrap configuration tables docs/configuration/bootstrap-config.md	etcd, proxy, admin, observability, and cache "Important fields" are converted from narrative lists into tables that show default values, optional fields (e.g., tls), reserved telemetry keys, and conditional nested blocks (e.g., redis when backend: redis).
Core concept refinements docs/overview/core-concepts.md	Model section now documents display_name, provider, and model_name; API Key section notes plaintext bearer tokens cannot be retrieved after creation and must be rotated; Observability Exporter text focuses on OTLP-compatible telemetry export.
Quickstart prerequisites and security guidance docs/quickstart/openai-sdk.md, docs/quickstart/self-hosted.md, docs/quickstart/first-model-first-key-first-request.md	OpenAI SDK quickstart adds a Prerequisites section (gateway + Node.js 18+); self-hosted quickstart requires Rust 1.93+ and notes first cargo run compile time; first-model guide adds upstream provider API key prerequisite and warns that admin API returns secret in plaintext and it must be treated as sensitive.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This doc-only PR improves new-developer onboarding by clarifying prerequisites, model naming, credential handling, and bootstrap configuration defaults across the quickstart and overview/configuration docs.

Changes:

• Adds Rust/Node/provider-key prerequisite guidance and build-time expectations.
• Clarifies model alias vs upstream model ID and credential visibility.
• Expands bootstrap configuration tables, especially observability and cache fields.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/quickstart/self-hosted.md	Adds Rust/cargo prerequisite and first-build duration note.
docs/quickstart/openai-sdk.md	Adds gateway and Node.js/npm prerequisites.
docs/quickstart/first-model-first-key-first-request.md	Clarifies provider API key prerequisite and plaintext provider-key handling.
docs/overview/core-concepts.md	Clarifies model fields, API-key plaintext handling, and observability exporter description.
docs/configuration/bootstrap-config.md	Adds defaults and expanded observability/cache bootstrap field tables.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[janiussyafiq]

Applied. Rewrote the appended paragraph to reflect actual behavior: the plaintext bearer is chosen (or generated) by the caller and SHA-256-hashed locally before submission, the gateway never sees or returns the plaintext at create time, and POST /admin/v1/apikeys/:id/rotate is the only endpoint that emits a server-generated plaintext (verified against apikeys_handlers.rs:97-104 for create and :155-178 for rotate). Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Confirmed against code: install_otlp_tracer (crates/aisix-obs/src/otlp.rs:26-58) validates the endpoint and emits a startup log line but defers the real exporter pipeline ("The real exporter wires up in a follow-up PR" per the inline code comment); no install_otlp_metrics function exists in the workspace. The bootstrap-config observability table now carries a Status column marking metrics.otlp.* as reserved (not yet wired) and tracing.otlp.* as partial (validation only). Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against otlp_http_sink.rs:184/:249 (the exporter builds OTLP traces payloads from UsageEvent records — per-request spans, not general metrics or logs). Rewrote the section to: "ships per-request span telemetry — derived from gateway UsageEvent records — to an OTLP/HTTP-compatible backend". Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against crates/aisix-admin/src/lib.rs:68 (/metrics route is hardcoded with no conditional gating). The bootstrap-config observability table now marks metrics.prometheus.enabled and metrics.prometheus.path as reserved (not yet consulted), with a footnote that the Prometheus exporter is currently mounted unconditionally at the hardcoded admin /metrics path. Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against crates/aisix-obs/src/access_log.rs:32-50 (AccessLog::emit() always calls tracing::info! with no config gate) and the unconditional emit_access_log call sites in every proxy handler. The bootstrap-config observability table now marks access_log as reserved (not yet consulted), with a footnote that access logs are emitted unconditionally by every proxy handler today. Pushed in commit 5401ff1.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

docs/configuration/bootstrap-config.md:164

• The tracing endpoint is described as validated at boot, but the implementation only checks that tracing.otlp.enabled=true has a non-empty endpoint; it does not parse or validate the endpoint URL/protocol before returning a handle. Calling this "validated" overstates the current behavior.

| `tracing.otlp.enabled` | enabling this validates the endpoint at boot and emits a startup log line; the OTLP traces pipeline itself is deferred to a future release | `false` | partial (validation only) |
| `tracing.otlp.endpoint` | OTLP/gRPC collector endpoint for traces; validated at boot when `tracing.otlp.enabled` is `true` | none | partial (validation only) |

[janiussyafiq]

Summary

Fixes six new-developer onboarding gaps surfaced by an end-to-end walkthrough of the 7-page onboarding flow (docs/index.md → docs/configuration/bootstrap-config.md) against main at 1a744ee. Three of the fixes (#1, #2, #3) close hard blockers on a clean machine (missing cargo / npm / provider-API-key prerequisites; model_not_found from display_name/model_name ambiguity; an Observability Exporter section whose second sentence is style-guide advice rather than user content). The remaining three (#4, #5, #6) close friction points along the same path (bootstrap-config.md field tables missing a Default column and an observability subsection; two credential-handling operational callouts; a cold-build duration note).

Doc-only diff. No code, schemas, configs, or test fixtures touched.

Closes#325.

Changes

File	Change
docs/quickstart/self-hosted.md	Prerequisites: add Rust 1.93+ with cargo (via rustup) as the leading prerequisite. After cargo run …: add a one-sentence note that the first-time build typically takes 3–5 minutes and that subsequent runs are incremental.
docs/quickstart/first-model-first-key-first-request.md	Prerequisites: replace "A reachable upstream OpenAI-compatible endpoint" with explicit credential-acquisition guidance (supported providers, sign-up link with cost order-of-magnitude, sk-... format hint, placeholder pointer). After the ProviderKey create-time response example: add a :::warning callout that the secret field is plaintext and that GET /admin/v1/provider_keys/:id also returns the plaintext.
docs/quickstart/openai-sdk.md	New ## Prerequisites section placed between the "If you have not done that yet…" intro and the first ## What Changes In The SDK section. Lists a running gateway with provider key / model / API key already created, and Node.js 18+ with npm (the OpenAI SDK floor).
docs/overview/core-concepts.md	Model field-list bullet: inline-annotate display_name as the alias callers send in the API request's model field and model_name as the upstream model ID forwarded to the provider. API Key section: append a sentence after the key_hash description noting the plaintext is unrecoverable post-create and pointing at POST /admin/v1/apikeys/:id/rotate. Observability Exporter section: replace the documentation-author-facing second sentence with a user-facing description of what the resource does (OTLP-compatible export to external backends) and when to configure one.
docs/configuration/bootstrap-config.md	Add a Default column to the field tables on etcd, proxy, admin. Build out the observability section with a new field table covering service_name, log_level, access_log, metrics.prometheus.*, metrics.otlp.*, and tracing.otlp.*, plus a pointer to the dynamic Observability Exporters page. Build out the cache section with a small field table covering backend and redis.

Net diff: 5 files, +58 / -35. Source: git diff --stat.

Test plan

Doc-only diff — no .rs files, schemas, configs, or test fixtures touched. The cargo trio was still run end-to-end as the canonical pre-merge gate.

• cargo fmt --check — PASS (exit 0).
• cargo clippy --workspace --all-targets -- -D warnings — PASS (exit 0; full tail captured below).
• cargo test --workspace — PASS (exit 0; full crate-suite results captured below).
• grep -rln <each affected page> tests/e2e/ for all 5 pages returns empty. pnpm test under tests/e2e/ is not applicable for this diff.

cargo clippy tail

 Checking aisix-proxy v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-proxy)
Checking aisix-admin v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-admin)
Checking aisix-server v0.1.0 (/root/GitHub/ai-gateway/crates/aisix-server)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 40.28s

cargo test summary

33 test-suite-result lines, all 'ok'. Aggregate: 1029 tests passed, 0 failed, 3 ignored across the workspace (unit suites + doc-tests). Sample tail (last 3 named tests + last result line):
test keyword::tests::invalid_regex_is_a_clean_error_not_a_panic ... ok
test usage::tests::full_channel_drop_does_not_panic ... ok
test dispatch::tests::build_v1_url_rejects_path_without_leading_slash - should panic ... ok
test result: ok. <N> passed; 0 failed; <N> ignored; 0 measured; 0 filtered out

Affected pages

• docs/quickstart/self-hosted.md
• docs/quickstart/first-model-first-key-first-request.md
• docs/quickstart/openai-sdk.md
• docs/overview/core-concepts.md
• docs/configuration/bootstrap-config.md

Pre-merge-check verification log

The three pre-merge checks called out in #325 were resolved as follows:

1. Rust / Node minimum versions. Verified Rust against rust-toolchain.toml (channel = "1.93.1") and Cargo.toml (rust-version = "1.93"). The issue body's tentative "Rust 1.79+" floor was bumped to Rust 1.93 or newer in the doc, and a note added that rustup will pull the right channel automatically because rust-toolchain.toml pins it. For Node.js, neither tests/e2e/package.json nor a top-level package.json declares an engines floor, so the doc cites Node.js 18 or newer (the OpenAI SDK's published floor at version 4.x shipped in tests/e2e/package.json).
2. Bootstrap-config Default column. Pulled all default values from crates/aisix-core/src/config.rs (this repo's config crate lives in aisix-core, not in a separate aisix-config crate as the issue body tentatively listed). Values pulled: EtcdConfig::default_prefix → "/aisix", default_dial_timeout / default_request_timeout → 5000ms, ProxyConfig::default_body_limit → 10 * 1024 * 1024, AdminConfig::default → addr "127.0.0.1:0" / admin_keys [] / tls None, ObservabilityConfig::default_service_name → "aisix", default_log_level → "info", default_access_log → true, PrometheusConfig::default → { enabled: true, path: "/metrics" }, OtlpConfig::default → { enabled: false, endpoint: None }, OtlpTracingConfig::default → { enabled: false, endpoint: None, sample_ratio: 1.0 }, CacheConfig::default → { backend: Memory, redis: None }. For fields without an explicit default and with Config::validate enforcement (etcd.endpoints, proxy.addr), the column reads required. For fields whose Default is None, the column reads none.
3. Provider-key GET response shape.crates/aisix-core/src/models/provider_key.rs:39 defines pub secret: String without #[serde(skip_serializing)], and crates/aisix-admin/src/provider_keys_handlers.rs:29-38 (get_provider_key) returns Json<ResourceEntry<ProviderKey>> — so GET /admin/v1/provider_keys/:iddoes include the plaintext secret in the response body, every time. The original draft callout in docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #325 read "subsequent reads via GET do not include it", which was empirically incorrect. The callout in this PR was adjusted to reflect actual behavior: the warning now states that the plaintext is in both the create response and any subsequent GET, and that the same handling applies any time you read the resource.

References

• docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #325 — docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages (this PR closes it)
• docs: replace GET /health references with /livez and /admin/v1/health across configuration, reference, and operations docs #293 — docs: replace GET /health references with /livez and /admin/v1/health (predecessor doc-correction; merged as docs: replace stale GET /health references with /livez and /admin/v1/health #294)
• docs: remove max_budget_usd references from standalone docs (managed-only field) #295 — docs: remove max_budget_usd references from standalone docs (predecessor doc-correction; merged as docs: remove max_budget_usd references from standalone docs (managed-only field) #296)
• docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials #249 — docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials (the docs rebuild whose pages this PR amends)

Summary by CodeRabbit

• Documentation
  • Converted narrative configuration sections into structured tables for bootstrap, observability, and cache settings (including defaults and required/optional status)
  • Clarified core concepts: model display vs upstream identifiers, API key lifecycle/rotation, and observability exporter behavior
  • Added quickstart prerequisites: upstream provider API key, Node.js 18+ for OpenAI SDK, Rust 1.93+ for self-hosted
  • Added warning to treat provider API secrets as sensitive

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 2f8aa0cb-5faa-4a13-a703-ebe2423802be

📥 Commits

Reviewing files that changed from the base of the PR and between 5401ff1 and 1094aac.

📒 Files selected for processing (1)

• docs/configuration/bootstrap-config.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/configuration/bootstrap-config.md

---

📝 Walkthrough

Walkthrough

This PR updates documentation: restructures bootstrap configuration sections into tables with defaults and optional flags, refines core concept fields and observability exporter text, and adds explicit quickstart prerequisites plus an API-key secrecy warning.

Changes

Documentation Clarity Improvements

Layer / File(s)	Summary
Bootstrap configuration tables docs/configuration/bootstrap-config.md	etcd, proxy, admin, observability, and cache "Important fields" are converted from narrative lists into tables that show default values, optional fields (e.g., tls), reserved telemetry keys, and conditional nested blocks (e.g., redis when backend: redis).
Core concept refinements docs/overview/core-concepts.md	Model section now documents display_name, provider, and model_name; API Key section notes plaintext bearer tokens cannot be retrieved after creation and must be rotated; Observability Exporter text focuses on OTLP-compatible telemetry export.
Quickstart prerequisites and security guidance docs/quickstart/openai-sdk.md, docs/quickstart/self-hosted.md, docs/quickstart/first-model-first-key-first-request.md	OpenAI SDK quickstart adds a Prerequisites section (gateway + Node.js 18+); self-hosted quickstart requires Rust 1.93+ and notes first cargo run compile time; first-model guide adds upstream provider API key prerequisite and warns that admin API returns secret in plaintext and it must be treated as sensitive.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This doc-only PR improves new-developer onboarding by clarifying prerequisites, model naming, credential handling, and bootstrap configuration defaults across the quickstart and overview/configuration docs.

Changes:

• Adds Rust/Node/provider-key prerequisite guidance and build-time expectations.
• Clarifies model alias vs upstream model ID and credential visibility.
• Expands bootstrap configuration tables, especially observability and cache fields.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/quickstart/self-hosted.md	Adds Rust/cargo prerequisite and first-build duration note.
docs/quickstart/openai-sdk.md	Adds gateway and Node.js/npm prerequisites.
docs/quickstart/first-model-first-key-first-request.md	Clarifies provider API key prerequisite and plaintext provider-key handling.
docs/overview/core-concepts.md	Clarifies model fields, API-key plaintext handling, and observability exporter description.
docs/configuration/bootstrap-config.md	Adds defaults and expanded observability/cache bootstrap field tables.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[janiussyafiq]

Applied. Rewrote the appended paragraph to reflect actual behavior: the plaintext bearer is chosen (or generated) by the caller and SHA-256-hashed locally before submission, the gateway never sees or returns the plaintext at create time, and POST /admin/v1/apikeys/:id/rotate is the only endpoint that emits a server-generated plaintext (verified against apikeys_handlers.rs:97-104 for create and :155-178 for rotate). Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Confirmed against code: install_otlp_tracer (crates/aisix-obs/src/otlp.rs:26-58) validates the endpoint and emits a startup log line but defers the real exporter pipeline ("The real exporter wires up in a follow-up PR" per the inline code comment); no install_otlp_metrics function exists in the workspace. The bootstrap-config observability table now carries a Status column marking metrics.otlp.* as reserved (not yet wired) and tracing.otlp.* as partial (validation only). Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against otlp_http_sink.rs:184/:249 (the exporter builds OTLP traces payloads from UsageEvent records — per-request spans, not general metrics or logs). Rewrote the section to: "ships per-request span telemetry — derived from gateway UsageEvent records — to an OTLP/HTTP-compatible backend". Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against crates/aisix-admin/src/lib.rs:68 (/metrics route is hardcoded with no conditional gating). The bootstrap-config observability table now marks metrics.prometheus.enabled and metrics.prometheus.path as reserved (not yet consulted), with a footnote that the Prometheus exporter is currently mounted unconditionally at the hardcoded admin /metrics path. Pushed in commit 5401ff1.

[janiussyafiq]

Applied. Verified against crates/aisix-obs/src/access_log.rs:32-50 (AccessLog::emit() always calls tracing::info! with no config gate) and the unconditional emit_access_log call sites in every proxy handler. The bootstrap-config observability table now marks access_log as reserved (not yet consulted), with a footnote that access logs are emitted unconditionally by every proxy handler today. Pushed in commit 5401ff1.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

docs/configuration/bootstrap-config.md:164

• The tracing endpoint is described as validated at boot, but the implementation only checks that tracing.otlp.enabled=true has a non-empty endpoint; it does not parse or validate the endpoint URL/protocol before returning a handle. Calling this "validated" overstates the current behavior.

| `tracing.otlp.enabled` | enabling this validates the endpoint at boot and emits a startup log line; the OTLP traces pipeline itself is deferred to a future release | `false` | partial (validation only) |
| `tracing.otlp.endpoint` | OTLP/gRPC collector endpoint for traces; validated at boot when `tracing.otlp.enabled` is `true` | none | partial (validation only) |