docs-kibana-settings

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Kibana settings docs

Kibana 设置文档

Work in the Kibana clone. Paths below are relative to

elastic/kibana

Document every user-facing

kibana.yml

setting and Advanced Settings (

uiSettings

) entry in

{settings}

YAML. Do not write the reference as freeform Markdown.

Schema,

applies_to

, description style, the

default

field, gated notes, and lifecycle history live in docs-builder: automated settings and settings-with-applies-example.yml.

This YAML does not follow the usual

docs-applies-to-tagging

lifecycle-symmetry rule. Read the settings page, not that skill.

Implementation tutorials stay in

docs/extend/tutorials/configuring-your-plugin.md

and

docs/extend/tutorials/ui-settings.md

. This skill covers the docs YAML only.

在 Kibana 克隆仓库中工作。以下路径相对于

elastic/kibana

。

在

{settings}

YAML 中记录每个面向用户的

kibana.yml

设置和高级设置（

uiSettings

）条目。不要以自由格式的 Markdown 编写参考文档。

Schema、

applies_to

、描述风格、

default

字段、门控说明和生命周期历史均由 docs-builder 定义：自动化设置和 settings-with-applies-example.yml。

此 YAML 不遵循常见的

docs-applies-to-tagging

生命周期对称规则。请阅读设置页面，而不是该 skill。

实现教程仍保留在

docs/extend/tutorials/configuring-your-plugin.md

和

docs/extend/tutorials/ui-settings.md

。本 skill 仅涵盖文档 YAML。

Classify

分类

User changes it in Code signal Docs YAML

User changes it in	Code signal	Docs YAML
`kibana.yml` or Cloud Edit user settings	Plugin `config` schema, `configPath` in `kibana.jsonc`	`docs/reference/configuration-reference/<area>-settings.yml`
Stack Management → Advanced Settings → Space Settings	`uiSettings.register()` (default `scope: 'namespace'` )	`docs/reference/advanced-settings-space.yml`
Advanced Settings → Global Settings	`uiSettings.registerGlobal()` or `scope: 'global'`	`docs/reference/advanced-settings-global.yml`

kibana.yml

or Cloud Edit user settings

Plugin

config

schema,

configPath

kibana.jsonc

docs/reference/configuration-reference/<area>-settings.yml

Stack Management → Advanced Settings → Space Settings

uiSettings.register()

(default

scope: 'namespace'

)

docs/reference/advanced-settings-space.yml

Advanced Settings → Global Settings

uiSettings.registerGlobal()

scope: 'global'

docs/reference/advanced-settings-global.yml

If the PR adds both a config-schema field and a

uiSettings

registration, document both. They are different settings.

A setting can exist in both places only when

kibana.yml

uses

uiSettings.overrides

to lock an Advanced Settings key. Document the

uiSettings

key in the Advanced Settings YAML. Document

uiSettings.overrides

itself in general settings YAML if that key changed.

Do not document a

kibana.yml

key in the Advanced Settings YAML. Do not document a

uiSettings

key in configuration-reference YAML.

用户更改位置代码标识文档 YAML

用户更改位置	代码标识	文档 YAML
`kibana.yml` 或 Cloud Edit user settings	插件 `config` Schema、插件 `kibana.jsonc` 中的 `configPath`	`docs/reference/configuration-reference/<area>-settings.yml`
Stack Management → Advanced Settings → Space Settings	`uiSettings.register()` （默认 `scope: 'namespace'` ）	`docs/reference/advanced-settings-space.yml`
Advanced Settings → Global Settings	`uiSettings.registerGlobal()` 或 `scope: 'global'`	`docs/reference/advanced-settings-global.yml`

kibana.yml

或 Cloud Edit user settings

插件

config

Schema、插件

kibana.jsonc

中的

configPath

docs/reference/configuration-reference/<area>-settings.yml

Stack Management → Advanced Settings → Space Settings

uiSettings.register()

（默认

scope: 'namespace'

）

docs/reference/advanced-settings-space.yml

Advanced Settings → Global Settings

uiSettings.registerGlobal()

或

scope: 'global'

docs/reference/advanced-settings-global.yml

如果 PR 同时添加了 config-schema 字段和

uiSettings

注册项，则两者都要记录。它们是不同的设置。

只有当

kibana.yml

使用

uiSettings.overrides

锁定某个高级设置键时，设置才可以同时出现在这两个位置。在高级设置 YAML 中记录该

uiSettings

键。如果

uiSettings.overrides

本身发生变化，请在通用设置 YAML 中记录它。

不要在高级设置 YAML 中记录

kibana.yml

键。不要在 configuration-reference YAML 中记录

uiSettings

键。

Workflow

工作流

