forked from elastic/integrations
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Move integration dev docs to elastic.co (elastic#9796)
* move documentation to public doc site * add links to new content
- Loading branch information
1 parent
c6d4a73
commit 30d807c
Showing
23 changed files
with
20 additions
and
1,841 deletions.
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,15 +1,10 @@ | ||
| # Contributing Guide | ||
|
|
||
| This page is intended for contributors to the [Package Registry](https://github.com/elastic/package-registry/) and Elastic Integrations. | ||
| Ready to dive into the world of integrations? See the [Integrations Developer Guide](https://www.elastic.co/guide/en/integrations-developer/current/index.html) to get started. Topics include: | ||
|
|
||
| ## Table of Contents | ||
|
|
||
| * [Definitions](./docs/definitions.md) - learn basic terms used in the universe of integrations, packages, data streams | ||
| * [Generic guidelines](./docs/generic_guidelines.md) - generic guidelines for developing integrations, compliance with ECS, docs, dashboards | ||
| * [Sample package: Nginx](./packages/nginx) - use as an inspiration for new packages, look at files, folders, test resources | ||
| * [Developer workflow: build and test integration](./docs/developer_workflow_design_build_test_integration.md) - step-by-step guide on how to build and test an integration | ||
| * [Developer workflow: bug fix an old package version](./docs/developer_workflow_bug_fix_older_package_version.md) - step-by-step guide on how to release a new fix for an old package version. | ||
| * [Fine-tune integration](./docs/fine_tune_integration.md) - fill missing items, correct structure, review manifests | ||
| * [Testing and validation](./docs/testing_and_validation.md) - run the Elastic stack, use test runners, review test coverage | ||
| * [Tips for building integrations](./docs/tips_for_building_integrations.md) - see your local changes in Kibana, follow best practices | ||
| * [Documentation Guidelines](./docs/documentation_guidelines.md) - guidelines for contributing to the docs, the Generic guidelines also has lots of docs tips | ||
| * [Quick start: Sample integration](https://www.elastic.co/guide/en/integrations-developer/current/quick-start.html) | ||
| * [Build an integration](https://www.elastic.co/guide/en/integrations-developer/current/build-a-new-integration.html) | ||
| * [Upload an integration](https://www.elastic.co/guide/en/integrations-developer/current/upload-a-new-integration.html) | ||
| * [Test an integration](https://www.elastic.co/guide/en/integrations-developer/current/testing.html) | ||
| * [Publish an integration](https://www.elastic.co/guide/en/integrations-developer/current/_publish_an_integration.html) | ||
| * [Developer workflows](https://www.elastic.co/guide/en/integrations-developer/current/developer-workflows.html) |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,132 +1 @@ | ||
| # Dashboard guidelines | ||
|
|
||
| A [Kibana dashboard][1] is a set of one or more panels, also referred as visualizations. Panels display data in charts, tables, maps, and more. Dashboards support several types of panels to display your data, and several options to create panels. | ||
|
|
||
| The goal of each integration dashboard is to: | ||
|
|
||
| * Provide a way to explore ingested data out of the box. | ||
| * Provide an overview of the monitored resources through installing the integration. | ||
|
|
||
| Each integration package should contain one or more dashboards. | ||
|
|
||
| ## Dashboard Best Practises | ||
|
|
||
| ### Building dashboards on stable versions | ||
|
|
||
| Avoid building dashboards on SNAPSHOT versions because as long as the release is not stable behavior changes might render your dashboard unusable. The only supported approach is to use a globally released version from [official releases list](https://www.elastic.co/downloads/past-releases#kibana). | ||
|
|
||
| ### Not too many visualizations per dashboard | ||
|
|
||
| Include only necessary visualisation inside a Dashboard and split them up (if possible) to other dashboards. Linking can be done: | ||
|
|
||
| * By using a Markdown visualization to improve performance | ||
| * Use [drilldowns](https://www.elastic.co/guide/en/kibana/current/drilldowns.html) to connect dashboards where they make sense | ||
|
|
||
| ### Out of date fields in dashboards | ||
|
|
||
| The dashboards must be updated to reflect any changes to field names or types. If a PR updates a field name or type, make sure it is correctly updated in any dashboard the field is being used into. | ||
|
|
||
| ### Add Visualizations by value, not by reference inside a dashboard | ||
|
|
||
| Kibana visualizations can be added in a dashboard by value or by reference. Historically by value did not exist. Switching to value has the advantage that the dashboards are fully self contained and only need a single request to be installed. | ||
|
|
||
| To achieve this: | ||
|
|
||
| * Migrate existing dashboards from by reference to by value | ||
| * Create new dashboards adding visualizations by value | ||
|
|
||
| A migration script has been created to help with the migration: [flash1293/legacy_vis_analyzer][2] | ||
|
|
||
| ### Choose the context of your Dashboard | ||
|
|
||
| Should always try to understand as much as possible what kind of context your users need to interact with. So keep the minimal context needed by answering following questions: | ||
|
|
||
| * Who is going to use this dashboard? | ||
| * How much time will the users have? | ||
| * What is the main goal of this dashboard and if there are, what are the secondary ones? | ||
| * What kind of charts can help users identify insights in the most immediate and clear way? | ||
|
|
||
| ### Organisation and hierarchy matters in your dashboards | ||
|
|
||
| The positioning of elements in space can define their belonging, with a certain degree this can be applied to dashboards. | ||
|
|
||
| * Keep related visualisations close to each other | ||
|
|
||
|  | ||
|
|
||
| * Use Markdown to create blocks of related content | ||
|
|
||
|  | ||
|
|
||
| * Reading Direction | ||
|
|
||
| Most people are used to reading from top to bottom. Place at the top of your page the most important charts and the ones that could give a brief and immediate summary of the context. A good general suggestion would be to increase the level of detail while you reach the bottom of the dashboard, this way users that are interested in getting all the information can obtain them without requiring too much effort from user that only need a quick glance of the situation. | ||
|
|
||
| * Central focal point | ||
|
|
||
| Placing a big chart, especially with big visual shapes such as rectangles, at the center of the dashboard would help reinforce a natural visual focal point that lies in the center of the interface | ||
|
|
||
|  | ||
|
|
||
| ### Use Margins | ||
|
|
||
| Kibana dashboards offer the possibility to apply margins between visualisations, we would suggest to always do that. | ||
| Margins create separation between charts which is an important visual feature, it helps identifying when two elements belong together or not while, at the same time, they provide more spacing and empty spaces that are always useful in making our interface more clean and elegant. | ||
|
|
||
| ## Visualisation Best Practises | ||
|
|
||
| ### Lens vs TSVB visualizations | ||
|
|
||
| **Always use Lens**, when possible. It's the best choice to be consistent and up to date and it should always be your first choice when creating new visualizations. | ||
|
|
||
| Migrate the dashboards from TSVB to Lens where possible. If it's not possible, please engage with the Kibana team to identify any gaps that prevent full TSVB to Lens dashboard migration. | ||
|
|
||
| ### Visualizations should contain a filter | ||
|
|
||
| Kibana visualizations can define a filter to avoid performance issues querying all `metrics-*` or `logs-*` indices. | ||
|
|
||
| It is recommended to set a filter in each visualization at least by the required `data_stream.dataset`. More details about the Elastic data stream naming scheme [here][3]. | ||
|
|
||
| Avoid using general filters as possible (filters with `-*`). Combine multiple fields and values inside a filter with AND/OR operators. Although your filter might become more complex, will avoid extra queries. | ||
|
|
||
| Example: | ||
|
|
||
|  | ||
|
|
||
| ### Do not use “library visualizations” | ||
|
|
||
| Do not use the visualisations that show up in the `Analytics > Visualize library`. Instead define visualizations as part of the dashboard. This is the default when creating new panels by clicking “Add new visualization” on the dashboard. If some panels are already saved to the library, you can unlink them and delete them from the library. There are little use cases where library visualizations are preferable. It makes sense e.g. if a given visualization always has to be exactly the same on multiple dashboards or if its users frequently look at the visualization without looking at the whole dashboard. | ||
|
|
||
| ### Use dashboard-native controls | ||
|
|
||
| The **Input controls** visualization type is deprecated in favor of **Controls** embedded into the dashboard itself. The `Controls` dropdown in the Dashboard menu bar should be used. See the [documentation](https://www.elastic.co/guide/en/kibana/master/add-controls.html) page for more information. | ||
|
|
||
| ### Keep Consistent Color | ||
|
|
||
| Use color to distinguish categories, represent quantity/density, and highlight data. When using color in this way, be aware that too many colors in a single chart can create noise and hinder quick comprehension. | ||
|
|
||
| [Elastic UI](https://elastic.github.io/eui/#/elastic-charts/creating-charts) can provide guidance for correct color choice. | ||
| Colors provided there for visualization have been tested for accessibility contrast and using them you would be sure to properly serve the biggest audience. | ||
|
|
||
| If your dashboard is made to identify specific behaviors it might be interesting to consider a color setting that could help pointing it out. Use a neutral color for generic elements and an accent one for the things that you are looking for. | ||
|
|
||
|  | ||
|
|
||
| ### Titles in Visualisations matter | ||
|
|
||
| Titles can have a strong visual impact on dashboards, especially when there are a lot of small charts. Two principles can generally be followed: | ||
|
|
||
| * Remove unnecessary or repetitive titles when the information is already explained or written within the chart | ||
| * When title is needed make it self explanatory and exhaustive, this way you will be able to remove axis titles and other specifications leaving more space for the charts itself. | ||
|
|
||
|  | ||
|
|
||
| ### Numbers/Formatting | ||
|
|
||
| Reduce the number of decimal places to the absolutely necessary ones to avoid extra calculations. | ||
| Use tables whenever you need precise numbers. | ||
|
|
||
|
|
||
| [1]: https://www.elastic.co/guide/en/kibana/current/dashboard.html | ||
| [2]: https://github.com/elastic/visualizations_integrations_tools | ||
| [3]: https://www.elastic.co/blog/an-introduction-to-the-elastic-data-stream-naming-scheme | ||
| **This content has moved. Please see the [Integrations Developer Guide](https://www.elastic.co/guide/en/integrations-developer/current/dashboard-guidelines.html) instead.** |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,49 +1 @@ | ||
| # Definitions | ||
|
|
||
| ## Package | ||
|
|
||
| An Elastic Package, or simply package for short, contains the dashboards, visualisations, and configurations to monitor the logs and metrics of a particular technology or group of related services, such as “MySQL”, or “System”. | ||
|
|
||
| The package consists of: | ||
|
|
||
| * Name | ||
| * Zero or more dashboards and visualisations and Canvas workpads | ||
| * Zero or more ML job definitions | ||
| * Zero or more data stream index templates | ||
|
|
||
| The package is versioned. | ||
|
|
||
| ## Integration | ||
|
|
||
| An integration is a specific type of a _package_ defining data streams used to observe a product using logs, metrics, and traces. | ||
|
|
||
| ## Data stream | ||
|
|
||
| A data stream is logical sub-division of an Integration package, dealing with a specific type of observable aspect of the service or product being observed. For example, the `mysql` package defines a data stream for collecting metrics and another data stream for collecting server logs. | ||
|
|
||
| A data stream defines all the assets needed to create an Elasticsearch data stream, for example: index templates and ingest pipelines. These assets are loaded into Elasticsearch when a user installs a package via the Fleet UI in Kibana. | ||
|
|
||
| A data stream also defines a policy template. Policy templates include variables that allow users to configure the data stream via the Fleet UI in Kibana. The resulting policy is interpreted by the Elastic Agent to collect relevant information from the product or service being observed. | ||
|
|
||
| Data streams are defined inside the `data_stream` folder located under the package's root directory. Each data stream is defined in it's own sub-folder. | ||
|
|
||
| The data stream consists of: | ||
|
|
||
| * Field definitions (`fields.yml` files) | ||
| * Zero or more ingest pipelines | ||
| * An Elastic Agent policy template | ||
|
|
||
| ## Development Extensions: '_dev' directories | ||
|
|
||
| The `_dev` directory is part of [the package spec](https://github.com/elastic/package-spec), containing development resources. These development resources cover any types of files/folders needed only at development time. This includes resources needed for testing but also includes any templates that might be used for generating documentation. In the future it could include other files/folders needed just at development time. It can be defined on the following levels: | ||
|
|
||
| 1. the package-level `_dev` folder contains files needed to setup the testing environment for that package. This environment setup is specified via folders/files in the `_dev/deploy` folder. For example, the `apache` package [specifies](https://github.com/elastic/integrations/tree/main/packages/apache/_dev/deploy) how to spin up an Apache Docker container for testing. | ||
| 1. the data stream-level `_dev` folder contains test configuration files for various types of tests. For example, see the [`_dev/test` folder](https://github.com/elastic/integrations/tree/main/packages/apache/data_stream/error/_dev/test) under the `apache/error` data stream. | ||
|
|
||
| The integrations have also [asset](https://github.com/elastic/elastic-package/blob/main/docs/howto/asset_testing.md) and [static](https://github.com/elastic/elastic-package/blob/main/docs/howto/static_testing.md) tests. They don't require config files, but configs can be used to mark them as optional. | ||
|
|
||
| ## Migration from Beats Modules | ||
|
|
||
| Filebeat and Metricbeat modules can be migrated over to Elastic Integrations. When migrating over, the same module in Filebeat and Metricbeat, related to the same observed product, can be combined into a single Elastic Integration. | ||
|
|
||
| [Learn more](/docs/import_from_beats.md) about how to migrate Filebeat and Metricbeat modules to Elastic Integrations. | ||
| **This content has moved. Please see the [Integrations Developer Guide](https://www.elastic.co/guide/en/integrations-developer/current/integration-definitions.html) instead.** |
Oops, something went wrong.