mirror of
https://github.com/elastic/kibana.git
synced 2025-06-27 18:51:07 -04:00
[DOCS] Adds user-facing docs for the new KP logging configuration (#94993)
Co-authored-by: Lisa Cawley <lcawley@elastic.co>
This commit is contained in:
Christiane (Tina) Heiligers
GitHub
parent
47761eed5d
commit
d29abdfa15
15 changed files with 1358 additions and 588 deletions
|
|
@ -1,6 +1,8 @@
|
|||
[[saved-objects-service]]
|
||||
== Saved Objects service
|
||||
|
||||
NOTE: The Saved Objects service is available both server and client side.
|
||||
|
||||
`Saved Objects service` allows {kib} plugins to use {es} like a primary
|
||||
database. Think of it as an Object Document Mapper for {es}. Once a
|
||||
plugin has registered one or more Saved Object types, the Saved Objects client
|
||||
|
|
@ -28,7 +30,9 @@ spaces.
|
|||
This document contains developer guidelines and best-practices for plugins
|
||||
wanting to use Saved Objects.
|
||||
|
||||
=== Registering a Saved Object type
|
||||
=== Server side usage
|
||||
|
||||
==== Registering a Saved Object type
|
||||
Saved object type definitions should be defined in their own `my_plugin/server/saved_objects` directory.
|
||||
|
||||
The folder should contain a file per type, named after the snake_case name of the type, and an `index.ts` file exporting all the types.
|
||||
|
|
@ -83,7 +87,7 @@ export class MyPlugin implements Plugin {
|
|||
}
|
||||
----
|
||||
|
||||
=== Mappings
|
||||
==== Mappings
|
||||
Each Saved Object type can define it's own {es} field mappings.
|
||||
Because multiple Saved Object types can share the same index, mappings defined
|
||||
by a type will be nested under a top-level field that matches the type name.
|
||||
|
|
@ -149,59 +153,6 @@ should carefully consider the fields they add to the mappings. Similarly,
|
|||
Saved Object types should never use `dynamic: true` as this can cause an
|
||||
arbitrary amount of fields to be added to the `.kibana` index.
|
||||
|
||||
=== References
|
||||
When a Saved Object declares `references` to other Saved Objects, the
|
||||
Saved Objects Export API will automatically export the target object with all
|
||||
of it's references. This makes it easy for users to export the entire
|
||||
reference graph of an object.
|
||||
|
||||
If a Saved Object can't be used on it's own, that is, it needs other objects
|
||||
to exist for a feature to function correctly, that Saved Object should declare
|
||||
references to all the objects it requires. For example, a `dashboard`
|
||||
object might have panels for several `visualization` objects. When these
|
||||
`visualization` objects don't exist, the dashboard cannot be rendered
|
||||
correctly. The `dashboard` object should declare references to all it's
|
||||
visualizations.
|
||||
|
||||
However, `visualization` objects can continue to be rendered or embedded into
|
||||
other dashboards even if the `dashboard` it was originally embedded into
|
||||
doesn't exist. As a result, `visualization` objects should not declare
|
||||
references to `dashboard` objects.
|
||||
|
||||
For each referenced object, an `id`, `type` and `name` are added to the
|
||||
`references` array:
|
||||
|
||||
[source, typescript]
|
||||
----
|
||||
router.get(
|
||||
{ path: '/some-path', validate: false },
|
||||
async (context, req, res) => {
|
||||
const object = await context.core.savedObjects.client.create(
|
||||
'dashboard',
|
||||
{
|
||||
title: 'my dashboard',
|
||||
panels: [
|
||||
{ visualization: 'vis1' }, // <1>
|
||||
],
|
||||
indexPattern: 'indexPattern1'
|
||||
},
|
||||
{ references: [
|
||||
{ id: '...', type: 'visualization', name: 'vis1' },
|
||||
{ id: '...', type: 'index_pattern', name: 'indexPattern1' },
|
||||
]
|
||||
}
|
||||
)
|
||||
...
|
||||
}
|
||||
);
|
||||
----
|
||||
<1> Note how `dashboard.panels[0].visualization` stores the `name` property of
|
||||
the reference (not the `id` directly) to be able to uniquely identify this
|
||||
reference. This guarantees that the id the reference points to always remains
|
||||
up to date. If a visualization `id` was directly stored in
|
||||
`dashboard.panels[0].visualization` there is a risk that this `id` gets
|
||||
updated without updating the reference in the references array.
|
||||
|
||||
==== Writing Migrations
|
||||
|
||||
Saved Objects support schema changes between Kibana versions, which we call
|
||||
|
|
@ -308,4 +259,60 @@ point in time.
|
|||
It is critical that you have extensive tests to ensure that migrations behave
|
||||
as expected with all possible input documents. Given how simple it is to test
|
||||
all the branch conditions in a migration function and the high impact of a bug
|
||||
in this code, there's really no reason not to aim for 100% test code coverage.
|
||||
in this code, there's really no reason not to aim for 100% test code coverage.
|
||||
|
||||
=== Client side usage
|
||||
|
||||
==== References
|
||||
|
||||
When a Saved Object declares `references` to other Saved Objects, the
|
||||
Saved Objects Export API will automatically export the target object with all
|
||||
of its references. This makes it easy for users to export the entire
|
||||
reference graph of an object.
|
||||
|
||||
If a Saved Object can't be used on its own, that is, it needs other objects
|
||||
to exist for a feature to function correctly, that Saved Object should declare
|
||||
references to all the objects it requires. For example, a `dashboard`
|
||||
object might have panels for several `visualization` objects. When these
|
||||
`visualization` objects don't exist, the dashboard cannot be rendered
|
||||
correctly. The `dashboard` object should declare references to all its
|
||||
visualizations.
|
||||
|
||||
However, `visualization` objects can continue to be rendered or embedded into
|
||||
other dashboards even if the `dashboard` it was originally embedded into
|
||||
doesn't exist. As a result, `visualization` objects should not declare
|
||||
references to `dashboard` objects.
|
||||
|
||||
For each referenced object, an `id`, `type` and `name` are added to the
|
||||
`references` array:
|
||||
|
||||
[source, typescript]
|
||||
----
|
||||
router.get(
|
||||
{ path: '/some-path', validate: false },
|
||||
async (context, req, res) => {
|
||||
const object = await context.core.savedObjects.client.create(
|
||||
'dashboard',
|
||||
{
|
||||
title: 'my dashboard',
|
||||
panels: [
|
||||
{ visualization: 'vis1' }, // <1>
|
||||
],
|
||||
indexPattern: 'indexPattern1'
|
||||
},
|
||||
{ references: [
|
||||
{ id: '...', type: 'visualization', name: 'vis1' },
|
||||
{ id: '...', type: 'index_pattern', name: 'indexPattern1' },
|
||||
]
|
||||
}
|
||||
)
|
||||
...
|
||||
}
|
||||
);
|
||||
----
|
||||
<1> Note how `dashboard.panels[0].visualization` stores the `name` property of
|
||||
the reference (not the `id` directly) to be able to uniquely identify this
|
||||
reference. This guarantees that the id the reference points to always remains
|
||||
up to date. If a visualization `id` was directly stored in
|
||||
`dashboard.panels[0].visualization` there is a risk that this `id` gets
|
||||
updated without updating the reference in the references array.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue