Logstash API spec - first pass #16546

karenzone · 2024-10-11T17:21:37Z

Related: https://github.com/elastic/docs-projects/issues/233

github-actions · 2024-12-27T17:43:01Z

📃 DOCS PREVIEW ✨ https://logstash_bk_16546.docs-preview.app.elstc.co/diff

github-actions · 2024-12-27T18:20:35Z

📃 DOCS PREVIEW ✨ https://logstash_bk_16546.docs-preview.app.elstc.co/diff

github-actions · 2024-12-27T20:21:21Z

📃 DOCS PREVIEW ✨ https://logstash_bk_16546.docs-preview.app.elstc.co/diff

karenzone

@lcawl, I left some questions and comments inline to discuss with you. Thanks for your help with this.

karenzone · 2024-12-27T20:07:21Z

docs/static/spec/openapi/starter.yaml

+        - `pipelines`. 
+        - `os`. 
+        - `jvm`. 


What's the trick to getting items on their own lines? (I tried \n, but they rendered literally.)

Node Info section has subsections for pipelines, os, and jvm, each with their own examples.
ToDo: Format nested content

What's the trick to getting items on their own lines? (I tried \n, but they rendered literally.)

I think this is now fixed (by using | )

karenzone · 2024-12-27T20:09:02Z

docs/static/spec/openapi/starter.yaml

+              examples:
+                nodeInfoExample1:
+                  pipelines:
+                    - test: 


Trick to keep null from appearing for entries without values.

This looks like an indentation issue.

I've created 81b6294 and it matches the original docs now

karenzone · 2024-12-27T20:16:09Z

docs/static/spec/openapi/starter.yaml

+        - `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.


Formatting for bulleted list. Table format?

I haven't tried a table yet but AFAIK it should work if you use a simple markdown table. Might be something that could be tested in a future update, however, if this is good enough for now.

karenzone · 2024-12-27T20:17:02Z

docs/static/spec/openapi/starter.yaml

+                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


Example is only partially reproduced.

I copied the rest of the info into the yaml file in 558a2b6

karenzone · 2024-12-27T20:23:21Z

docs/static/spec/openapi/starter.yaml

+                  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)


What's the ordering principle for entries?
Note that busiest_threads is rendering last but it's not entered there.

Interesting, I've never noticed that before. I tried adding the schema definitions to see if their absence was affecting that (64db183) but it's still the same. I don't think the order matters, so I think it's not a big issue but if we want to know for future reference we'd need to query the folks at Bump.sh

karenzone · 2024-12-27T20:24:34Z

docs/static/spec/openapi/starter.yaml

+                        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:


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.)

This relates to https://docs.bump.sh/help/customization-options/operations-navigation/ and will be affected by the tags we added.

karenzone · 2024-12-27T20:26:56Z

docs/static/spec/openapi/starter.yaml

+        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.


This content needs line breaks. I tried \n, but they render literally.

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

karenzone · 2024-12-27T20:43:19Z

docs/static/spec/openapi/starter.yaml

+                  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. 


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.

docs/static/spec/openapi/starter.yaml

github-actions · 2025-01-03T22:39:59Z

📃 DOCS PREVIEW ✨ https://logstash_bk_16546.docs-preview.app.elstc.co/diff

github-actions · 2025-01-03T23:11:13Z

📃 DOCS PREVIEW ✨ https://logstash_bk_16546.docs-preview.app.elstc.co/diff

Co-authored-by: Cas Donoghue <[email protected]>

github-actions · 2025-01-07T01:30:44Z

📃 DOCS PREVIEW ✨ https://logstash_bk_16546.docs-preview.app.elstc.co/diff

github-actions · 2025-01-07T02:07:02Z

📃 DOCS PREVIEW ✨ https://logstash_bk_16546.docs-preview.app.elstc.co/diff

Logstash API spec - first pass

da11b1f

karenzone added the docs label Oct 11, 2024

karenzone self-assigned this Oct 11, 2024

Delete docs/static/spec/openapi/starter copy.yaml

7d3954b

jsvd added the status:work-in-progress label Oct 11, 2024

lcawl and others added 2 commits October 11, 2024 11:23

Plugins info API draft

51c9e66

More work on APIs

0cd5d16

Add framework for node and hot threads

64863e1

karenzone force-pushed the 233-api branch from 4705c87 to 64863e1 Compare December 27, 2024 17:56

Add more content

488083a

karenzone commented Dec 27, 2024

View reviewed changes

karenzone mentioned this pull request Dec 27, 2024

Doc: Validate human-readable parameter for Logstash APIs #16805

Closed

donoghuc reviewed Dec 30, 2024

View reviewed changes

docs/static/spec/openapi/starter.yaml Outdated Show resolved Hide resolved

karenzone assigned lcawl Jan 2, 2025

karenzone requested a review from lcawl January 2, 2025 21:20

lcawl added 2 commits January 3, 2025 14:07

Add tags

97e1eeb

Bulleted lists

cd45001

Add basic health report response body schema

cdf12f8

lcawl and others added 3 commits January 6, 2025 16:44

Update docs/static/spec/openapi/starter.yaml

30a157a

Co-authored-by: Cas Donoghue <[email protected]>

Fix node info example

81b6294

Add remainder of jvm stats example

558a2b6

Add response schema for hot threads

64db183

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Logstash API spec - first pass #16546

Logstash API spec - first pass #16546

karenzone commented Oct 11, 2024

github-actions bot commented Dec 27, 2024

github-actions bot commented Dec 27, 2024

github-actions bot commented Dec 27, 2024

karenzone left a comment

karenzone Dec 27, 2024

karenzone Dec 27, 2024

lcawl Jan 7, 2025

karenzone Dec 27, 2024

lcawl Jan 7, 2025

lcawl Jan 7, 2025

karenzone Dec 27, 2024

lcawl Jan 7, 2025 •

edited

Loading

karenzone Dec 27, 2024

lcawl Jan 7, 2025

karenzone Dec 27, 2024

lcawl Jan 7, 2025

karenzone Dec 27, 2024

lcawl Jan 7, 2025

karenzone Dec 27, 2024

donoghuc Dec 30, 2024

karenzone Dec 27, 2024

github-actions bot commented Jan 3, 2025

github-actions bot commented Jan 3, 2025

github-actions bot commented Jan 7, 2025

github-actions bot commented Jan 7, 2025

Logstash API spec - first pass #16546

Are you sure you want to change the base?

Logstash API spec - first pass #16546

Conversation

karenzone commented Oct 11, 2024

github-actions bot commented Dec 27, 2024

github-actions bot commented Dec 27, 2024

github-actions bot commented Dec 27, 2024

karenzone left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lcawl Jan 7, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Jan 3, 2025

github-actions bot commented Jan 3, 2025

github-actions bot commented Jan 7, 2025

github-actions bot commented Jan 7, 2025

lcawl Jan 7, 2025 •

edited

Loading