From da11b1ff3e3e6ccd0fe1f4a103e9ae34c1c8ac19 Mon Sep 17 00:00:00 2001 From: Karen Metts Date: Fri, 11 Oct 2024 13:18:54 -0400 Subject: [PATCH 01/15] Logstash API spec - first pass --- docs/static/spec/openapi/starter copy.yaml | 59 ++++++++++++++++++++++ docs/static/spec/openapi/starter.yaml | 59 ++++++++++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 docs/static/spec/openapi/starter copy.yaml create mode 100644 docs/static/spec/openapi/starter.yaml diff --git a/docs/static/spec/openapi/starter copy.yaml b/docs/static/spec/openapi/starter copy.yaml new file mode 100644 index 00000000000..2b3b9cc94f1 --- /dev/null +++ b/docs/static/spec/openapi/starter copy.yaml @@ -0,0 +1,59 @@ + +openapi: 3.1.0 +info: + title: Observability Intake Serverless APIs + description: | + **Technical preview** + This functionality is in technical preview and may be changed or removed in a future release. + Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. + + ## Documentation source and versions + This documentation is derived from a private repository. + It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/). + version: '0.1' + x-doc-license: + name: Attribution-NonCommercial-NoDerivatives 4.0 International + url: https://creativecommons.org/licenses/by-nc-nd/4.0/ + x-feedbackLink: + label: Feedback + url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+ +servers: + - url: / +security: + - apiKeyAuth: [] +tags: + - name: event intake + description: >- + The events intake API is the internal protocol that APM agents use to talk to the Elastic Stack. + x-displayName: APM event intake + - name: opentelemetry intake + description: > + The OpenTelemetry intake API uses the OpenTelemetry Protocol (OTLP) to send traces, metrics, and logs to the Elastic Stack. + OTLP is the default transfer protocol for OpenTelemetry and is supported natively. + The Observability Intake Serverless API supports two OTLP communication protocols on the same port: OTLP/HTTP (protobuf) and OTLP/gRPC. + x-displayName: APM OpenTelemetry intake + - name: service info + description: These APIs provide information that can be used by Elastic APM agents, for example. + x-displayName: Observability Intake Serverless APIs information +paths: + /: + $ref: paths/service_version.yaml + /opentelemetry.proto.collector.metrics.v1.MetricsService/Export: + $ref: paths/opentelemetry.proto.collector.metrics.v1.MetricsService_Export.yaml + /opentelemetry.proto.collector.trace.v1.TraceService/Export: + $ref: paths/opentelemetry.proto.collector.trace.v1.TraceService_Export.yaml + /opentelemetry.proto.collector.logs.v1.LogsService/Export: + $ref: paths/opentelemetry.proto.collector.logs.v1.LogsService_Export.yaml + /v1/metrics: + $ref: paths/v1_metrics.yaml + /v1/traces: + $ref: paths/v1_traces.yaml + /v1/logs: + $ref: paths/v1_logs.yaml +components: + securitySchemes: + apiKeyAuth: + type: apiKey + in: header + name: Authorization + description: 'e.g. Authorization: ApiKey base64AccessApiKey' diff --git a/docs/static/spec/openapi/starter.yaml b/docs/static/spec/openapi/starter.yaml new file mode 100644 index 00000000000..2b3b9cc94f1 --- /dev/null +++ b/docs/static/spec/openapi/starter.yaml @@ -0,0 +1,59 @@ + +openapi: 3.1.0 +info: + title: Observability Intake Serverless APIs + description: | + **Technical preview** + This functionality is in technical preview and may be changed or removed in a future release. + Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. + + ## Documentation source and versions + This documentation is derived from a private repository. + It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/). + version: '0.1' + x-doc-license: + name: Attribution-NonCommercial-NoDerivatives 4.0 International + url: https://creativecommons.org/licenses/by-nc-nd/4.0/ + x-feedbackLink: + label: Feedback + url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+ +servers: + - url: / +security: + - apiKeyAuth: [] +tags: + - name: event intake + description: >- + The events intake API is the internal protocol that APM agents use to talk to the Elastic Stack. + x-displayName: APM event intake + - name: opentelemetry intake + description: > + The OpenTelemetry intake API uses the OpenTelemetry Protocol (OTLP) to send traces, metrics, and logs to the Elastic Stack. + OTLP is the default transfer protocol for OpenTelemetry and is supported natively. + The Observability Intake Serverless API supports two OTLP communication protocols on the same port: OTLP/HTTP (protobuf) and OTLP/gRPC. + x-displayName: APM OpenTelemetry intake + - name: service info + description: These APIs provide information that can be used by Elastic APM agents, for example. + x-displayName: Observability Intake Serverless APIs information +paths: + /: + $ref: paths/service_version.yaml + /opentelemetry.proto.collector.metrics.v1.MetricsService/Export: + $ref: paths/opentelemetry.proto.collector.metrics.v1.MetricsService_Export.yaml + /opentelemetry.proto.collector.trace.v1.TraceService/Export: + $ref: paths/opentelemetry.proto.collector.trace.v1.TraceService_Export.yaml + /opentelemetry.proto.collector.logs.v1.LogsService/Export: + $ref: paths/opentelemetry.proto.collector.logs.v1.LogsService_Export.yaml + /v1/metrics: + $ref: paths/v1_metrics.yaml + /v1/traces: + $ref: paths/v1_traces.yaml + /v1/logs: + $ref: paths/v1_logs.yaml +components: + securitySchemes: + apiKeyAuth: + type: apiKey + in: header + name: Authorization + description: 'e.g. Authorization: ApiKey base64AccessApiKey' From 7d3954b820e1189a5ff27e4178c6706a86d25598 Mon Sep 17 00:00:00 2001 From: Karen Metts <35154725+karenzone@users.noreply.github.com> Date: Fri, 11 Oct 2024 13:22:59 -0400 Subject: [PATCH 02/15] Delete docs/static/spec/openapi/starter copy.yaml --- docs/static/spec/openapi/starter copy.yaml | 59 ---------------------- 1 file changed, 59 deletions(-) delete mode 100644 docs/static/spec/openapi/starter copy.yaml diff --git a/docs/static/spec/openapi/starter copy.yaml b/docs/static/spec/openapi/starter copy.yaml deleted file mode 100644 index 2b3b9cc94f1..00000000000 --- a/docs/static/spec/openapi/starter copy.yaml +++ /dev/null @@ -1,59 +0,0 @@ - -openapi: 3.1.0 -info: - title: Observability Intake Serverless APIs - description: | - **Technical preview** - This functionality is in technical preview and may be changed or removed in a future release. - Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. - - ## Documentation source and versions - This documentation is derived from a private repository. - It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/). - version: '0.1' - x-doc-license: - name: Attribution-NonCommercial-NoDerivatives 4.0 International - url: https://creativecommons.org/licenses/by-nc-nd/4.0/ - x-feedbackLink: - label: Feedback - url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+ -servers: - - url: / -security: - - apiKeyAuth: [] -tags: - - name: event intake - description: >- - The events intake API is the internal protocol that APM agents use to talk to the Elastic Stack. - x-displayName: APM event intake - - name: opentelemetry intake - description: > - The OpenTelemetry intake API uses the OpenTelemetry Protocol (OTLP) to send traces, metrics, and logs to the Elastic Stack. - OTLP is the default transfer protocol for OpenTelemetry and is supported natively. - The Observability Intake Serverless API supports two OTLP communication protocols on the same port: OTLP/HTTP (protobuf) and OTLP/gRPC. - x-displayName: APM OpenTelemetry intake - - name: service info - description: These APIs provide information that can be used by Elastic APM agents, for example. - x-displayName: Observability Intake Serverless APIs information -paths: - /: - $ref: paths/service_version.yaml - /opentelemetry.proto.collector.metrics.v1.MetricsService/Export: - $ref: paths/opentelemetry.proto.collector.metrics.v1.MetricsService_Export.yaml - /opentelemetry.proto.collector.trace.v1.TraceService/Export: - $ref: paths/opentelemetry.proto.collector.trace.v1.TraceService_Export.yaml - /opentelemetry.proto.collector.logs.v1.LogsService/Export: - $ref: paths/opentelemetry.proto.collector.logs.v1.LogsService_Export.yaml - /v1/metrics: - $ref: paths/v1_metrics.yaml - /v1/traces: - $ref: paths/v1_traces.yaml - /v1/logs: - $ref: paths/v1_logs.yaml -components: - securitySchemes: - apiKeyAuth: - type: apiKey - in: header - name: Authorization - description: 'e.g. Authorization: ApiKey base64AccessApiKey' From 51c9e66f619e5e32e03509c6bb4e27c3af7baeb0 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 11 Oct 2024 11:23:30 -0700 Subject: [PATCH 03/15] Plugins info API draft --- docs/static/spec/openapi/starter.yaml | 83 +++++++++++++-------------- 1 file changed, 41 insertions(+), 42 deletions(-) diff --git a/docs/static/spec/openapi/starter.yaml b/docs/static/spec/openapi/starter.yaml index 2b3b9cc94f1..f7a59cac5ad 100644 --- a/docs/static/spec/openapi/starter.yaml +++ b/docs/static/spec/openapi/starter.yaml @@ -1,16 +1,23 @@ openapi: 3.1.0 info: - title: Observability Intake Serverless APIs + title: Logstash APIs description: | - **Technical preview** - This functionality is in technical preview and may be changed or removed in a future release. - Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. + When you run Logstash, it automatically captures runtime metrics that you can use to monitor the health and performance of your Logstash deployment. + The metrics collected by Logstash include: + + - Logstash node info, like pipeline settings, OS info, and JVM info. + - Plugin info, including a list of installed plugins. + - Node stats, like JVM stats, process stats, event-related stats, and pipeline runtime stats. + - Hot threads. + + The APIs that retrieve these metrics are available by default without requiring any extra configuration. ## Documentation source and versions - This documentation is derived from a private repository. + + This documentation is derived from the `main` branch of the [logstash](https://github.com/elastic/logstash) repository. It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/). - version: '0.1' + version: '1.0' x-doc-license: name: Attribution-NonCommercial-NoDerivatives 4.0 International url: https://creativecommons.org/licenses/by-nc-nd/4.0/ @@ -21,39 +28,31 @@ servers: - url: / security: - apiKeyAuth: [] -tags: - - name: event intake - description: >- - The events intake API is the internal protocol that APM agents use to talk to the Elastic Stack. - x-displayName: APM event intake - - name: opentelemetry intake - description: > - The OpenTelemetry intake API uses the OpenTelemetry Protocol (OTLP) to send traces, metrics, and logs to the Elastic Stack. - OTLP is the default transfer protocol for OpenTelemetry and is supported natively. - The Observability Intake Serverless API supports two OTLP communication protocols on the same port: OTLP/HTTP (protobuf) and OTLP/gRPC. - x-displayName: APM OpenTelemetry intake - - name: service info - description: These APIs provide information that can be used by Elastic APM agents, for example. - x-displayName: Observability Intake Serverless APIs information -paths: - /: - $ref: paths/service_version.yaml - /opentelemetry.proto.collector.metrics.v1.MetricsService/Export: - $ref: paths/opentelemetry.proto.collector.metrics.v1.MetricsService_Export.yaml - /opentelemetry.proto.collector.trace.v1.TraceService/Export: - $ref: paths/opentelemetry.proto.collector.trace.v1.TraceService_Export.yaml - /opentelemetry.proto.collector.logs.v1.LogsService/Export: - $ref: paths/opentelemetry.proto.collector.logs.v1.LogsService_Export.yaml - /v1/metrics: - $ref: paths/v1_metrics.yaml - /v1/traces: - $ref: paths/v1_traces.yaml - /v1/logs: - $ref: paths/v1_logs.yaml -components: - securitySchemes: - apiKeyAuth: - type: apiKey - in: header - name: Authorization - description: 'e.g. Authorization: ApiKey base64AccessApiKey' +paths: + /_node/plugins: + get: + summary: Get plugin info + description: > + Get information about all Logstash plugins that are currently installed. + This API basically returns the output of running the `bin/logstash-plugin list --verbose` command. + operationId: nodePlugins + parameters: + - name: pretty + in: query + schema: + type: boolean + description: > + If you append `?pretty=true` to the request, the JSON returned will be pretty formatted (use it for debugging only!). + responses: + '200': + description: Indicates a successful call + content: + application/json: + examples: + nodePluginsExample1: + total: 1 + plugins: + - name: logstash-codec-cef + version: 4.1.2 + + From 0cd5d16f62366163178e0afb9d4528d0c8896f2a Mon Sep 17 00:00:00 2001 From: Karen Metts Date: Fri, 25 Oct 2024 10:45:54 -0400 Subject: [PATCH 04/15] More work on APIs --- docs/static/spec/openapi/starter.yaml | 125 +++++++++++++++++++++++++- 1 file changed, 123 insertions(+), 2 deletions(-) diff --git a/docs/static/spec/openapi/starter.yaml b/docs/static/spec/openapi/starter.yaml index f7a59cac5ad..03774fb2ab7 100644 --- a/docs/static/spec/openapi/starter.yaml +++ b/docs/static/spec/openapi/starter.yaml @@ -29,12 +29,15 @@ servers: security: - apiKeyAuth: [] paths: + +## Node info API + /_node/plugins: get: - summary: Get plugin info + summary: Get node info description: > Get information about all Logstash plugins that are currently installed. - This API basically returns the output of running the `bin/logstash-plugin list --verbose` command. + This API returns the output of running the `bin/logstash-plugin list --verbose` command. operationId: nodePlugins parameters: - name: pretty @@ -54,5 +57,123 @@ paths: plugins: - name: logstash-codec-cef version: 4.1.2 + + + + /_node/plugins: + get: + summary: Get plugin info + description: > + Get information about all Logstash plugins that are currently installed. + This API returns the output of running the `bin/logstash-plugin list --verbose` command. + operationId: nodePlugins + parameters: + - name: pretty + in: query + schema: + type: boolean + description: > + If you append `?pretty=true` to the request, the JSON returned will be pretty formatted (use it for debugging only!). + responses: + '200': + description: Indicates a successful call + content: + application/json: + examples: + nodePluginsExample1: + total: 1 + plugins: + - name: logstash-codec-cef + version: 6.2.7 +## Plugins info API (LISA) + + /_node/plugins: + get: + summary: Get plugin info + description: > + Get information about all Logstash plugins that are currently installed. + This API returns the output of running the `bin/logstash-plugin list --verbose` command. + operationId: nodePlugins + parameters: + - name: pretty + in: query + schema: + type: boolean + description: > + If you append `?pretty=true` to the request, the JSON returned will be pretty formatted (use it for debugging only!). + responses: + '200': + description: Indicates a successful call + content: + application/json: + examples: + nodePluginsExample1: + total: 1 + plugins: + - name: logstash-codec-cef + version: 6.2.7 +## Node stats API + + /_node/plugins: + get: + summary: Get node info + description: > + Get information about all Logstash plugins that are currently installed. + This API returns the output of running the `bin/logstash-plugin list --verbose` command. + operationId: nodePlugins + parameters: + - name: pretty + in: query + schema: + type: boolean + description: > + If you append `?pretty=true` to the request, the JSON returned will be pretty formatted (use it for debugging only!). + responses: + '200': + description: Indicates a successful call + content: + application/json: + examples: + nodePluginsExample1: + total: 1 + plugins: + - name: logstash-codec-cef + version: 4.1.2 + + +## Hot Threads API + + /_node/hot_threads: + get: + summary: Get hot threads + description: > + Get information about current hot threads for Logstash. + A hot thread is a Java thread that has high CPU usage and takes longer than normal to execute. + operationId: nodeHot_threads + parameters: + - name: pretty + in: query + schema: + type: boolean + description: > + If you append `?pretty=true` to the request, the JSON returned will be pretty formatted (use it for debugging only!). + - name: human + in: query + schema: + type: boolean + description: > + If you append `?human=true` to the request, the JSON returned will be in a human-readable format. + + responses: + '200': + description: Indicates a successful call + content: + application/json: + examples: + nodePluginsExample1: + total: 1 + plugins: + - name: logstash-codec-cef + version: 4.1.2 From 64863e146c1f81a5a3ca04802e82e42bffcf4375 Mon Sep 17 00:00:00 2001 From: Karen Metts Date: Fri, 27 Dec 2024 12:19:53 -0500 Subject: [PATCH 05/15] Add framework for node and hot threads --- docs/static/spec/openapi/starter.yaml | 117 +++++++++----------------- 1 file changed, 41 insertions(+), 76 deletions(-) diff --git a/docs/static/spec/openapi/starter.yaml b/docs/static/spec/openapi/starter.yaml index 03774fb2ab7..f13a2f67973 100644 --- a/docs/static/spec/openapi/starter.yaml +++ b/docs/static/spec/openapi/starter.yaml @@ -28,44 +28,20 @@ servers: - url: / security: - apiKeyAuth: [] -paths: -## Node info API - /_node/plugins: +paths: + /_node/: get: summary: Get node info description: > - Get information about all Logstash plugins that are currently installed. - This API returns the output of running the `bin/logstash-plugin list --verbose` command. - operationId: nodePlugins - parameters: - - name: pretty - in: query - schema: - type: boolean - description: > - If you append `?pretty=true` to the request, the JSON returned will be pretty formatted (use it for debugging only!). - responses: - '200': - description: Indicates a successful call - content: - application/json: - examples: - nodePluginsExample1: - total: 1 - plugins: - - name: logstash-codec-cef - version: 4.1.2 + Get information about Logstash nodes, where `` (optional) specifies the types of node info you want returned. + You can limit the info that is returned by combining any of these types in a comma-separated list: + - `pipelines` + - `os` + - `jvm` - - /_node/plugins: - get: - summary: Get plugin info - description: > - Get information about all Logstash plugins that are currently installed. - This API returns the output of running the `bin/logstash-plugin list --verbose` command. operationId: nodePlugins parameters: - name: pretty @@ -73,7 +49,7 @@ paths: schema: type: boolean description: > - If you append `?pretty=true` to the request, the JSON returned will be pretty formatted (use it for debugging only!). + If you append `?pretty=true` to the request, the JSON returned will be pretty formatted. Use it for debugging only! responses: '200': description: Indicates a successful call @@ -84,16 +60,13 @@ paths: total: 1 plugins: - name: logstash-codec-cef - version: 6.2.7 - -## Plugins info API (LISA) - + version: 4.1.2 /_node/plugins: get: summary: Get plugin info description: > Get information about all Logstash plugins that are currently installed. - This API returns the output of running the `bin/logstash-plugin list --verbose` command. + This API returns the same output you get by running the `bin/logstash-plugin list --verbose` command. operationId: nodePlugins parameters: - name: pretty @@ -101,35 +74,7 @@ paths: schema: type: boolean description: > - If you append `?pretty=true` to the request, the JSON returned will be pretty formatted (use it for debugging only!). - responses: - '200': - description: Indicates a successful call - content: - application/json: - examples: - nodePluginsExample1: - total: 1 - plugins: - - name: logstash-codec-cef - version: 6.2.7 - -## Node stats API - - /_node/plugins: - get: - summary: Get node info - description: > - Get information about all Logstash plugins that are currently installed. - This API returns the output of running the `bin/logstash-plugin list --verbose` command. - operationId: nodePlugins - parameters: - - name: pretty - in: query - schema: - type: boolean - description: > - If you append `?pretty=true` to the request, the JSON returned will be pretty formatted (use it for debugging only!). + If you append `?pretty=true` to the request, the JSON returned will be pretty formatted. Use it for debugging only! responses: '200': description: Indicates a successful call @@ -142,9 +87,6 @@ paths: - name: logstash-codec-cef version: 4.1.2 - -## Hot Threads API - /_node/hot_threads: get: summary: Get hot threads @@ -153,27 +95,50 @@ paths: A hot thread is a Java thread that has high CPU usage and takes longer than normal to execute. operationId: nodeHot_threads parameters: + - name: threads + in: query + schema: + type: integer + description: > + The number of hot threads to return. The default is 10. + - name: stacktrace_size + in: query + schema: + type: integer + description: > + The depth of the stack trace to report for each thread. The default is 50. + - name: ignore_idle_threads + in: query + schema: + type: boolean + description: > + If true, does not return idle threads. The default is `true`. - name: pretty in: query schema: type: boolean description: > - If you append `?pretty=true` to the request, the JSON returned will be pretty formatted (use it for debugging only!). + If you append `?pretty=true` to the request, the JSON returned will be pretty formatted. Use it for debugging only! - name: human in: query schema: type: boolean description: > If you append `?human=true` to the request, the JSON returned will be in a human-readable format. - responses: '200': description: Indicates a successful call content: application/json: examples: - nodePluginsExample1: - total: 1 - plugins: - - name: logstash-codec-cef - version: 4.1.2 + nodeHotThreadsExample1: + hot_threads: + - time: 2025-01-06T18:25:28-07:00 + busiest_threads: 3 + threads: + name: Ruby-0-Thread-7 + percent_of_cpu_time: 0.0 + state: timed_waiting + path: /path/to/logstash-8.17.0/vendor/bundle/jruby/1.9/gems/puma-2.16.0-java/lib/puma/thread_pool.rb:187 + traces: java.lang.Object.wait(Native Method)", "org.jruby.RubyThread.sleep(RubyThread.java:1002)", "org.jruby.RubyKernel.sleep(RubyKernel.java:803) + From 488083a551f829b832b2664b6f9b306cec820adc Mon Sep 17 00:00:00 2001 From: Karen Metts Date: Fri, 27 Dec 2024 14:59:53 -0500 Subject: [PATCH 06/15] Add more content --- docs/static/spec/openapi/starter.yaml | 134 +++++++++++++++++++++++--- 1 file changed, 121 insertions(+), 13 deletions(-) diff --git a/docs/static/spec/openapi/starter.yaml b/docs/static/spec/openapi/starter.yaml index f13a2f67973..f525bad7010 100644 --- a/docs/static/spec/openapi/starter.yaml +++ b/docs/static/spec/openapi/starter.yaml @@ -10,6 +10,7 @@ info: - Plugin info, including a list of installed plugins. - Node stats, like JVM stats, process stats, event-related stats, and pipeline runtime stats. - Hot threads. + - Health report. The APIs that retrieve these metrics are available by default without requiring any extra configuration. @@ -28,8 +29,6 @@ servers: - url: / security: - apiKeyAuth: [] - - paths: /_node/: get: @@ -38,11 +37,10 @@ paths: Get information about Logstash nodes, where `` (optional) specifies the types of node info you want returned. You can limit the info that is returned by combining any of these types in a comma-separated list: - - `pipelines` - - `os` - - `jvm` - - operationId: nodePlugins + - `pipelines`. + - `os`. + - `jvm`. + operationId: nodeInfo parameters: - name: pretty in: query @@ -56,11 +54,21 @@ paths: content: application/json: examples: - nodePluginsExample1: - total: 1 - plugins: - - name: logstash-codec-cef - version: 4.1.2 + nodeInfoExample1: + pipelines: + - test: + workers: 1 + batch_size: 1 + batch_delay: 5 + config_reload_automatic: false + config_reload_interval: 3 + - test2: + workers: 8 + batch_size: 125 + batch_delay: 5 + config_reload_automatic: false + config_reload_interval: 3 + /_node/plugins: get: summary: Get plugin info @@ -85,7 +93,63 @@ paths: total: 1 plugins: - name: logstash-codec-cef - version: 4.1.2 + version: 6.2.8 + - name: logstash-codec-collectd + version: 3.0.3 + - name: logstash-codec-dots + version: 3.0.2 + - name: logstash-coded-edn + version: 3.0.2 + + /_node/stats: + get: + summary: Get node stats + description: > + Get runtime stats for Logstash, where `` (optional) specifies the types of stats you want to return. + You can limit the info that is returned by combining any of these types in a comma-separated list: + + - `jvm` gets JVM stats, including stats about threads, memory usage, garbage collectors, and uptime. + - `process` gets process stats, including stats about file descriptors, memory consumption, and CPU usage. + - `events` gets event-related statistics for the Logstash instance (regardless of how many pipelines were created and destroyed). + - `flow` gets flow-related statistics for the Logstash instance (regardless of how many pipelines were created and destroyed). + - `pipelines` gets runtime stats about each Logstash pipeline. + - `reloads` gets runtime stats about config reload successes and failures. + - `os` gets runtime stats about cgroups when Logstash is running in a container. + - `geoip_download_manager` gets stats for databases used with the Geoip filter plugin. + + operationId: nodeStats + parameters: + - name: pretty + in: query + schema: + type: boolean + description: > + If you append `?pretty=true` to the request, the JSON returned will be pretty formatted (use it for debugging only!). + responses: + '200': + description: Indicates a successful call + content: + application/json: + examples: + nodeStatsExample1: + jvm: + threads: + count: 49 + peak_count: 50 + mem: + heap_used_percent: 14 + heap_committed_in_bytes: 309866496 + heap_max_in_bytes: 1037959168 + heap_used_in_bytes: 151686096 + non_heap_used_in_bytes: 122486176 + non_heap_committed_in_bytes: 133222400 + pools: + survivor: + peak_used_in_bytes: 8912896 + used_in_bytes: 288776 + peak_max_in_bytes: 35782656 + max_in_bytes: 35782656 + committed_in_bytes: 8912896 /_node/hot_threads: get: @@ -142,3 +206,47 @@ paths: path: /path/to/logstash-8.17.0/vendor/bundle/jruby/1.9/gems/puma-2.16.0-java/lib/puma/thread_pool.rb:187 traces: java.lang.Object.wait(Native Method)", "org.jruby.RubyThread.sleep(RubyThread.java:1002)", "org.jruby.RubyKernel.sleep(RubyKernel.java:803) + /_health_report: + get: + summary: Get health status + description: > + The health API returns a report with the health status of Logstash and the pipelines that are running inside of it. + The report contains a list of indicators that compose Logstash functionality. + + Each indicator has a health status of: green, unknown, yellow, or red. + The indicator provides an explanation and metadata describing the reason for its current health status. + + The top-level status is controlled by the worst indicator status. + + In the event that an indicator status is non-green, a list of impacts may be present in the indicator result which detail the functionalities that are negatively affected by the health issue. + Each impact carries with it a severity level, an area of the system that is affected, and a simple description of the impact on the system. + + Some health indicators can determine the root cause of a health problem and prescribe a set of steps that can be performed in order to improve the health of the system. + The root cause and remediation steps are encapsulated in a diagnosis. + A diagnosis contains a cause detailing a root cause analysis, an action containing a brief description of the steps to take to fix the problem, and the URL for detailed troubleshooting help. + + NOTE: The health indicators perform root cause analysis of non-green health statuses. + This can be computationally expensive when called frequently. + + operationId: healthStatus + parameters: + - name: pretty + in: query + schema: + type: boolean + description: > + If you append `?pretty=true` to the request, the JSON returned will be pretty formatted. Use it for debugging only! + responses: + '200': + description: Indicates a successful call + content: + application/json: + examples: + healthStatusExample1: + status: + - green: Logstash is healthy. + unknown: Logstash health could not be determined. + yellow: The functionality of Logstash is in a degraded state and may need remediation to avoid the health becoming red. + red: Logstash is experiencing an outage or certain features are unavailable for use. + indicators: Information about the health of Logstash indicators. + From 97e1eebace369e1c1f2e629679b839820d3c0e21 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 3 Jan 2025 14:07:21 -0800 Subject: [PATCH 07/15] Add tags --- docs/static/spec/openapi/starter.yaml | 44 +++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/docs/static/spec/openapi/starter.yaml b/docs/static/spec/openapi/starter.yaml index f525bad7010..c101b63b786 100644 --- a/docs/static/spec/openapi/starter.yaml +++ b/docs/static/spec/openapi/starter.yaml @@ -29,6 +29,40 @@ servers: - url: / security: - apiKeyAuth: [] +tags: + - name: health + x-displayName: Health report + # description: + # externalDocs: + # description: + # url: + - name: hot threads + x-displayName: Hot threads + # description: + # externalDocs: + # description: + # url: + - name: node info + x-displayName: Node info + description: | + Logstash node info, like pipeline settings, OS info, and JVM info. + # externalDocs: + # description: + # url: + - name: node stats + x-displayName: Node stats + description: | + Node stats, like JVM stats, process stats, event-related stats, and pipeline runtime stats. + # externalDocs: + # description: + # url: + - name: plugin info + x-displayName: Plugins info + description: | + Plugin info, including a list of installed plugins. + # externalDocs: + # description: + # url: paths: /_node/: get: @@ -41,6 +75,8 @@ paths: - `os`. - `jvm`. operationId: nodeInfo + tags: + - node info parameters: - name: pretty in: query @@ -76,6 +112,8 @@ paths: Get information about all Logstash plugins that are currently installed. This API returns the same output you get by running the `bin/logstash-plugin list --verbose` command. operationId: nodePlugins + tags: + - plugin info parameters: - name: pretty in: query @@ -118,6 +156,8 @@ paths: - `geoip_download_manager` gets stats for databases used with the Geoip filter plugin. operationId: nodeStats + tags: + - node stats parameters: - name: pretty in: query @@ -158,6 +198,8 @@ paths: Get information about current hot threads for Logstash. A hot thread is a Java thread that has high CPU usage and takes longer than normal to execute. operationId: nodeHot_threads + tags: + - hot threads parameters: - name: threads in: query @@ -229,6 +271,8 @@ paths: This can be computationally expensive when called frequently. operationId: healthStatus + tags: + - health parameters: - name: pretty in: query From cd45001a031684b79557d25aeefbfdd4d849293e Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 3 Jan 2025 14:18:35 -0800 Subject: [PATCH 08/15] Bulleted lists --- docs/static/spec/openapi/starter.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/static/spec/openapi/starter.yaml b/docs/static/spec/openapi/starter.yaml index c101b63b786..a9b99cc35b3 100644 --- a/docs/static/spec/openapi/starter.yaml +++ b/docs/static/spec/openapi/starter.yaml @@ -67,13 +67,13 @@ paths: /_node/: get: summary: Get node info - description: > + description: | Get information about Logstash nodes, where `` (optional) specifies the types of node info you want returned. You can limit the info that is returned by combining any of these types in a comma-separated list: - - `pipelines`. - - `os`. - - `jvm`. + - `pipelines` + - `os` + - `jvm` operationId: nodeInfo tags: - node info @@ -142,7 +142,7 @@ paths: /_node/stats: get: summary: Get node stats - description: > + description: | Get runtime stats for Logstash, where `` (optional) specifies the types of stats you want to return. You can limit the info that is returned by combining any of these types in a comma-separated list: From cdf12f887ab8c4338dfb3715c1894064cec491e4 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 3 Jan 2025 14:50:42 -0800 Subject: [PATCH 09/15] Add basic health report response body schema --- docs/static/spec/openapi/starter.yaml | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/static/spec/openapi/starter.yaml b/docs/static/spec/openapi/starter.yaml index a9b99cc35b3..1db8a2621d8 100644 --- a/docs/static/spec/openapi/starter.yaml +++ b/docs/static/spec/openapi/starter.yaml @@ -285,6 +285,13 @@ paths: description: Indicates a successful call content: application/json: + schema: + type: object + properties: + indicators: + type: object + status: + $ref: '#/components/schemas/Statuses' examples: healthStatusExample1: status: @@ -292,5 +299,13 @@ paths: unknown: Logstash health could not be determined. yellow: The functionality of Logstash is in a degraded state and may need remediation to avoid the health becoming red. red: Logstash is experiencing an outage or certain features are unavailable for use. - indicators: Information about the health of Logstash indicators. - + indicators: Information about the health of Logstash indicators. +components: + schemas: + Statuses: + type: string + enum: + - green + - red + - unknown + - yellow \ No newline at end of file From 30a157a6c7328c6edaa10bcdd0adaef3e3d963b0 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Mon, 6 Jan 2025 16:44:45 -0800 Subject: [PATCH 10/15] Update docs/static/spec/openapi/starter.yaml Co-authored-by: Cas Donoghue --- docs/static/spec/openapi/starter.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/static/spec/openapi/starter.yaml b/docs/static/spec/openapi/starter.yaml index 1db8a2621d8..5ea1084f351 100644 --- a/docs/static/spec/openapi/starter.yaml +++ b/docs/static/spec/openapi/starter.yaml @@ -251,7 +251,7 @@ paths: /_health_report: get: summary: Get health status - description: > + description: | The health API returns a report with the health status of Logstash and the pipelines that are running inside of it. The report contains a list of indicators that compose Logstash functionality. From 81b629433a53ca17560d77d6d220f55ba3254df3 Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 6 Jan 2025 16:54:34 -0800 Subject: [PATCH 11/15] Fix node info example --- docs/static/spec/openapi/starter.yaml | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/static/spec/openapi/starter.yaml b/docs/static/spec/openapi/starter.yaml index 5ea1084f351..3cc611554d3 100644 --- a/docs/static/spec/openapi/starter.yaml +++ b/docs/static/spec/openapi/starter.yaml @@ -93,17 +93,17 @@ paths: nodeInfoExample1: pipelines: - test: - workers: 1 - batch_size: 1 - batch_delay: 5 - config_reload_automatic: false - config_reload_interval: 3 + workers: 1 + batch_size: 1 + batch_delay: 5 + config_reload_automatic: false + config_reload_interval: 3 - test2: - workers: 8 - batch_size: 125 - batch_delay: 5 - config_reload_automatic: false - config_reload_interval: 3 + workers: 8 + batch_size: 125 + batch_delay: 5 + config_reload_automatic: false + config_reload_interval: 3 /_node/plugins: get: From 558a2b64bc9df810f8af85328e767bf73a63c4d6 Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 6 Jan 2025 17:03:09 -0800 Subject: [PATCH 12/15] Add remainder of jvm stats example --- docs/static/spec/openapi/starter.yaml | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/docs/static/spec/openapi/starter.yaml b/docs/static/spec/openapi/starter.yaml index 3cc611554d3..2f3194efd80 100644 --- a/docs/static/spec/openapi/starter.yaml +++ b/docs/static/spec/openapi/starter.yaml @@ -173,23 +173,44 @@ paths: examples: nodeStatsExample1: jvm: - threads: + threads: count: 49 peak_count: 50 - mem: + mem: heap_used_percent: 14 heap_committed_in_bytes: 309866496 heap_max_in_bytes: 1037959168 heap_used_in_bytes: 151686096 non_heap_used_in_bytes: 122486176 non_heap_committed_in_bytes: 133222400 - pools: + pools: survivor: peak_used_in_bytes: 8912896 used_in_bytes: 288776 peak_max_in_bytes: 35782656 max_in_bytes: 35782656 committed_in_bytes: 8912896 + old: + peak_used_in_bytes: 148656848 + used_in_bytes: 148656848 + peak_max_in_bytes: 715849728 + max_in_bytes: 715849728 + committed_in_bytes: 229322752 + young: + peak_used_in_bytes: 71630848 + used_in_bytes: 2740472 + peak_max_in_bytes: 286326784 + max_in_bytes: 286326784 + committed_in_bytes: 71630848 + gc: + collectors: + old: + collection_time_in_millis: 607 + collection_count: 12 + young: + collection_time_in_millis: 4904 + collection_count: 1033 + uptime_in_millis: 1809643 /_node/hot_threads: get: From 64db183dd187e98c883428c5285e2cd31f9bfbe6 Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 6 Jan 2025 17:39:53 -0800 Subject: [PATCH 13/15] Add response schema for hot threads --- docs/static/spec/openapi/starter.yaml | 210 ++++++++++++++++---------- 1 file changed, 132 insertions(+), 78 deletions(-) diff --git a/docs/static/spec/openapi/starter.yaml b/docs/static/spec/openapi/starter.yaml index 2f3194efd80..04f515f249c 100644 --- a/docs/static/spec/openapi/starter.yaml +++ b/docs/static/spec/openapi/starter.yaml @@ -91,19 +91,21 @@ paths: application/json: examples: nodeInfoExample1: - pipelines: - - test: - workers: 1 - batch_size: 1 - batch_delay: 5 - config_reload_automatic: false - config_reload_interval: 3 - - test2: - workers: 8 - batch_size: 125 - batch_delay: 5 - config_reload_automatic: false - config_reload_interval: 3 + # summary: + value: + pipelines: + - test: + workers: 1 + batch_size: 1 + batch_delay: 5 + config_reload_automatic: false + config_reload_interval: 3 + - test2: + workers: 8 + batch_size: 125 + batch_delay: 5 + config_reload_automatic: false + config_reload_interval: 3 /_node/plugins: get: @@ -128,16 +130,18 @@ paths: application/json: examples: nodePluginsExample1: - total: 1 - plugins: - - name: logstash-codec-cef - version: 6.2.8 - - name: logstash-codec-collectd - version: 3.0.3 - - name: logstash-codec-dots - version: 3.0.2 - - name: logstash-coded-edn - version: 3.0.2 + # summary: + value: + total: 1 + plugins: + - name: logstash-codec-cef + version: 6.2.8 + - name: logstash-codec-collectd + version: 3.0.3 + - name: logstash-codec-dots + version: 3.0.2 + - name: logstash-coded-edn + version: 3.0.2 /_node/stats: get: @@ -172,45 +176,47 @@ paths: application/json: examples: nodeStatsExample1: - jvm: - threads: - count: 49 - peak_count: 50 - mem: - heap_used_percent: 14 - heap_committed_in_bytes: 309866496 - heap_max_in_bytes: 1037959168 - heap_used_in_bytes: 151686096 - non_heap_used_in_bytes: 122486176 - non_heap_committed_in_bytes: 133222400 - pools: - survivor: - peak_used_in_bytes: 8912896 - used_in_bytes: 288776 - peak_max_in_bytes: 35782656 - max_in_bytes: 35782656 - committed_in_bytes: 8912896 - old: - peak_used_in_bytes: 148656848 - used_in_bytes: 148656848 - peak_max_in_bytes: 715849728 - max_in_bytes: 715849728 - committed_in_bytes: 229322752 - young: - peak_used_in_bytes: 71630848 - used_in_bytes: 2740472 - peak_max_in_bytes: 286326784 - max_in_bytes: 286326784 - committed_in_bytes: 71630848 - gc: - collectors: - old: - collection_time_in_millis: 607 - collection_count: 12 - young: - collection_time_in_millis: 4904 - collection_count: 1033 - uptime_in_millis: 1809643 + # summary: + value: + jvm: + threads: + count: 49 + peak_count: 50 + mem: + heap_used_percent: 14 + heap_committed_in_bytes: 309866496 + heap_max_in_bytes: 1037959168 + heap_used_in_bytes: 151686096 + non_heap_used_in_bytes: 122486176 + non_heap_committed_in_bytes: 133222400 + pools: + survivor: + peak_used_in_bytes: 8912896 + used_in_bytes: 288776 + peak_max_in_bytes: 35782656 + max_in_bytes: 35782656 + committed_in_bytes: 8912896 + old: + peak_used_in_bytes: 148656848 + used_in_bytes: 148656848 + peak_max_in_bytes: 715849728 + max_in_bytes: 715849728 + committed_in_bytes: 229322752 + young: + peak_used_in_bytes: 71630848 + used_in_bytes: 2740472 + peak_max_in_bytes: 286326784 + max_in_bytes: 286326784 + committed_in_bytes: 71630848 + gc: + collectors: + old: + collection_time_in_millis: 607 + collection_count: 12 + young: + collection_time_in_millis: 4904 + collection_count: 1033 + uptime_in_millis: 1809643 /_node/hot_threads: get: @@ -257,17 +263,47 @@ paths: description: Indicates a successful call content: application/json: + schema: + type: object + properties: + hot_threads: + type: object + properties: + busiest_threads: + type: integer + threads: + type: array + items: + $ref: '#/components/schemas/Thread' + time: + type: string examples: nodeHotThreadsExample1: - hot_threads: - - time: 2025-01-06T18:25:28-07:00 - busiest_threads: 3 - threads: - name: Ruby-0-Thread-7 - percent_of_cpu_time: 0.0 - state: timed_waiting - path: /path/to/logstash-8.17.0/vendor/bundle/jruby/1.9/gems/puma-2.16.0-java/lib/puma/thread_pool.rb:187 - traces: java.lang.Object.wait(Native Method)", "org.jruby.RubyThread.sleep(RubyThread.java:1002)", "org.jruby.RubyKernel.sleep(RubyKernel.java:803) + # summary: + value: + hot_threads: + - time: 2025-01-06T18:25:28-07:00 + busiest_threads: 3 + threads: + - name: Ruby-0-Thread-7 + percent_of_cpu_time: 0.0 + state: timed_waiting + path: /path/to/logstash-8.17.0/vendor/bundle/jruby/1.9/gems/puma-2.16.0-java/lib/puma/thread_pool.rb:187 + traces: java.lang.Object.wait(Native Method)", "org.jruby.RubyThread.sleep(RubyThread.java:1002)", "org.jruby.RubyKernel.sleep(RubyKernel.java:803) + - name: "[test2]>worker3" + percent_of_cpu_time: 0.85 + state: waiting + traces: + - "sun.misc.Unsafe.park(Native Method)" + - "java.util.concurrent.locks.LockSupport.park(LockSupport.java:175)" + - "java.util.concurrent.locks.AbstractQueuedSynchronizer.parkAndCheckInterrupt(AbstractQueuedSynchronizer.java:836)" + - name: "[test2]>worker2" + percent_of_cpu_time: 0.85 + state: runnable + traces: + - "org.jruby.RubyClass.allocate(RubyClass.java:225)" + - "org.jruby.RubyClass.newInstance(RubyClass.java:856)" + - "org.jruby.RubyClass$INVOKER$i$newInstance.call(RubyClass$INVOKER$i$newInstance.gen)" /_health_report: get: @@ -315,12 +351,14 @@ paths: $ref: '#/components/schemas/Statuses' examples: healthStatusExample1: - status: - - green: Logstash is healthy. - unknown: Logstash health could not be determined. - yellow: The functionality of Logstash is in a degraded state and may need remediation to avoid the health becoming red. - red: Logstash is experiencing an outage or certain features are unavailable for use. - indicators: Information about the health of Logstash indicators. + # summary: + value: + status: + - green: Logstash is healthy. + unknown: Logstash health could not be determined. + yellow: The functionality of Logstash is in a degraded state and may need remediation to avoid the health becoming red. + red: Logstash is experiencing an outage or certain features are unavailable for use. + indicators: Information about the health of Logstash indicators. components: schemas: Statuses: @@ -329,4 +367,20 @@ components: - green - red - unknown - - yellow \ No newline at end of file + - yellow + Thread: + type: object + properties: + name: + type: string + path: + type: string + percent_of_cpu_time: + type: number + format: double + state: + type: string + traces: + type: array + items: + type: string \ No newline at end of file From 3284c2649600dd8621623c304d1234616dd85ecc Mon Sep 17 00:00:00 2001 From: Karen Metts Date: Thu, 9 Jan 2025 14:54:52 -0500 Subject: [PATCH 14/15] Rename file --- docs/static/spec/openapi/{starter.yaml => logstash-api.yaml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/static/spec/openapi/{starter.yaml => logstash-api.yaml} (100%) diff --git a/docs/static/spec/openapi/starter.yaml b/docs/static/spec/openapi/logstash-api.yaml similarity index 100% rename from docs/static/spec/openapi/starter.yaml rename to docs/static/spec/openapi/logstash-api.yaml From 7710391a1549c085b8a9dbbc3fc20bddfd55e6aa Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 9 Jan 2025 13:24:31 -0800 Subject: [PATCH 15/15] Add linting config and fix linting errors --- docs/static/spec/openapi/logstash-api.yaml | 72 ++++++++++++---------- docs/static/spec/openapi/redocly.yaml | 52 ++++++++++++++++ 2 files changed, 92 insertions(+), 32 deletions(-) create mode 100644 docs/static/spec/openapi/redocly.yaml diff --git a/docs/static/spec/openapi/logstash-api.yaml b/docs/static/spec/openapi/logstash-api.yaml index 04f515f249c..49ff4bef1c7 100644 --- a/docs/static/spec/openapi/logstash-api.yaml +++ b/docs/static/spec/openapi/logstash-api.yaml @@ -282,28 +282,31 @@ paths: # summary: value: hot_threads: - - time: 2025-01-06T18:25:28-07:00 - busiest_threads: 3 - threads: - - name: Ruby-0-Thread-7 - percent_of_cpu_time: 0.0 - state: timed_waiting - path: /path/to/logstash-8.17.0/vendor/bundle/jruby/1.9/gems/puma-2.16.0-java/lib/puma/thread_pool.rb:187 - traces: java.lang.Object.wait(Native Method)", "org.jruby.RubyThread.sleep(RubyThread.java:1002)", "org.jruby.RubyKernel.sleep(RubyKernel.java:803) - - name: "[test2]>worker3" - percent_of_cpu_time: 0.85 - state: waiting - traces: - - "sun.misc.Unsafe.park(Native Method)" - - "java.util.concurrent.locks.LockSupport.park(LockSupport.java:175)" - - "java.util.concurrent.locks.AbstractQueuedSynchronizer.parkAndCheckInterrupt(AbstractQueuedSynchronizer.java:836)" - - name: "[test2]>worker2" - percent_of_cpu_time: 0.85 - state: runnable - traces: - - "org.jruby.RubyClass.allocate(RubyClass.java:225)" - - "org.jruby.RubyClass.newInstance(RubyClass.java:856)" - - "org.jruby.RubyClass$INVOKER$i$newInstance.call(RubyClass$INVOKER$i$newInstance.gen)" + time: 2025-01-06T18:25:28-07:00 + busiest_threads: 3 + threads: + - name: Ruby-0-Thread-7 + percent_of_cpu_time: 0.0 + state: timed_waiting + path: /path/to/logstash-8.17.0/vendor/bundle/jruby/1.9/gems/puma-2.16.0-java/lib/puma/thread_pool.rb:187 + traces: + - "java.lang.Object.wait(Native Method)" + - "org.jruby.RubyThread.sleep(RubyThread.java:1002)" + - "org.jruby.RubyKernel.sleep(RubyKernel.java:803)" + - name: "[test2]>worker3" + percent_of_cpu_time: 0.85 + state: waiting + traces: + - "sun.misc.Unsafe.park(Native Method)" + - "java.util.concurrent.locks.LockSupport.park(LockSupport.java:175)" + - "java.util.concurrent.locks.AbstractQueuedSynchronizer.parkAndCheckInterrupt(AbstractQueuedSynchronizer.java:836)" + - name: "[test2]>worker2" + percent_of_cpu_time: 0.85 + state: runnable + traces: + - "org.jruby.RubyClass.allocate(RubyClass.java:225)" + - "org.jruby.RubyClass.newInstance(RubyClass.java:856)" + - "org.jruby.RubyClass$INVOKER$i$newInstance.call(RubyClass$INVOKER$i$newInstance.gen)" /_health_report: get: @@ -346,23 +349,28 @@ paths: type: object properties: indicators: + description: Information about the health of Logstash indicators. type: object status: $ref: '#/components/schemas/Statuses' - examples: - healthStatusExample1: - # summary: - value: - status: - - green: Logstash is healthy. - unknown: Logstash health could not be determined. - yellow: The functionality of Logstash is in a degraded state and may need remediation to avoid the health becoming red. - red: Logstash is experiencing an outage or certain features are unavailable for use. - indicators: Information about the health of Logstash indicators. components: + securitySchemes: + apiKeyAuth: + # description: + in: header + name: Authorization + type: apiKey schemas: Statuses: type: string + description: | + Health status of Logstash, based on the aggregated status of all indicators. + Statuses are: + + - `green`: Logstash is healthy. + - `unknown`: Logstash health could not be determined. + - `yellow`: The functionality of Logstash is in a degraded state and may need remediation to avoid the health becoming red. + - `red`: Logstash is experiencing an outage or certain features are unavailable for use. enum: - green - red diff --git a/docs/static/spec/openapi/redocly.yaml b/docs/static/spec/openapi/redocly.yaml new file mode 100644 index 00000000000..139a503ba85 --- /dev/null +++ b/docs/static/spec/openapi/redocly.yaml @@ -0,0 +1,52 @@ +extends: + - recommended +rules: +# Built-in rules + # Descriptions + parameter-description: warn + tag-description: warn + operation-description: off + # Document info + info-contact: warn + info-license: warn + # Examples + no-invalid-media-type-examples: + severity: warn + allowAdditionalProperties: false + no-invalid-schema-examples: + severity: warn + allowAdditionalProperties: false + # Operations + operation-operationId: error + operation-operationId-unique: error + operation-operationId-url-safe: warn + operation-summary: warn + # Parameters + path-parameters-defined: warn + # Paths + no-ambiguous-paths: warn + no-identical-paths: error + path-excludes-patterns: + severity: error + patterns: + - ^\/internal + # Responses + operation-4xx-response: off + operation-2xx-response: off + # Schema + spec: off + spec-strict-refs: off + # Tags + operation-tag-defined: off + tags-alphabetical: off + operation-singular-tag: off +# Custom rules + rule/operation-summary-length: + subject: + type: Operation + property: summary + message: Operation summary must have a minimum of 5 and maximum of 45 characters + severity: warn + assertions: + maxLength: 45 + minLength: 5 \ No newline at end of file