Repository navigation
docs: fill v1.3 documentation gaps and fix stale defaults - #3019
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
The pending-row alert guidance compares a cross-worker aggregate with a per-batch flush threshold, risking false alerts during normal operation in both English and Chinese documentation.
1 open issue
What changed in this PR
Updates the English and Chinese Nightly and v1.3 documentation to clarify release behavior, correct configuration defaults, and expand integration guidance.
Changes:
- Documents upgrade requirements, OTLP labels, bulk-write validation, retry semantics, and active/inactive TWCS options.
- Refreshes MCP v0.6.1 guidance and clarifies AI function availability in release binaries.
- Backports enterprise monitoring reference alerts from #2995 to v1.3.
| File | Description |
|---|---|
versioned_docs/version-1.3/user-guide/integrations/mcp.md |
Updates MCP tools, configuration, and write-mode guidance. |
versioned_docs/version-1.3/user-guide/ingest-data/for-observability/opentelemetry.md |
Explains resource-derived job and instance labels. |
versioned_docs/version-1.3/user-guide/ingest-data/for-iot/grpc-sdks/java.md |
Corrects Bulk Write schema requirements. |
versioned_docs/version-1.3/user-guide/deployments-administration/upgrade.md |
Adds compatibility changes and upgrade checklist items. |
versioned_docs/version-1.3/user-guide/deployments-administration/manage-data/compaction.md |
Explains TWCS windows and replaces the stale walkthrough. |
versioned_docs/version-1.3/user-guide/deployments-administration/configuration.md |
Corrects defaults and explains write-retry limits. |
versioned_docs/version-1.3/reference/sql/functions/ai/overview.md |
Clarifies release-binary availability and activation. |
versioned_docs/version-1.3/reference/sql/create.md |
Adds active/inactive TWCS table options. |
versioned_docs/version-1.3/reference/sql/alter.md |
Adds TWCS options for database and table changes. |
versioned_docs/version-1.3/enterprise/deployments-administration/monitoring/key-metrics.md |
Backports reference alerts and clarifies external configuration. |
i18n/zh/docusaurus-plugin-content-docs/version-1.3/user-guide/integrations/mcp.md |
Updates Chinese MCP tools and security guidance. |
i18n/zh/docusaurus-plugin-content-docs/version-1.3/user-guide/ingest-data/for-observability/opentelemetry.md |
Explains resource-derived labels in Chinese. |
i18n/zh/docusaurus-plugin-content-docs/version-1.3/user-guide/ingest-data/for-iot/grpc-sdks/java.md |
Corrects Chinese Bulk Write schema guidance. |
i18n/zh/docusaurus-plugin-content-docs/version-1.3/user-guide/deployments-administration/upgrade.md |
Adds Chinese compatibility and rollout guidance. |
i18n/zh/docusaurus-plugin-content-docs/version-1.3/user-guide/deployments-administration/manage-data/compaction.md |
Updates Chinese TWCS window and trigger explanations. |
i18n/zh/docusaurus-plugin-content-docs/version-1.3/user-guide/deployments-administration/configuration.md |
Aligns Chinese defaults and retry semantics. |
i18n/zh/docusaurus-plugin-content-docs/version-1.3/reference/sql/functions/ai/overview.md |
Clarifies AI availability and activation in Chinese. |
i18n/zh/docusaurus-plugin-content-docs/version-1.3/reference/sql/create.md |
Adds Chinese TWCS table-option descriptions. |
i18n/zh/docusaurus-plugin-content-docs/version-1.3/reference/sql/alter.md |
Adds Chinese TWCS alteration options. |
i18n/zh/docusaurus-plugin-content-docs/version-1.3/enterprise/deployments-administration/monitoring/key-metrics.md |
Backports Chinese monitoring reference alerts. |
i18n/zh/docusaurus-plugin-content-docs/current/user-guide/integrations/mcp.md |
Updates Chinese Nightly MCP guidance. |
i18n/zh/docusaurus-plugin-content-docs/current/user-guide/ingest-data/for-observability/opentelemetry.md |
Documents OTLP label derivation in Chinese Nightly. |
i18n/zh/docusaurus-plugin-content-docs/current/user-guide/ingest-data/for-iot/grpc-sdks/java.md |
Corrects Chinese Nightly Bulk Write requirements. |
i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/upgrade.md |
Aligns Chinese Nightly upgrade guidance. |
i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/manage-data/compaction.md |
Updates Chinese Nightly TWCS explanations. |
i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/configuration.md |
Corrects Chinese Nightly defaults and retry guidance. |
i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/functions/ai/overview.md |
Updates Chinese Nightly AI availability guidance. |
i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/create.md |
Adds Chinese Nightly TWCS creation options. |
i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/alter.md |
Adds Chinese Nightly TWCS alteration options. |
docs/user-guide/integrations/mcp.md |
Updates Nightly MCP tools, options, and safeguards. |
docs/user-guide/ingest-data/for-observability/opentelemetry.md |
Documents OTLP resource-to-label mapping. |
docs/user-guide/ingest-data/for-iot/grpc-sdks/java.md |
Corrects Nightly Bulk Write schema guidance. |
docs/user-guide/deployments-administration/upgrade.md |
Adds v1.3 compatibility and rollout requirements. |
docs/user-guide/deployments-administration/manage-data/compaction.md |
Documents TWCS windows and removes the stale walkthrough. |
docs/user-guide/deployments-administration/configuration.md |
Corrects Nightly defaults and explains retry limitations. |
docs/reference/sql/functions/ai/overview.md |
Clarifies AI release availability and startup instructions. |
docs/reference/sql/create.md |
Adds TWCS window-specific creation options. |
docs/reference/sql/alter.md |
Adds TWCS window-specific alteration options. |
Review effort: Balanced
Deploying greptime-docs with
|
| Latest commit: |
123b68d
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://f6e5b8ff.greptime-docs.pages.dev |
| Branch Preview URL: | https://docs-v1-3-doc-gaps.greptime-docs.pages.dev |
daviderli614
left a comment
daviderli614
left a comment
There was a problem hiding this comment.
Thanks for this thorough PR — I reviewed the full diff across all four copies (EN/ZH × current/version-1.3) and the changes are accurate, consistently applied, and well cross-referenced. No blocking issues; leaving a few non-blocking comments below.
Worth addressing
-
Orphaned diagram asset — All four references to
compaction-trigger-file-num.pngare removed (EN/ZH × current/1.3), butstatic/compaction-trigger-file-num.pngstill exists in the repo. Please delete the asset in this PR (or confirm it's linked from somewhere else). -
write_cache_ttl→Unset— Changing the default from8htoUnsetdrops the concrete value and doesn't state what "unset" means (no TTL / never expire, or some implicit default?). One sentence clarifying the unset behavior would help, since cache-eviction semantics matter here. -
grpc.server_addr(metasrv) →Unset— The description no longer explains what happens when it's unset, and it now sits next to the top-levelserver_addr(127.0.0.1:3002). The datanodegrpc.server_addrrow documents its auto-detect fallback; metasrv should get the same treatment so readers can tell which key wins. -
flight_compressiondefaultnone→arrow_ipc— This is a user-visible default (lz4 Arrow IPC compression on by default). If it's a genuine v1.3 behavior change rather than just a stale-doc fix, consider a one-line callout in the upgrade guide. Worth a quick double-check againstconfig/config.md.
Nits
-
OTLP
joblabel change — Good table entry. Since it requires updating dashboard selectors and alert rules, consider also adding a checklist item under "Before upgrading" alongside the TSID item. -
num_workers"half of the CPU cores, rounded up" — Phrasing differs from the neighboringAutorows ("1/2 of cpu cores", no "rounded up"). Pick one for consistency. -
TWCS active-window definition — "the window of the SST file with the highest sequence number" is a bit opaque; the parenthetical "most recently flushed data" already carries the meaning, so consider dropping or glossing "sequence number".
-
up{job="greptimedb-instance"}— The hardcoded job name assumes a specific scrape config; a brief note that it should match the scrape job name would prevent copy-paste confusion.
Nice work in particular on the write_retry semantics (exactly-once caveat, append-only duplicates) and the MCP v0.6.1 rewrite (write-mode now correctly gating pipeline/dashboard tools). LGTM once the asset cleanup and the write_cache_ttl/grpc.server_addr clarifications are addressed.
What changed
Fills user-facing gaps for GreptimeDB v1.3 and corrects stale content in the same pages.
v1.3 behavior that was missing or wrong:
upgrade.md: adds the OTLPjoblabel change (<service.namespace>/<service.name>), PromQL vector matching changes, and strict bulk insert validation; the checklist now coversprom_validation_modeand the Datanode-before-Frontend order.opentelemetry.md: documents howjobandinstanceare derived from resource attributes.active_window.*andinactive_window.*options incompaction.md,create.md, andalter.md. Thetrigger_file_num = 3walkthrough and diagram are removed because the active window now triggers on L0 file count only.configuration.md:write_retryretry semantics (no exactly-once; append-only tables can get duplicates);experimental_series_scan_v2defaults tofalse.greptime_prom_store_pending_rowsrule no longer compares the cross-batch total with the per-batchmax_batch_rows, and theuprule notes that the job name depends on the scrape configuration.Stale defaults in
configuration.md, checked against v1.3.0config/config.mdand source: runtime thread minimums,num_workers, write buffer and cache sizes,write_cache_ttl,grpc.flight_compression, metasrvdata_home,grpc.server_addr,datanode.client.connect_timeout, andwal.auto_prune_interval. Version 1.2 has several of the same wrong defaults and is not changed here.Scope
Verification
git diff --check,DOC_LANG=en pnpm check:links,DOC_LANG=zh pnpm check:links.Checklist