Task progress:
- [ ] 1. Classify kibana.yml vs space vs global
- [ ] 2. Grep docs/reference and {settings} includes for the collection
- [ ] 3. Read the registration for key, type, default, category, and availability. Use the merge base if this branch removes the setting
- [ ] 4. Copy the nearest valid sibling
- [ ] 5. Tag applies_to from the docs-builder settings page
- [ ] 6. Check kibana.yml ech against the Cloud user-settings allowlist
- [ ] 7. Preview the Supported on line
- [ ] 8. If users need instructions, open a docs-content issue or PR

Task progress:
- [ ] 1. Classify kibana.yml vs space vs global
- [ ] 2. Grep docs/reference and {settings} includes for the collection
- [ ] 3. Read the registration for key, type, default, category, and availability. Use the merge base if this branch removes the setting
- [ ] 4. Copy the nearest valid sibling
- [ ] 5. Tag applies_to from the docs-builder settings page
- [ ] 6. Check kibana.yml ech against the Cloud user-settings allowlist
- [ ] 7. Preview the Supported on line
- [ ] 8. If users need instructions, open a docs-content issue or PR

Find the YAML file

查找 YAML 文件

bash

git grep -n -- '<prefix-or-key>' HEAD -- docs/reference

If a matching group already exists, add the entry there. Match the surrounding entries.

Resolve

configPath

from the plugin

kibana.jsonc

["xpack", "spaces"]

plus schema field

maxSpaces

xpack.spaces.maxSpaces

Most edits stay in an existing YAML file. The host

.md

file already includes it with

{settings}

. Create a new YAML plus host Markdown only when no file documents that prefix:

Add

docs/reference/configuration-reference/<area>-settings.md

with

{settings}

pointing at the new YAML.

Add the page under

docs/reference/toc.yml

→

configuration-reference.md

Reporting settings already split across several YAML files included from
```
reporting-settings.md
```
. Add to the matching include, not a new page.

Do not invent an Advanced Settings

group

name. Place the entry in the group that matches

category

in code. If

category

is omitted, the setting lands in General in the UI. If the UI adds a new category, add a matching

group

with an

id

. Keep order close to the UI.

Do not add YAML for internal flags, test-only config, or a rename that a documented deprecation already covers.

bash

git grep -n -- '<prefix-or-key>' HEAD -- docs/reference

如果已有匹配的分组，则在其中添加条目。保持与周围条目一致。

从插件的

kibana.jsonc

解析

configPath

。

["xpack", "spaces"]

与 Schema 字段

maxSpaces

对应

xpack.spaces.maxSpaces

。

大多数修改都应保留在现有 YAML 文件中。宿主

.md

文件已经通过

{settings}

引入该文件。只有在没有文件记录此前缀时，才创建新的 YAML 和宿主 Markdown：

添加

docs/reference/configuration-reference/<area>-settings.md

，其中

{settings}

指向新的 YAML。

在

docs/reference/toc.yml

→

configuration-reference.md

下添加页面。

报告设置已经拆分到多个 YAML 文件中，并由
```
reporting-settings.md
```
引入。请添加到匹配的 include 中，不要创建新页面。

不要臆造高级设置的

group

名称。将条目放入与代码中

category

匹配的分组。如果省略

category

，该设置会显示在 UI 的 General 中。如果 UI 添加了新类别，请添加带有

id

的匹配

group

。顺序应尽量与 UI 保持一致。

不要为内部标志、仅用于测试的配置或已有文档弃用说明涵盖的重命名添加 YAML。

Verify against source

对照源代码验证

Do not copy defaults, types, or availability from the issue body or PR title.

If this branch adds or changes the setting, read the implementation on this branch. If this branch removes the setting, grep the PR merge base. HEAD no longer has the registration. Keep the existing YAML entry and follow the docs-builder settings page for

removed

. If the setting is not part of this branch, read Elastic

main

. If

origin

is your fork, fetch

upstream/main

. If

origin

elastic/kibana

, fetch

origin/main

bash

git grep -n -- '<setting.key>' HEAD -- '*.ts' '*.tsx'

For a removal, recover the registration from the merge base against the same main ref you fetched above.

origin

is your fork:

bash

git grep -n -- '<setting.key>' "$(git merge-base HEAD upstream/main)" -- '*.ts' '*.tsx'

origin

elastic/kibana

bash

git grep -n -- '<setting.key>' "$(git merge-base HEAD origin/main)" -- '*.ts' '*.tsx'

Claim	kibana.yml source	Advanced Settings source
Key	`configPath` + schema field path	Object key in `register` / `registerGlobal`
Default	`schema.*({ defaultValue })`	`value` or `getValue`
Type	Schema type	`schema` plus optional `type`
Options	`schema.oneOf` / literals	`options` / `optionLabels`
Availability	`offeringBasedSchema` , `schema.contextRef('serverless')` , Cloud support	Serverless allowlists and `technicalPreview` / `experimental` / `deprecation`
UI category / group	n/a	`category` array. YAML `group` title.

