Doc: Distinguish between elastic-supported and community-supported plugins

[karenzone]

Can we use the :default_plugin: setting to accurately distinguish between elastic-supported and community-supported plugins.?

• Are all plugins that are installed by default elastic-supported plugins?
• Are there any elastic-supported plugins that are not installed by default?

~We can most likely implement this initiative by updating plugin headers to show different text based on the :default_plugin: value.~ Update: This approach won't work because there's not a 1:1 relationship between default plugins and level of support. I'm trying something different as noted in comments.

Proposal: Phased rollout

Follows the Logstash Plugins support matrix. If we use this approach, let's consider a phased rollout:

• Tier 1 plugins (72 total)
• Tier 2 plugins (17 total)
• Community

Possible next steps

We could consider adding the configuration to [plugins-metadata.json](https://github.com/elastic/logstash/blob/main/rakelib/plugins-metadata.json), but we'd still need to clear the setting in each doc source file. So there's probably no value in that approach.

[karenzone]

@flexitrev: Here's the issue we discussed. Please feel free to add to it.

Who can answer these questions:

• Are all plugins that are installed by default elastic-supported plugins?
• Are there any elastic-supported plugins that are not installed by default?

[karenzone]

cc:/ @roaksoax @jsvd

[flexitrev]

I'm not sure we need to answer the default set of installed plugin question. Even if we do install an unsupported plugin or don't, that can change over time. What our documentation should reflect is what's currently supported. Or better, what versions are supported

[karenzone]

For sure, docs should reflect what's currently supported. I'm trying to figure out if/how we can use flags such as default_plugin to trigger conditional content rather than trying to manage it all manually.

[flexitrev]

@roaksoax would default_plugin work to distinguish supported/unsupported plugins?

[roaksoax]

@flexitrev @karenzone I don't think that that we can use default_plugin to differentiate whether a plugin is supported or unsupported. We do have unsupported plugins that are shipped by default in logstash, meaning they are set as default_plugin.

Either we expand the metadata to include that information, or we leverage the same mechanism as we do for the support matrix, which is to rely on the spreadsheet.

[karenzone]

@karenzone: Related: https://docs.elastic.co/integrations/support

[karenzone]

Related [test] PRs:

• 16206

  Adds support for support level to plugin header files in logstash repo

• https://github.com/elastic/logstash-docs/pull/1673 Adds support level attributes to select generated plugin docs for validation

To test:

• Check out the changed files from both repos, and run docbldlsx --open. (PR checking doesn't help us here because the change spans multiple repos.)

Sample output:

[karenzone]

@jsvd Let's discuss!

[jsvd]

I would like to avoid having more than 1 place where we state what's commercially supported. The plugin reference docs explain how any/a user uses the plugin: if it needs to be installed or is bundled with logstash (:default-plugin: attr), what are its settings, and guidance for its use. The support matrix is the place Elastic customers (current or prospect) can find out what is commercially supported if they have a subscription with Elastic. I'd prefer to keep this separation clean and avoid two sources of truth.

The Elastic integrations are, afaik, the only occurrence of the commercial support of a feature/product being defined outside of support.elastic.co.

[karenzone]

This was an ask from @flexitrev and @roaksoax in a move toward more transparency so that users would know what level of support to expect before they use a plugin.

[flexitrev]

This seems necessary to clear up current confusion about support for various plugins. Requiring customers to go to a different place to understand support than in documentation is a bad customer experience. I think being explicit about the plugins that are supported and therefore actively maintained is good practice.

[lucabelluccini]

At the moment I think we only tell if the Logstash plugin is installed by default or not. But we do not tell anything about who is maintaining it and what is the support we offer.

About "duplication", it's true having in the docs AND support matrix to maintain is a duplication, but we can solve it:

• Have a proper automation/pipeline where the support matrix and docs are both generated from the plugins metadata
• If the above is not possible, make the Support Matrix point to the plugin docs section (which will be mandatory) about the support level - and make the Support Matrix only define the Support level "meaning". The plugins docs will tell the support level.

Note integrations are not the only "product" not being explicitly in the Support Matrix. The APM Agents are another example.

[karenzone]

Update

This project is blocked pending some decisions.

I'm closing related PRs for now:

• https://github.com/elastic/logstash/pull/16206
• https://github.com/elastic/logstash-docs/pull/1673