Logstash API spec - first pass #16546
Conversation
|
📃 DOCS PREVIEW ✨ https://logstash_bk_16546.docs-preview.app.elstc.co/diff |
|
📃 DOCS PREVIEW ✨ https://logstash_bk_16546.docs-preview.app.elstc.co/diff |
|
📃 DOCS PREVIEW ✨ https://logstash_bk_16546.docs-preview.app.elstc.co/diff |
| - `pipelines`. | ||
| - `os`. | ||
| - `jvm`. |
There was a problem hiding this comment.
What's the trick to getting items on their own lines? (I tried \n, but they rendered literally.)
There was a problem hiding this comment.
Node Info section has subsections for pipelines, os, and jvm, each with their own examples.
ToDo: Format nested content
| examples: | ||
| nodeInfoExample1: | ||
| pipelines: | ||
| - test: |
There was a problem hiding this comment.
Trick to keep null from appearing for entries without values.
| - `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. |
There was a problem hiding this comment.
Formatting for bulleted list. Table format?
| 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 |
There was a problem hiding this comment.
Example is only partially reproduced.
| 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) |
There was a problem hiding this comment.
What's the ordering principle for entries?
Note that busiest_threads is rendering last but it's not entered there.
| 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: |
There was a problem hiding this comment.
Health_report appears last in the spec, but is rendering first. (Not sure it matters, but I'd like to know what's going on.)
| 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. |
There was a problem hiding this comment.
This content needs line breaks. I tried \n, but they render literally.
There was a problem hiding this comment.
I believe this is just pure YAML. The scalar (>) folds on line 212 (description: >). If instead we use a literal scalar | it should preserve line breaks exactly as written (description: |). https://github.com/elastic/logstash/pull/16546/files#r1899659257
| 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. |
There was a problem hiding this comment.
The Health report API docs show hierarchical descriptions rather that examples. What's the best way to represent this type of content? Also, research nested format.
| /_health_report: | ||
| get: | ||
| summary: Get health status | ||
| description: > |
There was a problem hiding this comment.
| description: > | |
| description: | |
Use literal scalar instead of folding to preserve newlines.
Related: https://github.com/elastic/docs-projects/issues/233