The

setting

value must match the runtime key at HEAD, or the merge-base key when this branch removes the setting. Quote keys that contain a colon, for example

"dateFormat:tz"

. The

name

i18n string is the UI label. It is not the YAML

setting

key.

Copy the nearest sibling. Change only what this setting needs. Include

datatype

and

default

when the source defines them. Copy the

datatype

term the surrounding file already uses. Include

id

when the generated slug would collide or stay unreadable.

不要从 issue 正文或 PR 标题复制默认值、类型或可用性。

如果此分支添加或修改了设置，请阅读此分支上的实现。如果此分支删除了设置，请在 PR 的 merge base 中搜索。HEAD 中已不再包含注册项。保留现有 YAML 条目，并遵循 docs-builder 设置页面中关于

removed

的规则。如果设置不属于此分支，请阅读 Elastic

main

。如果

origin

是你的 fork，请 fetch

upstream/main

。如果

origin

是

elastic/kibana

，请 fetch

origin/main

。

bash

git grep -n -- '<setting.key>' HEAD -- '*.ts' '*.tsx'

对于删除的设置，请根据上面获取的同一 main 引用，从 merge base 中恢复注册项。

如果

origin

是你的 fork：

bash

git grep -n -- '<setting.key>' "$(git merge-base HEAD upstream/main)" -- '*.ts' '*.tsx'

如果

origin

是

elastic/kibana

：

bash

git grep -n -- '<setting.key>' "$(git merge-base HEAD origin/main)" -- '*.ts' '*.tsx'

声明	kibana.yml 来源	高级设置来源
键	`configPath` 与 Schema 字段路径	`register` / `registerGlobal` 中的对象键
默认值	`schema.*({ defaultValue })`	`value` 或 `getValue`
类型	Schema 类型	`schema` 以及可选的 `type`
选项	`schema.oneOf` / 字面量	`options` / `optionLabels`
可用性	`offeringBasedSchema` 、 `schema.contextRef('serverless')` 、Cloud 支持	Serverless 允许列表以及 `technicalPreview` / `experimental` / `deprecation`
UI 类别/分组	不适用	`category` 数组。YAML `group` 标题。

setting

值必须与 HEAD 处的运行时键匹配；如果此分支删除了设置，则必须与 merge base 处的键匹配。对于包含冒号的键需加引号，例如

"dateFormat:tz"

。

name

i18n 字符串是 UI 标签，不是 YAML 的

setting

键。

复制最接近的同级条目。仅修改此设置所需的内容。当来源定义时，包含

datatype

和

default

。复制周边文件已经使用的

datatype

术语。当生成的 slug 会冲突或仍难以理解时，包含

id

。

applies_to lookups

applies_to

查询

Read the docs-builder settings page, then fill Kibana-only values from source:

kibana.yml

ech
: grep the Elastic Cloud Hosted user-settings allowlist in a local
```
elastic/cloud
```
clone, under
```
scala-services/adminconsole/src/main/resources/settings/kibana/
```
. Write
```
ech: ga
```
if the key is listed. Write
```
ech: unavailable
```
if it is not. Do not use
```
node scripts/check_kibana_settings.js
```
for this. That CLI only lists Kibana config keys. It does not read the Cloud allowlist. Do not infer support from the published Cloud settings page. That page is generated from this YAML.
Advanced Settings
ech
: those keys are not on the Cloud user-settings allowlist. Follow the docs-builder deployment keys. The allowlist grep is for
```
kibana.yml
```
only.
If Elastic Cloud Hosted should list the setting, include the YAML from
```
docs/reference/cloud/elastic-cloud-kibana-settings.md
```
with
```
:deployment: ech
```
. That filter shows a setting only when the entry has
```
ech: ga
```
.

Advanced Settings
serverless
: start at

src/platform/packages/shared/serverless/settings/common/index.ts

. If the ID is there, write

serverless: ga

. If it is not, grep

observability_project

security_project

search_project

, and

vectordb_project

in that folder. Ignore

workplace_ai_project

. Follow each allowlist's imports to resolve the constant to the runtime key, including IDs exported from packages other than

kbn-management/settings/setting_ids

. Map

observability_project

observability

security_project

security

search_project

elasticsearch

, and

vectordb_project

vectordb

. If the ID is only on some of those four lists, nest those keys. If it is on none, write

serverless: unavailable

kibana.yml

serverless
: use

offeringBasedSchema

schema.contextRef('serverless')

. Write a scalar

serverless: ga

serverless: unavailable

