elastic · mjwolf · Jul 1, 2025 · Jul 1, 2025 · Jul 1, 2025 · Jul 2, 2025
diff --git a/docs/howto/add_package_readme.md b/docs/howto/add_package_readme.md
@@ -6,11 +6,18 @@ Each package should have a README to explain all the details related to a given
 
 In order to help developers, this file is intended to be auto-generated by the `elastic-package build` command.
 The template used to generate the final README must be located at `_dev/build/docs/README.md`.
-This is the file that developers should be writting/updating.
+This is the file that developers should be writing/updating.
 
 As a note, there could be more than one readme file present in `_dev/build/docs/*.md`.
 `elastic-package build` command will render and write all those files into `docs/` folder.
 
+When generating README files, `elastic-package` automatically prepends a header comment to indicate that the file
+is auto-generated and should not be edited manually:
+```
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
+```
+
 # Markdown templates
 
 Files in `_dev/build/docs/*.md` follow Markdown syntax and they are rendered using [text/template](https://pkg.go.dev/text/template) package.

diff --git a/internal/docs/readme.go b/internal/docs/readme.go
@@ -27,6 +27,11 @@ type ReadmeFile struct {
 	Error    error
 }
 
+const (
+	doNotModifyStr string = `<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->`
+)
+
 // AreReadmesUpToDate function checks if all the .md readme files are up-to-date.
 func AreReadmesUpToDate() ([]ReadmeFile, error) {
 	packageRoot, err := packages.MustFindPackageRoot()
@@ -210,6 +215,7 @@ func renderReadme(fileName, packageRoot, templatePath string, linksMap linkMap)
 	}
 
 	var rendered bytes.Buffer
+	fmt.Fprintln(&rendered, doNotModifyStr)
 	err = t.Execute(&rendered, nil)
 	if err != nil {
 		return nil, fmt.Errorf("executing template failed: %w", err)

diff --git a/internal/docs/readme_test.go b/internal/docs/readme_test.go
@@ -30,7 +30,9 @@ func TestGenerateReadme(t *testing.T) {
 			readmeTemplateContents: `
 # README
 Introduction to the package`,
-			expected: `
+			expected: `<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
+
 # README
 Introduction to the package`,
 		},
@@ -83,7 +85,9 @@ func TestRenderReadmeWithLinks(t *testing.T) {
 Introduction to the package
 {{ url "foo" }}
 {{ url "foo" "Example" }}`,
-			expected: `
+			expected: `<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
+
 # README
 Introduction to the package
 http://www.example.com/bar
@@ -127,7 +131,9 @@ func TestRenderReadmeWithSampleEvent(t *testing.T) {
 # README
 Introduction to the package
 {{ event "example" }}`,
-			expected: `
+			expected: `<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
+
 # README
 Introduction to the package
 An example event for ` + "`example`" + ` looks as following:
@@ -184,7 +190,9 @@ func TesRenderReadmeWithFields(t *testing.T) {
 # README
 Introduction to the package
 {{ fields }}`,
-			expected: `
+			expected: `<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
+
 # README
 Introduction to the package
 **Exported fields**
@@ -207,7 +215,9 @@ Introduction to the package
 # README
 Introduction to the package
 {{ fields "example" }}`,
-			expected: `
+			expected: `<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
+
 # README
 Introduction to the package
 **Exported fields**
@@ -230,7 +240,9 @@ Introduction to the package
 # README
 Introduction to the package
 {{ fields "notexist" }}`,
-			expected: `
+			expected: `<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
+
 # README
 Introduction to the package
 **Exported fields**

diff --git a/internal/packages/archetype/_static/package-docs-readme.md.tmpl b/internal/packages/archetype/_static/package-docs-readme.md.tmpl
@@ -1,84 +1,118 @@
-<!-- Use this template language as a starting point, replacing {placeholder text} with details about the integration. -->
-<!-- Find more detailed documentation guidelines in https://github.com/elastic/integrations/blob/main/docs/documentation_guidelines.md -->
+<!-- This template can be used as a starting point for writing documentation for your new integration. For each section, fill in the details
+described in the comments.
 
-# {{.Manifest.Title}}
+Find more detailed documentation guidelines in https://www.elastic.co/docs/extend/integrations/documentation-guidelines
+-->
 
-<!-- The {{.Manifest.Title}} integration allows you to monitor {name of service}. {name of service} is {describe service}.
+# {{.Manifest.Title}} Integration for Elastic
 
-Use the {{.Manifest.Title}} integration to {purpose}. Then visualize that data in Kibana, create alerts to notify you if something goes wrong, and reference {data stream type} when troubleshooting an issue.
+## Overview
 
-For example, if you wanted to {sample use case} you could {action}. Then you can {visualize|alert|troubleshoot} by {action}. -->
+<!-- Complete this section with a short summary of what data this integration collects and what use cases it enables -->
+The {{.Manifest.Title}} integration for Elastic enables collection of ...
+This integration facilitates ...
 
-## Data streams
+### Compatibility
 
-<!-- The {{.Manifest.Title}} integration collects {one|two} type{s} of data streams: {logs and/or metrics}. -->
+<!-- Complete this section with information on what 3rd party software or hardware versions this integration is compatible with -->
+This integration is compatible with ...
 
-<!-- If applicable -->
-<!-- **Logs** help you keep a record of events happening in {service}.
-Log data streams collected by the {name} integration include {sample data stream(s)} and more. See more details in the [Logs](#logs-reference). -->
+### How it works
 
-<!-- If applicable -->
-<!-- **Metrics** give you insight into the state of {service}.
-Metric data streams collected by the {name} integration include {sample data stream(s)} and more. See more details in the [Metrics](#metrics-reference). -->
+<!-- Add a high level overview on how this integration works. For example, does it collect data from API calls or recieving data from a network or file.-->
 
-<!-- Optional: Any additional notes on data streams -->
+## What data does this integration collect?
 
-## Requirements
+<!-- Complete this section with information on what types of data the integration collects, and link to reference documentation if available -->
+The {{.Manifest.Title}} integration collects log messages of the following types:
+* ...
 
-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.
+### Supported use cases
 
-<!--
-	Optional: Other requirements including:
-	* System compatibility
-	* Supported versions of third-party products
-	* Permissions needed
-	* Anything else that could block a user from successfully using the integration
--->
+<!-- Add details on the use cases that can be enabled by using this integration. Explain why a user would want to install and use this integration. -->
 
-## Setup
+## What do I need to use this integration?
 
-<!-- Any prerequisite instructions -->
+<!-- List any vendor-specific prerequisites needed before starting to install the integration. -->
 
-For step-by-step instructions on how to set up an integration, see the
-[Getting started](https://www.elastic.co/guide/en/welcome-to-elastic/current/getting-started-observability.html) guide.
+## How do I deploy this integration?
 
-<!-- Additional set up instructions -->
+### Agent-based deployment
 
-<!-- If applicable -->
-<!-- ## Logs reference -->
+Elastic Agent must be installed. For more details, check the Elastic Agent [installation instructions](docs-content://reference/fleet/install-elastic-agents.md). You can install only one Elastic Agent per host.
 
-<!-- Repeat for each data stream of the current type -->
-<!-- ### {Data stream name}
+Elastic Agent is required to stream data from the syslog or log file receiver and ship the data to Elastic, where the events will then be processed via the integration's ingest pipelines.
+
+<!-- If agentless is available for this integration, we'll want to include that here as well. -->
+<!-- ### Agentless deployment
+
+Agentless deployments are only supported in Elastic Serverless and Elastic Cloud environments. Agentless deployments provide a means to ingest data while avoiding the orchestration, management, and maintenance needs associated with standard ingest infrastructure. Using an agentless deployment makes manual agent deployment unnecessary, allowing you to focus on your data instead of the agent that collects it.
+
+For more information, refer to [Agentless integrations](https://www.elastic.co/guide/en/serverless/current/security-agentless-integrations.html) and [Agentless integrations FAQ](https://www.elastic.co/guide/en/serverless/current/agentless-integration-troubleshooting.html) 
+-->
+
+### Onboard / configure
+
+<!-- List the steps that will need to be followed in order to completely set up a working inte completely set up a working integration.
+For integrations that support multiple input types, be sure to add steps for all inputs.
+-->
+
+### Validation
 
-The `{data stream name}` data stream provides events from {source} of the following types: {list types}. -->
+<!-- How can the user test whether the integration is working? Including example commands or test files if applicable -->
 
-<!-- Optional -->
-<!-- #### Example
+## Troubleshooting
 
-An example event for `{data stream name}` looks as following:
+For help with Elastic ingest tools, check [Common problems](https://www.elastic.co/docs/troubleshoot/ingest/fleet/common-problems).
 
-{code block with example} -->
+<!-- Add any vendor specific troubleshooting here.
 
-<!-- #### Exported fields
+Are there common issues or “gotchas” for deploying this integration? If so, how can they be resolved?
+If applicable, links to the third-party software’s troubleshooting documentation.
+-->
+
+## Scaling
 
-{insert table} -->
+For more information on architectures that can be used for scaling this integration, check the [Ingest Architectures](https://www.elastic.co/docs/manage-data/ingest/ingest-reference-architectures) documentation.
 
-<!-- If applicable -->
-<!-- ## Metrics reference -->
+<!-- Add any vendor specific scaling information here -->
+
+## Reference
 
 <!-- Repeat for each data stream of the current type -->
 <!-- ### {Data stream name}
 
-The `{data stream name}` data stream provides events from {source} of the following types: {list types}. -->
+The `{data stream name}` data stream provides events from {source} of the following types: {list types}.
+
+For each data_stream_name, include an optional summary of the datastream, the exported fields reference table and the sample event. -->
+
+<!-- The fields template function will be replaced by a generated list of all fields from the `fields/` directory of the data stream when building the integration. -->
+<!--
+#### {data stream name} fields
+
+To include a generated list of fields from the `fields/` directory, uncomment and use:
+(Remove the spaces between curly braces when using)
+{ { fields "data_stream_name" } }
-(Remove the spaces between curly braces when using)
-{ { fields "data_stream_name" } }
+{{ "{{ fields \"data_stream_name\" }}" }}
-(Remove the spaces between curly braces when using)
-{ { fields "data_stream_name" } }
+{{ "{{ fields \"data_stream_name\" }}" }}
 
-<!-- Optional -->
-<!-- #### Example
+-->
+
+<!-- The event template function will be replace by a sample event, taken from `sample_event.json`, when building this integration. -->
+<!--
+
+To include a sample event from `sample_event.json`, uncomment and use:
+(Remove the spaces between curly braces when using)
+{ { event "data_stream_name" } }
-(Remove the spaces between curly braces when using)
-{ { event "data_stream_name" } }
+{{ "{{ event \"data_stream_name\" }}" }}
-(Remove the spaces between curly braces when using)
-{ { event "data_stream_name" } }
+{{ "{{ event \"data_stream_name\" }}" }}
+
+-->
 
-An example event for `{data stream name}` looks as following:
+### Inputs used
 
-{code block with example} -->
+<!-- List inputs used in this integration, and link to the documentation -->
+These inputs can be used with this integration:
+* ...
 
-<!-- #### Exported fields
+### API usage
 
-{insert table} -->
+<!-- For integrations that use APIs to collect data, document all the APIs that are used, and link to relevent information -->
+These APIs are used with this integration:
+* ...
diff --git a/internal/packages/archetype/_static/package-sample-event.json.tmpl b/internal/packages/archetype/_static/package-sample-event.json.tmpl
@@ -0,0 +1,3 @@
+{
+  "description": "This is an example sample-event for {{.Manifest.Title}}. Replace it with a real sample event. Hint: If system tests exist, running `elastic-package test system --generate` will generate this file."
+}
diff --git a/internal/packages/archetype/package.go b/internal/packages/archetype/package.go
@@ -54,6 +54,14 @@ func createPackageInDir(packageDescriptor PackageDescriptor, cwd string) error {
 		return fmt.Errorf("can't render package README: %w", err)
 	}
 
+	if packageDescriptor.Manifest.Type != "content" {
+		logger.Debugf("Write docs readme to _dev")
+		err = renderResourceFile(packageDocsReadme, &packageDescriptor, filepath.Join(baseDir, "_dev", "build", "docs", "README.md"))
+		if err != nil {
+			return fmt.Errorf("can't render package README in _dev: %w", err)
+		}
+	}
+
 	if license := packageDescriptor.Manifest.Source.License; license != "" {
 		logger.Debugf("Write license file")
 		err = licenses.WriteTextToFile(license, filepath.Join(baseDir, "LICENSE.txt"))
@@ -78,6 +86,14 @@ func createPackageInDir(packageDescriptor PackageDescriptor, cwd string) error {
 		return fmt.Errorf("can't render sample screenshot: %w", err)
 	}
 
+	if packageDescriptor.Manifest.Type == "integration" {
+		logger.Debugf("Write sample sample_event")
+		err = renderResourceFile(packageSampleEvent, &packageDescriptor, filepath.Join(baseDir, "sample_event.json"))
+		if err != nil {
+			return fmt.Errorf("can't render sample sample_event: %w", err)
+		}
+	}
+
 	if packageDescriptor.Manifest.Type == "input" {
 		logger.Debugf("Write base fields")
 		err = renderResourceFile(fieldsBaseTemplate, &packageDescriptor, filepath.Join(baseDir, "fields", "base-fields.yml"))

diff --git a/internal/packages/archetype/resources.go b/internal/packages/archetype/resources.go
@@ -33,6 +33,9 @@ var packageImgSampleIcon []byte
 //go:embed _static/sampleScreenshot.png.b64
 var packageImgSampleScreenshot string
 
+//go:embed _static/package-sample-event.json.tmpl
+var packageSampleEvent string
+
 // Input Package templates
 
 //go:embed _static/input-package-agent-config.yml.tmpl

diff --git a/test/packages/false_positives/cisco_asa/docs/README.md b/test/packages/false_positives/cisco_asa/docs/README.md
@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Cisco ASA Integration
 
 This integration is for Cisco ASA network device's logs. It includes the following

diff --git a/test/packages/false_positives/docker_failing_test_service/docs/README.md b/test/packages/false_positives/docker_failing_test_service/docs/README.md
@@ -1 +1,3 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Test integration
diff --git a/test/packages/false_positives/httpjson_false_positive_asserts/docs/README.md b/test/packages/false_positives/httpjson_false_positive_asserts/docs/README.md
@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Custom API input integration
 
 The custom API input integration is used to ingest data from custom RESTful API's that do not currently have an existing integration.

diff --git a/test/packages/false_positives/long_integers_as_json_numbers/docs/README.md b/test/packages/false_positives/long_integers_as_json_numbers/docs/README.md
@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Long Integer Tests
 
 An example event for `test` looks as following:

diff --git a/test/packages/false_positives/nginx_missing_deployer/docs/README.md b/test/packages/false_positives/nginx_missing_deployer/docs/README.md
@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Nginx Integration
 
 This integration periodically fetches metrics from [Nginx](https://nginx.org/) servers. It can parse access and error

diff --git a/test/packages/false_positives/prometheus/docs/README.md b/test/packages/false_positives/prometheus/docs/README.md
@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Prometheus Integration
 
 This integration can collect metrics from:

diff --git a/test/packages/other/ecs_mappings/docs/README.md b/test/packages/other/ecs_mappings/docs/README.md
@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # ECS Mappings Test
 
 Test package to verify support for ECS mappings available to integrations running on stack version 8.13.0 and later.

diff --git a/test/packages/other/fields_tests/docs/README.md b/test/packages/other/fields_tests/docs/README.md
@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Fields Tests
 
 An example event for `first` looks as following:

diff --git a/test/packages/other/imported_mappings_tests/docs/README.md b/test/packages/other/imported_mappings_tests/docs/README.md
@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Imported Mappings Tests
 
 An example event for `first` looks as following:

diff --git a/test/packages/other/long_integers/docs/README.md b/test/packages/other/long_integers/docs/README.md
@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Long Integer Tests
 
 An example event for `test` looks as following:

diff --git a/test/packages/other/readme_links/docs/README.md b/test/packages/other/readme_links/docs/README.md
@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Readme Links
 
 Examples of links:

diff --git a/test/packages/other/with_links/docs/README.md b/test/packages/other/with_links/docs/README.md
@@ -1,3 +1,5 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # Imported Mappings Tests
 
 An example event for `first` looks as following: