Updating docs about how to create new dashboards #5229
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
monicasarbu
added
review
needs_backport
monicasarbu
force-pushed
the
update_docs_about_creating_new_dashboards
branch
from
b80a5af to
6d13b70
Compare
|
@dedemorton Ready for the review. I think I am done with the changes. |
dedemorton
reviewed
Sep 26, 2017
| @@ -1,17 +1,9 @@ | |||
| [[new-dashboards]] | |||
| == Creating New Kibana Dashboards for a Beat | |||
There was a problem hiding this comment.
Title is a bit long. Let's add an abbreviated title so the TOC is cleaner. It's good to mention "Beat" in the heading for SEO, but not necessary in the TOC where the context is clear.
== Creating New Kibana Dashboards for a Beat or Beat module
++++
<titleabbrev>Creating New Kibana Dashboards</titleabbrev>
++++
docs/devguide/newdashboards.asciidoc
Outdated
| a special index in Elasticsearch. By default the index is `.kibana`, but you can specify a different index. | ||
|
|
||
| When you're done making changes to the dashboards in Kibana, you can use the `export_dashboards` script to <<export-dashboards,export the dashboards>>, along with all dependencies, to a local directory. | ||
| When contributing to Beats development, you may want to add new dashboards or customize the existing ones. When you're done making changes to the dashboards in Kibana, you can use the `export_dashboards` script to <<export-dashboards,export the dashboards>>, along with all dependencies, to a local directory. |
There was a problem hiding this comment.
I'd remove line 4 and work some of the details into this section by saying:
When contributing to Beats development, you may want to add new dashboards or
customize the existing ones. To get started, you can
<<import-dashboards,import the Kibana dashboards>> that come with the official
Beats and use them as a starting point for your own dashboards. When you're done
making changes to the dashboards in Kibana, you can use the `export_dashboards`
script to <<export-dashboards,export the dashboards>>, along with all
dependencies, to a local directory.
docs/devguide/newdashboards.asciidoc
Outdated
|
|
||
| NOTE: Starting with Beats 5.0.0, the Kibana dashboards are not released as part of the Beat package. They are released in a separate | ||
| package called `beats-dashboards`. | ||
| The official Beats come with Kibana dashboards, and starting with 6.0.0, they are part of the Beat package. You can use the Beat executable to <<import-dashboards,import the dashboards>> into Kibana. |
There was a problem hiding this comment.
The ideas seem a bit out of sequence here. To fix this:
- Move line 4 to the topic about importing dashboards (see my comments later).
- Make the changes recommended on line 6.
docs/devguide/newdashboards.asciidoc
Outdated
| You can use the `import_dashboards` script to import all the dashboards and the index pattern for a Beat, including the dependencies such as visualizations and searches. | ||
| The `import_dashboards` script is available under | ||
| https://github.com/elastic/beats/tree/master/dev-tools/cmd/import_dashboards[beats/dev-tools/cmd/import_dashboards]. It's also available in each Beat package under the `scripts` directory. | ||
| You can use the Beat executable to import all the dashboards and the index pattern for a Beat, including the dependencies such as visualizations and searches. |
There was a problem hiding this comment.
Move the content from line 4 to the start of this section. One small concern I have is that users might look furtively on the download page for an executable called "Beat". So I'd suggest a minor change:
The official Beats come with Kibana dashboards, and starting with 6.0.0, they
are part of every Beat package. You can use the Beat executable to import all
the dashboards and the index pattern for a Beat, including the dependencies
such as visualizations and searches.
docs/devguide/newdashboards.asciidoc
Outdated
| https://github.com/elastic/beats/tree/master/dev-tools/cmd/import_dashboards[beats/dev-tools/cmd/import_dashboards]. It's also available in each Beat package under the `scripts` directory. | ||
| You can use the Beat executable to import all the dashboards and the index pattern for a Beat, including the dependencies such as visualizations and searches. | ||
|
|
||
| Importing the dashboards can be done as part of the `setup` phase. |
There was a problem hiding this comment.
Make this active to avoid passive voice:
To import the dashboards, run the setup command:
docs/devguide/newdashboards.asciidoc
Outdated
| *`-cacert <certificate_authority>`*:: | ||
| The Certificate Authority to use for server verification. | ||
| *`setup.dashboards.directory=<local_dir>`*:: | ||
| Local directory that contains the saved dashboards and their dependencies. The default value is `kibana` directory, available in the Beat package. |
There was a problem hiding this comment.
Change to:
The default value is the `kibana` directory available in the Beat package.
docs/devguide/newdashboards.asciidoc
Outdated
|
|
||
| [[build-dashboards]] | ||
| === Building Your Own Beat Dashboards | ||
|
|
||
| For visualizing the dashboards of a Beat in Kibana you need to have configured: | ||
| NOTE:: If you want to modify a dashboard that comes with a Beat, it's better to modify a copy of the dashboard as the Beat overwrites the dashboards during the setup phase in order to have the latest version. For duplicating a dashboard, just use the `Clone` button from the top of the page. |
There was a problem hiding this comment.
Change to: "...it's better to modify a copy of the dashboard because the Beat overwrites..."
docs/devguide/newdashboards.asciidoc
Outdated
|
|
||
| The Beat index pattern is generated from the `etc/fields.yml`, where all the fields for a Beat are defined. For each field, besides the `type`, you can configure the | ||
| The Beat index pattern is generated from the `fields.yml`, that contains all the fields generated by the Beat. For each field, besides the `type`, you can configure the |
There was a problem hiding this comment.
Users might be confused if we use "generated" to mean a two different things in the same sentence. Maybe it would be better to say:
The Beat index pattern is generated from the `fields.yml`, which contains all
the fields exported by the Beat.
docs/devguide/newdashboards.asciidoc
Outdated
|
|
||
| ==== Exporting Kibana 6.0 dashboards and newer | ||
|
|
||
| The `dev-tools/cmd/export_dashboards.go` script helps you export your customized Kibana 6.0 dashboards and newer. You might need to export a single dashboard |
There was a problem hiding this comment.
Is there a thought missing at the end of this sentence? There is no period, and it just seems to drop off.
docs/devguide/newdashboards.asciidoc
Outdated
|
|
||
| You can export a single dashboard by passing the dashboard ID in the `-dashboard` flag. | ||
|
|
||
| NOTE:: The dashboard ID is available in the dashboard URL. For example, in case the dashboard URL is |
There was a problem hiding this comment.
To get the correct note formatting, use NOTE: (a single colon). Otherwise, you won't get the correct formatting and icon. (There are multiple instances of NOTE:: that need to be fixed.)
|
@dedemorton I addressed all the remarks. Can you please have another look? |
monicasarbu
force-pushed
the
update_docs_about_creating_new_dashboards
branch
from
06742ed to
c7b196e
Compare
ruflin
pushed a commit
to ruflin/beats
that referenced
this pull request
Oct 9, 2017
(cherry picked from commit 94b6298)
ruflin
removed
the
needs_backport
tsg
pushed a commit
that referenced
this pull request
Oct 10, 2017
leweafan
pushed a commit
to leweafan/beats
that referenced
this pull request
Apr 28, 2023
(cherry picked from commit f945da9)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR is part of #4540, and includes documentation updates in the dev guide about how to import and export Kibana 6.0 dashboards and newer.
cc-ed @dedemorton