先阅读 docs-builder 设置页面，然后从源代码填充 Kibana 专属值：

kibana.yml

ech
：在本地
```
elastic/cloud
```
克隆仓库中搜索 Elastic Cloud Hosted 用户设置允许列表，路径为
```
scala-services/adminconsole/src/main/resources/settings/kibana/
```
。如果键位于列表中，写入
```
ech: ga
```
；如果不在，则写入
```
ech: unavailable
```
。不要使用
```
node scripts/check_kibana_settings.js
```
。该 CLI 只列出 Kibana 配置键，不读取 Cloud 允许列表。不要根据已发布的 Cloud 设置页面推断支持情况，因为该页面由此 YAML 生成。
高级设置
ech
：这些键不在 Cloud 用户设置允许列表中。请遵循 docs-builder 的 deployment keys。允许列表搜索仅适用于
```
kibana.yml
```
。
如果 Elastic Cloud Hosted 应列出该设置，请从
```
docs/reference/cloud/elastic-cloud-kibana-settings.md
```
引入带有
```
:deployment: ech
```
的 YAML。该过滤器仅在条目具有
```
ech: ga
```
时显示设置。
高级设置
serverless
：从
```
src/platform/packages/shared/serverless/settings/common/index.ts
```
开始。如果 ID 位于其中，写入
```
serverless: ga
```
。如果不在，则在该文件夹中搜索
```
observability_project
```
、
```
security_project
```
、
```
search_project
```
和
```
vectordb_project
```
。忽略
```
workplace_ai_project
```
。沿每个允许列表的导入关系将常量解析为运行时键，包括从
```
kbn-management/settings/setting_ids
```
之外的其他 package 导出的 ID。将
```
observability_project
```
映射到
```
observability
```
，将
```
security_project
```
映射到
```
security
```
，将
```
search_project
```
映射到
```
elasticsearch
```
，将
```
vectordb_project
```
映射到
```
vectordb
```
。如果 ID 仅出现在上述四个列表中的部分列表中，则嵌套这些键。如果一个都不在，则写入
```
serverless: unavailable
```
。

kibana.yml

serverless
：使用

offeringBasedSchema

或

schema.contextRef('serverless')

。写入标量

serverless: ga

或

serverless: unavailable

。

Preview

预览

bash

docs-builder
docs-builder serve

On a Kibana PR:

https://docs-v3-preview.elastic.dev/elastic/kibana/pull/<n>/reference/kibana/<page>/

YAML that parses is not proof that badges render. Inspect the setting's

<dd>

for

dd > p.settings-supported-on

bash

docs-builder
docs-builder serve

在 Kibana PR 中：

https://docs-v3-preview.elastic.dev/elastic/kibana/pull/<n>/reference/kibana/<page>/

仅能成功解析的 YAML 并不能证明徽章会正确呈现。请检查设置的

<dd>

，查找

dd > p.settings-supported-on

。

How-to follow-up

操作指南后续处理

If users need instructions beyond the reference entry:

Search published docs with the

elastic-docs

MCP (

search_docs

find_related_docs

Open an
```
elastic/docs-content
```
issue, or an accompanying PR on the page that already covers that workflow.

Skip this when the reference entry is enough.

如果用户需要参考条目之外的说明：

使用
```
elastic-docs
```
MCP（
```
search_docs
```
或
```
find_related_docs
```
）搜索已发布文档。
在
```
elastic/docs-content
```
创建一个 issue，或在已经涵盖该工作流的页面上创建配套 PR。

如果参考条目已经足够，则跳过此步骤。

Verification

验证

YAML file matches kibana.yml vs space vs global
```
setting
```
matches the runtime key at HEAD, or at the merge base when this branch removes the setting
Description,
```
default
```
,
```
applies_to
```
, and lifecycle follow the docs-builder settings page
kibana.yml
```
ech
```
matches the Cloud user-settings allowlist in
```
elastic/cloud
```
Advanced Settings
```
serverless
```
matches
```
common/index.ts
```
or the nested project allowlists, following each file's imports
No UI label, test ID, or component name used as the YAML
```
setting
```
key

YAML 文件与 kibana.yml、space 或 global 分类一致
```
setting
```
与 HEAD 处的运行时键一致，或在删除设置的分支中与 merge base 处的运行时键一致
描述、
```
default
```
、
```
applies_to
```
和生命周期遵循 docs-builder 设置页面
kibana.yml
```
ech
```
与
```
elastic/cloud
```
中的 Cloud 用户设置允许列表一致
高级设置
```
serverless
```
与
```
common/index.ts
```
或嵌套的项目允许列表一致，并遵循每个文件的导入关系
未将 UI 标签、测试 ID 或组件名称用作 YAML
```
setting
```
键