From 2f7ee97117a9648fd78b02de78f39ff014c297a6 Mon Sep 17 00:00:00 2001 From: Arianna Laudazzi Date: Wed, 13 Aug 2025 08:19:42 +0200 Subject: [PATCH 1/8] Update doc guidelines --- docs/extend/documentation-guidelines.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/extend/documentation-guidelines.md b/docs/extend/documentation-guidelines.md index ea5d9cd7537..0283a585ccd 100644 --- a/docs/extend/documentation-guidelines.md +++ b/docs/extend/documentation-guidelines.md @@ -7,10 +7,10 @@ mapped_pages: The goal of each integration’s documentation is to: -* Help the reader understand the benefits the integration offers and how Elastic can help with their use case. Inform the reader of any requirements, including system compatibility, supported versions of third-party products, permissions needed, and more. -* Provide a comprehensive list of collected fields and the data and metric types for each. The reader can reference this information while evaluating the integration, interpreting collected data, or troubleshooting issues. -* Set the reader up for a successful installation and setup by connecting them with any other resources they’ll need. -* Each integration document should contain several sections, and you should use consistent headings to make it easier for a single user to evaluate and use multiple integrations. +* Describe the benefits the integration offers and how Elastic can help with different use cases. +* Specify requirements, including system compatibility, supported versions of third-party products, permissions needed, and more. +* Provide a list of collected fields, including data and metric types for each field. This information is useful while evaluating the integration, interpreting collected data, or troubleshooting issues. +* Each integration document should contain the following sections * [Overview](#idg-docs-guidelines-overview) * [Datastreams](#idg-docs-guidelines-datastreams) @@ -19,7 +19,6 @@ The goal of each integration’s documentation is to: * [Troubleshooting (optional)](#idg-docs-guidelines-troubleshooting) * [Reference](#idg-docs-guidelines-reference) - Some considerations when these documentation files are written at `_dev/build/docs/*.md`: * These files follow the Markdown syntax and leverage the use of [documentation templates](https://github.com/elastic/elastic-package/blob/main/docs/howto/add_package_readme.md). From fe873f28fabdb291a8949d40559061b301efaea8 Mon Sep 17 00:00:00 2001 From: Arianna Laudazzi Date: Wed, 13 Aug 2025 09:03:51 +0200 Subject: [PATCH 2/8] Update the Overview section --- docs/extend/documentation-guidelines.md | 41 ++++--------------------- 1 file changed, 6 insertions(+), 35 deletions(-) diff --git a/docs/extend/documentation-guidelines.md b/docs/extend/documentation-guidelines.md index 0283a585ccd..8473aa9a3b1 100644 --- a/docs/extend/documentation-guidelines.md +++ b/docs/extend/documentation-guidelines.md @@ -31,48 +31,19 @@ Some considerations when these documentation files are written at `_dev/build/do * In the documentation files (`_dev/build/docs/*.md`), `{{ url "getting-started-observability" "Elastic guide" }}` generates a link to the Observability Getting Started guide. - - ### Overview [idg-docs-guidelines-overview] -The overview section explains what the integration is, defines the third-party product that is providing data, establishes its relationship to the larger ecosystem of Elastic products, and helps the reader understand how it can be used to solve a tangible problem. - -The overview should answer the following questions: - -* What is the integration? -* What is the third-party product that is providing data? -* What can you do with it? - - * General description - * Basic example +The **Overview** section explains what the integration does, what the main uses cases are, and contains the following subsections: +* **Compatibility** + Indicates which versions, deployment methods, or architectures of the third party software this integration compatible with. -#### Template [_template] - -Use this template language as a starting point, replacing `` with details about the integration: - -```text -The integration allows you to monitor . is . - -Use the integration to . Then visualize that data in Kibana, create alerts to notify you if something goes wrong, and reference when troubleshooting an issue. - -For example, if you wanted to you could . Then you can by . -``` - - -#### Example [_example] - -```text -The AWS CloudFront integration allows you to monitor your AWS CloudFront usage. AWS CloudFront is a content delivery network (CDN) service. - -Use the AWS CloudFront integration to collect and parse logs related to content delivery. Then visualize that data in Kibana, create alerts to notify you if something goes wrong, and reference logs when troubleshooting an issue. - -For example, you could use the data from this integration to know when there are more than some number of failed requests for a single piece of content in a given time period. You could also use the data to troubleshoot the underlying issue by looking at additional context in the logs like the number of unique users (by IP address) who experienced the issue, the source of the request, and more. -``` +* **How it works** + Provides a high-level overview on how the integration collects data. -### Datastreams [idg-docs-guidelines-datastreams] +### What data does this integration collect? [idg-data-collected] The data streams section provides a high-level overview of the kind of data that is collected by the integration. This is helpful since it can be difficult to quickly derive an understanding from just the reference sections (since they’re so long). From 0367fc04cbcbdf0935c84f7f76ae2340729313f2 Mon Sep 17 00:00:00 2001 From: Arianna Laudazzi Date: Wed, 13 Aug 2025 09:15:36 +0200 Subject: [PATCH 3/8] Update the data-collected section --- docs/extend/documentation-guidelines.md | 47 ++----------------------- 1 file changed, 3 insertions(+), 44 deletions(-) diff --git a/docs/extend/documentation-guidelines.md b/docs/extend/documentation-guidelines.md index 8473aa9a3b1..4155d34339d 100644 --- a/docs/extend/documentation-guidelines.md +++ b/docs/extend/documentation-guidelines.md @@ -45,51 +45,10 @@ The **Overview** section explains what the integration does, what the main uses ### What data does this integration collect? [idg-data-collected] -The data streams section provides a high-level overview of the kind of data that is collected by the integration. This is helpful since it can be difficult to quickly derive an understanding from just the reference sections (since they’re so long). +This section should include: -The data streams section should include: - -* A list of the types of data streams collected by the integration -* A summary of each type of data stream included and a link to the relevant reference section: - - * Logs - * Metrics - -* Notes (optional) - - -#### Template [_template_2] - -Use this template language as a starting point, replacing `` with details about the integration: - -```text -## Data streams - -The integration collects two types of data streams: logs and metrics. - -**Logs** help you keep a record of events happening in . -Log data streams collected by the integration include and more. See more details in the [Metrics]<#metrics-reference>. - - - - -``` - - -#### Example [_example_2] - -```text -The System integration collects two types of data: logs and metrics. - -Logs help you keep a record of events that happen on your machine. Log data streams collected by the System integration include application, system, and security events on machines running Windows or auth and syslog events on machines running macOS or Linux. See more details in the Logs reference. - -Metrics give you insight into the state of the machine. Metric data streams collected by the System integration include CPU usage, load statistics, memory usage, information on network behavior, and more. See more details in the Metrics reference. - -You can enable and disable individual data streams. If all data streams are disabled and the System integration is still enabled, Fleet uses the default data streams. -``` +* The types of data collected by the integration +* Supported use cases ### Requirements [idg-docs-guidelines-requirements] From 430bcc90418b353526d4c6a690fe8067d6c39991 Mon Sep 17 00:00:00 2001 From: Arianna Laudazzi Date: Wed, 13 Aug 2025 11:11:54 +0200 Subject: [PATCH 4/8] Update the requirements section --- docs/extend/documentation-guidelines.md | 39 ++++--------------------- 1 file changed, 5 insertions(+), 34 deletions(-) diff --git a/docs/extend/documentation-guidelines.md b/docs/extend/documentation-guidelines.md index 4155d34339d..fb0f73e46a8 100644 --- a/docs/extend/documentation-guidelines.md +++ b/docs/extend/documentation-guidelines.md @@ -13,8 +13,8 @@ The goal of each integration’s documentation is to: * Each integration document should contain the following sections * [Overview](#idg-docs-guidelines-overview) - * [Datastreams](#idg-docs-guidelines-datastreams) - * [Requirements](#idg-docs-guidelines-requirements) + * [What data does this integration collect?](#idg-data-collected) + * [What do I need to use this integration?](#idg-requirements) * [Setup](#idg-docs-guidelines-setup) * [Troubleshooting (optional)](#idg-docs-guidelines-troubleshooting) * [Reference](#idg-docs-guidelines-reference) @@ -50,41 +50,12 @@ This section should include: * The types of data collected by the integration * Supported use cases +### What do I need to use this integration? [idg-requirements] -### Requirements [idg-docs-guidelines-requirements] - -The requirements section helps readers to confirm that the integration will work with their systems. +This section indicates what is required to use this integration: * Elastic prerequisites (for example, a self-managed or Cloud deployment) -* System compatibility -* Supported versions of third-party products -* Permissions needed -* Anything else that could block a user from successfully using the integration - - -#### Template [_template_3] - -Use this template language as a starting point, including any other requirements for the integration: - -```text -## Requirements - -You need Elasticsearch for storing and searching your data and Kibana for visualizing and managing it. -You can use our hosted Elasticsearch Service on Elastic Cloud, which is recommended, or self-manage the Elastic Stack on your own hardware. - - -``` - - -#### Example [_example_3] - -```text -You need Elasticsearch for storing and searching your data and Kibana for visualizing and managing it. You can use our hosted Elasticsearch Service on Elastic Cloud, which is recommended, or self-manage the Elastic Stack on your own hardware. - -Each data stream collects different kinds of metric data, which may require dedicated permissions to be fetched and may vary across operating systems. Details on the permissions needed for each data stream are available in the Metrics reference. -``` - -For a much more detailed example, refer to the [AWS integration requirements](https://github.com/elastic/integrations/blob/main/packages/aws/_dev/build/docs/README.md#requirements). +* Credentials or an admin account for the third-party software ### Setup [idg-docs-guidelines-setup] From f075729bcd2d251337a7122e7375d7c9dd8bf35b Mon Sep 17 00:00:00 2001 From: Arianna Laudazzi Date: Wed, 13 Aug 2025 11:23:49 +0200 Subject: [PATCH 5/8] Update the setup section --- docs/extend/documentation-guidelines.md | 51 ++++++++----------------- 1 file changed, 16 insertions(+), 35 deletions(-) diff --git a/docs/extend/documentation-guidelines.md b/docs/extend/documentation-guidelines.md index fb0f73e46a8..a71fd95b11f 100644 --- a/docs/extend/documentation-guidelines.md +++ b/docs/extend/documentation-guidelines.md @@ -12,11 +12,11 @@ The goal of each integration’s documentation is to: * Provide a list of collected fields, including data and metric types for each field. This information is useful while evaluating the integration, interpreting collected data, or troubleshooting issues. * Each integration document should contain the following sections - * [Overview](#idg-docs-guidelines-overview) + * [Overview](#idg-docs-overview) * [What data does this integration collect?](#idg-data-collected) * [What do I need to use this integration?](#idg-requirements) - * [Setup](#idg-docs-guidelines-setup) - * [Troubleshooting (optional)](#idg-docs-guidelines-troubleshooting) + * [How do I deploy this integration?](#idg-docs-setup) + * [Troubleshooting](#idg-docs-troubleshooting) * [Reference](#idg-docs-guidelines-reference) Some considerations when these documentation files are written at `_dev/build/docs/*.md`: @@ -31,7 +31,7 @@ Some considerations when these documentation files are written at `_dev/build/do * In the documentation files (`_dev/build/docs/*.md`), `{{ url "getting-started-observability" "Elastic guide" }}` generates a link to the Observability Getting Started guide. -### Overview [idg-docs-guidelines-overview] +### Overview [idg-docs-overview] The **Overview** section explains what the integration does, what the main uses cases are, and contains the following subsections: @@ -57,45 +57,26 @@ This section indicates what is required to use this integration: * Elastic prerequisites (for example, a self-managed or Cloud deployment) * Credentials or an admin account for the third-party software +### How do I deploy this integration? [idg-docs-setup] -### Setup [idg-docs-guidelines-setup] +This section refers to the Observability [Getting started guide](docs-content://solutions/observability/get-started.md) for generic, step-by-step instructions, and should also include any of the following additional setup instructions: -The setup section points the reader to the Observability [Getting started guide](docs-content://solutions/observability/get-started.md) for generic, step-by-step instructions. +**Onboard and configure** -This section should also include any additional setup instructions beyond what’s included in the guide, which may include instructions to update the configuration of a third-party service. For example, for the Cisco ASA integration, users need to configure their Cisco device following the [steps found in the Cisco documentation](https://documentation.meraki.com/General_Administration/Monitoring_and_Reporting/Syslog_Server_Overview_and_Configuration#Configuring_a_Syslog_Server). +* How do I install the Agent and deploy this integration? +* Which agent deployment methods are acceptable? Fleet? Standalone? +* Is agentless deployment supported for this integration? +* What data, input, fields, or authentication tokens must be configured during integration deployment? What values should they have? + +**Validation** + +* How can I test whether the integration is working? Include example commands or test files if applicable. ::::{note} When possible, use links to point to third-party documentation for configuring non-Elastic products since workflows may change without notice. :::: - - -#### Template [_template_4] - -Use this template language as a starting point, including any other setup instructions for the integration: - -```text -## Setup - - - -For step-by-step instructions on how to set up an integration, see the -{{ url "getting-started-observability" "Getting started" }} guide. - - -``` - - -#### Example [_example_4] - -```text -Before sending logs to Elastic from your Cisco device, you must configure your device according to <>. - -After you've configured your device, you can set up the Elastic integration. For step-by-step instructions on how to set up an integration, see the <> guide. -``` - - -### Troubleshooting (optional) [idg-docs-guidelines-troubleshooting] +### Troubleshooting [idg-docs-troubleshooting] The troubleshooting section is optional. It should contain information about special cases and exceptions that aren’t necessary for getting started or won’t be applicable to all users. From 99d9c3eed7bd720580429a91566cf6efdbd63ae5 Mon Sep 17 00:00:00 2001 From: Arianna Laudazzi Date: Wed, 13 Aug 2025 15:34:06 +0200 Subject: [PATCH 6/8] Update the troubleshooting section --- docs/extend/documentation-guidelines.md | 21 +-------------------- 1 file changed, 1 insertion(+), 20 deletions(-) diff --git a/docs/extend/documentation-guidelines.md b/docs/extend/documentation-guidelines.md index a71fd95b11f..e3bcdb7a57b 100644 --- a/docs/extend/documentation-guidelines.md +++ b/docs/extend/documentation-guidelines.md @@ -78,26 +78,7 @@ When possible, use links to point to third-party documentation for configuring n ### Troubleshooting [idg-docs-troubleshooting] -The troubleshooting section is optional. It should contain information about special cases and exceptions that aren’t necessary for getting started or won’t be applicable to all users. - - -#### Template [_template_5] - -There is no standard format for the troubleshooting section. - - -#### Example [_example_5] - -```text ->Note that certain data streams may access `/proc` to gather process information, ->and the resulting `ptrace_may_access()` call by the kernel to check for ->permissions can be blocked by ->[AppArmor and other LSM software](https://gitlab.com/apparmor/apparmor/wikis/TechnicalDoc_Proc_and_ptrace), even though the System module doesn't use `ptrace` directly. -> ->In addition, when running inside a container the proc filesystem directory of the host ->should be set using `system.hostfs` setting to `/hostfs`. -``` - +The troubleshooting section should include details specific to each input type, along with general guidance for resolving common issues encountered when deploying this integration. Whenever possible, link to the troubleshooting documentation provided by the third-party software. ### Reference [idg-docs-guidelines-reference] From f7a871ca3ef0b42ac0c270be2965b0c815c88f63 Mon Sep 17 00:00:00 2001 From: Arianna Laudazzi Date: Wed, 13 Aug 2025 15:45:55 +0200 Subject: [PATCH 7/8] Add the scaling section --- docs/extend/documentation-guidelines.md | 68 +++++++------------------ 1 file changed, 17 insertions(+), 51 deletions(-) diff --git a/docs/extend/documentation-guidelines.md b/docs/extend/documentation-guidelines.md index e3bcdb7a57b..7e5b6dfec04 100644 --- a/docs/extend/documentation-guidelines.md +++ b/docs/extend/documentation-guidelines.md @@ -17,7 +17,8 @@ The goal of each integration’s documentation is to: * [What do I need to use this integration?](#idg-requirements) * [How do I deploy this integration?](#idg-docs-setup) * [Troubleshooting](#idg-docs-troubleshooting) - * [Reference](#idg-docs-guidelines-reference) + * [Scaling](#idg-docs-scaling) + * [Reference](#idg-docs-reference) Some considerations when these documentation files are written at `_dev/build/docs/*.md`: @@ -59,7 +60,7 @@ This section indicates what is required to use this integration: ### How do I deploy this integration? [idg-docs-setup] -This section refers to the Observability [Getting started guide](docs-content://solutions/observability/get-started.md) for generic, step-by-step instructions, and should also include any of the following additional setup instructions: +This section refers to the Observability [Getting started guide](docs-content://solutions/observability/get-started.md) for generic, step-by-step instructions, and should also include the following additional setup instructions: **Onboard and configure** @@ -80,59 +81,24 @@ When possible, use links to point to third-party documentation for configuring n The troubleshooting section should include details specific to each input type, along with general guidance for resolving common issues encountered when deploying this integration. Whenever possible, link to the troubleshooting documentation provided by the third-party software. -### Reference [idg-docs-guidelines-reference] +### Scaling [idg-docs-scaling] -Readers might use the reference section while evaluating the integration, interpreting collected data, or troubleshooting issues. +Based on the input, this section should explain how to scale the integration and what are the best types of scaling architecture to use, including benchmarking recommendations. -There can be any number of reference sections (for example, `## Metrics reference`, `## Logs reference`). Each reference section can contain one or more subsections, such as one for each individual data stream (for example, `### Access Logs` and `### Error logs`). +### Reference [idg-docs-reference] + +There can be any number of reference sections, for example: + +* ECS Field Reference +* Metrics reference +* Logs reference +* Inputs used in this integration +* APIs used to collect data +* Changelog Each reference section should contain detailed information about: -* A list of the log or metric types we support within the integration and a link to the relevant third-party documentation. +* A list of the log or metric types supported within the integration and a link to the relevant third-party documentation. * (Optional) An example event in JSON format. * Exported fields for logs, metrics, and events with actual types (for example, `counters`, `gauges`, `histograms` vs. `longs` and `doubles`). Fields should be generated using the instructions in [Fine-tune the integration](https://github.com/elastic/integrations/blob/main/docs/fine_tune_integration.md). -* ML Modules jobs. - - -#### Template [_template_6] - -```text - -## reference - - -## - -The `` data stream provides events from of the following types: . - - - - - - -### Exported fields - - -``` - - -#### Example [_example_6] - -```text ->## Logs reference -> ->### PAN-OS -> ->The `panos` data stream provides events from Palo Alto Networks device of the following types: [GlobalProtect](https://docs.paloaltonetworks.com/pan-os/10-2/pan-os-admin/monitoring/use-syslog-for-monitoring/syslog-field-descriptions/globalprotect-log-fields), [HIP Match](https://docs.paloaltonetworks.com/pan-os/10-2/pan-os-admin/monitoring/use-syslog-for-monitoring/syslog-field-descriptions/hip-match-log-fields), [Threat](https://docs.paloaltonetworks.com/pan-os/10-2/pan-os-admin/monitoring/use-syslog-for-monitoring/syslog-field-descriptions/threat-log-fields), [Traffic](https://docs.paloaltonetworks.com/pan-os/10-2/pan-os-admin/monitoring/use-syslog-for-monitoring/syslog-field-descriptions/traffic-log-fields) and [User-ID](https://docs.paloaltonetworks.com/pan-os/10-2/pan-os-admin/monitoring/use-syslog-for-monitoring/syslog-field-descriptions/user-id-log-fields). -> ->#### Example -> ->An example event for `panos` looks as following: -> ->(code block) -> ->#### Exported fields -> ->(table of fields) -``` - +* ML Modules jobs. \ No newline at end of file From ed0ca68ac457b80d3c5e0f2300edeeb77a2b9455 Mon Sep 17 00:00:00 2001 From: Arianna Laudazzi Date: Mon, 18 Aug 2025 10:09:54 +0200 Subject: [PATCH 8/8] Integrate reviewer's comment --- docs/extend/documentation-guidelines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/extend/documentation-guidelines.md b/docs/extend/documentation-guidelines.md index 7e5b6dfec04..b6b04016545 100644 --- a/docs/extend/documentation-guidelines.md +++ b/docs/extend/documentation-guidelines.md @@ -17,7 +17,7 @@ The goal of each integration’s documentation is to: * [What do I need to use this integration?](#idg-requirements) * [How do I deploy this integration?](#idg-docs-setup) * [Troubleshooting](#idg-docs-troubleshooting) - * [Scaling](#idg-docs-scaling) + * [Performance and scaling](#idg-docs-performance-scaling) * [Reference](#idg-docs-reference) Some considerations when these documentation files are written at `_dev/build/docs/*.md`: @@ -81,7 +81,7 @@ When possible, use links to point to third-party documentation for configuring n The troubleshooting section should include details specific to each input type, along with general guidance for resolving common issues encountered when deploying this integration. Whenever possible, link to the troubleshooting documentation provided by the third-party software. -### Scaling [idg-docs-scaling] +### Performance and scaling [idg-docs-performance-scaling] Based on the input, this section should explain how to scale the integration and what are the best types of scaling architecture to use, including benchmarking recommendations.