feat(openapi): rule parameters documentation for observability rules

[kdelemme]

Resolves https://github.com/elastic/actionable-observability/issues/11

Summary

This PR adds the openAPI documentation for the following observability rules:

• SLO burn rate rule
• Infra log threshold
• Infra inventory
• Infra metric threshold
• APM anomaly
• APM error count
• APM transaction duration
• APM transaction error rate
• Synthetics uptime TLS
• Synthetics uptime monitor status

[apmmachine]

🤖 GitHub comments

Expand to view the GitHub comments

Just comment with:

• /oblt-deploy : Deploy a Kibana instance using the Observability test environments.
• run elasticsearch-ci/docs : Re-trigger the docs validation. (use unformatted text in the comment!)

[elasticmachine]

Pinging @elastic/actionable-observability (Team: Actionable Observability)

[fkanout]

@kdelemme, I have two questions:

• How can I access these files once Kibana is running?
• If recall correctly, don't we need the URL in the API definition for each endpoint?

[elasticmachine]

Pinging @elastic/apm-ui (Team:APM)

[elasticmachine]

Pinging @elastic/uptime (Team:uptime)

[sorenlouv]

apm changes lgtm

[kdelemme]

@kdelemme, I have two questions:

• How can I access these files once Kibana is running?
• If recall correctly, don't we need the URL in the API definition for each endpoint?

@fkanout, you cannot access the output of these files. It's meant to be used by a script to bundle all the rules parameters. The script would search all yaml files starting with a # @kbn-doc-linker partial line.
Therefore, there are no need for the full OpenAPI specification of a regular API, response-ops only need the parameters of the rules.

If you want to check the schema individually, you can paste the content of the yaml file (starting after the first properties:) in this dummy spec into https://editor.swagger.io:

openapi: 3.0.1
info:
  title: dummy
  description: OpenAPI schema
  version: '1.0'
  contact:
    name: Actionable Observability Team
servers:
  - url: http://localhost:5601
    description: local
paths:
  /foo:
    get:
      summary: dummy
      operationId: dummy
      responses:
        '200':
          description: dummy
          content:
            application/json:
              schema:
                properties:
                  <PASTE_HERE>

[jcger]

I did some changes to the script so that it will load the spec using the file name only. Would it be ok for you to change it the root key is removed? x-pack/plugins/apm/server/routes/alerts/rule_types/docs/params_property_apm_anomaly.yaml would look like:

# @kbn-doc-linker partial

required:
  - windowSize
  - windowUnit
  - environment
  - anomalySeverityType
properties:
  serviceName:
    type: string
    description: The service name from APM
  transactionType:
    type: string
    description: The transaction type from APM
  windowSize:
    type: number
    example: 6
    description: The window size
  windowUnit:
    type: string
    description: The window size unit
    enum:
      - "m"
      - "h"
      - "d"
  environment:
    type: string
    description: The environment from APM
  anomalySeverityType:
    type: string
    description: The anomaly threshold value
    enum:
      - critical
      - major
      - minor
      - warning

It's feasible to make it work using the file name only but I'm thinking about leaving the header comment just to make it easier for developers to understand/trace what happens to this file. Any thoughts?

[kdelemme]

@jcger Done

[kibana-ci]

💚 Build Succeeded

• Buildkite Build
• Commit: a22d7a2

Metrics [docs]

Unknown metric groups

ESLint disabled line counts

id	before	after	diff
enterpriseSearch	19	21	+2
securitySolution	414	418	+4
total			+6

Total ESLint disabled count

id	before	after	diff
enterpriseSearch	20	22	+2
securitySolution	498	502	+4
total			+6

History

• 💚 Build #132082 succeeded d323ca6
• 💚 Build #131757 succeeded 5cf8b5e
• 💚 Build #131317 succeeded ddc3c4f
• 💚 Build #131101 succeeded 2324177

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

cc @kdelemme

[mohamedhamed-ahmed]

Infra changes LGTM!

[dominiqueclarke]

Uptime changes LGTM