From c65cc5beff9a12ba2e2072dd2fe57067614bf7a1 Mon Sep 17 00:00:00 2001 From: Ry Biesemeyer Date: Tue, 18 Mar 2025 16:47:12 +0000 Subject: [PATCH 01/11] openapi: resolve warning about discriminator type --- docs/static/spec/openapi/logstash-api.yaml | 126 +++++++++++---------- 1 file changed, 65 insertions(+), 61 deletions(-) diff --git a/docs/static/spec/openapi/logstash-api.yaml b/docs/static/spec/openapi/logstash-api.yaml index 1a78799608d..44e01d9a61d 100644 --- a/docs/static/spec/openapi/logstash-api.yaml +++ b/docs/static/spec/openapi/logstash-api.yaml @@ -2246,75 +2246,79 @@ components: failures: type: integer format: int64 - + PipelineQueueStatsMemory: + type: object + properties: + type: + type: string + enum: + - memory + events_count: + type: integer + format: int64 + queue_size_in_bytes: + type: integer + format: int64 + max_queue_size_in_bytes: + type: integer + format: int64 + PipelineQueueStatsPersisted: + type: object + properties: + type: + type: string + enum: + - persisted + capacity: + type: object + properties: + max_unread_events: + type: integer + format: int64 + page_capacity_in_bytes: + type: integer + format: int64 + max_queue_size_in_bytes: + type: integer + format: int64 + queue_size_in_bytes: + type: integer + format: int64 + data: + type: object + properties: + path: + type: string + free_space_in_bytes: + type: integer + format: int64 + storage_type: + type: string + events: + type: integer + format: int64 + events_count: + type: integer + format: int64 + queue_size_in_bytes: + type: integer + format: int64 + max_queue_size_in_bytes: + type: integer + format: int64 PipelineQueueStats: type: object properties: queue: type: object oneOf: - - type: object - description: "The metrics of persisted queue." - properties: - type: - type: string - enum: - - persisted - capacity: - type: object - properties: - max_unread_events: - type: integer - format: int64 - page_capacity_in_bytes: - type: integer - format: int64 - max_queue_size_in_bytes: - type: integer - format: int64 - queue_size_in_bytes: - type: integer - format: int64 - data: - type: object - properties: - path: - type: string - free_space_in_bytes: - type: integer - format: int64 - storage_type: - type: string - events: - type: integer - format: int64 - events_count: - type: integer - format: int64 - queue_size_in_bytes: - type: integer - format: int64 - max_queue_size_in_bytes: - type: integer - format: int64 - - type: object - description: "The metrics of memory queue." - properties: - type: - type: string - enum: - - memory - events_count: - type: integer - format: int64 - queue_size_in_bytes: - type: integer - format: int64 - max_queue_size_in_bytes: - type: integer - format: int64 + - $ref: "#/components/schemas/PipelineQueueStatsMemory" + - $ref: "#/components/schemas/PipelineQueueStatsPersisted" discriminator: propertyName: type + mapping: + memory: "#/components/schemas/PipelineQueueStatsMemory" + persisted: "#/components/schemas/PipelineQueueStatsPersisted" QueueStats: type: object properties: From 1baccc8494beeb527d687c5b357047bddfa7ce52 Mon Sep 17 00:00:00 2001 From: Ry Biesemeyer Date: Tue, 18 Mar 2025 16:48:09 +0000 Subject: [PATCH 02/11] openapi: resolve warning about example having extra filter metrics --- docs/static/spec/openapi/logstash-api.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/static/spec/openapi/logstash-api.yaml b/docs/static/spec/openapi/logstash-api.yaml index 44e01d9a61d..aa33cedb8cd 100644 --- a/docs/static/spec/openapi/logstash-api.yaml +++ b/docs/static/spec/openapi/logstash-api.yaml @@ -2139,6 +2139,9 @@ components: $ref: "#/components/schemas/WorkerStats" events: $ref: "#/components/schemas/FilterOutputPluginEventsStats" + additionalProperties: + propertyNames: + pattern: "^[a-z][a-z0-9_]*$" CodecPluginStats: type: object properties: From 7a2df83ede77b6fc17b3767be49c030ee69bb6df Mon Sep 17 00:00:00 2001 From: Ry Biesemeyer Date: Tue, 18 Mar 2025 16:48:37 +0000 Subject: [PATCH 03/11] openapi: add missing descriptions --- docs/static/spec/openapi/logstash-api.yaml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/static/spec/openapi/logstash-api.yaml b/docs/static/spec/openapi/logstash-api.yaml index aa33cedb8cd..f2ff040c2cb 100644 --- a/docs/static/spec/openapi/logstash-api.yaml +++ b/docs/static/spec/openapi/logstash-api.yaml @@ -34,12 +34,15 @@ security: tags: - name: health x-displayName: Health report - # description: + description: | + A report of the health of the Logstash process and its pipelines # externalDocs: # description: # url: - name: hot threads x-displayName: Hot threads + description: | + Information about the threads that are considered "hot" and consuming significant resources. # description: # externalDocs: # description: From 5b957f5ccb36c7ac2ad9e8543caad81d0f813b19 Mon Sep 17 00:00:00 2001 From: Ry Biesemeyer Date: Fri, 14 Mar 2025 19:48:03 +0000 Subject: [PATCH 04/11] openapi spec: DRY FlowValue --- docs/static/spec/openapi/logstash-api.yaml | 55 +++++++--------------- 1 file changed, 18 insertions(+), 37 deletions(-) diff --git a/docs/static/spec/openapi/logstash-api.yaml b/docs/static/spec/openapi/logstash-api.yaml index f2ff040c2cb..b3ce3c5bfe9 100644 --- a/docs/static/spec/openapi/logstash-api.yaml +++ b/docs/static/spec/openapi/logstash-api.yaml @@ -1755,56 +1755,37 @@ components: - unknown - yellow - FlowWindows: - type: object + FlowValue: description: | When the rate for a given flow metric window is infinite, it is presented as a string. This occurs when the numerator metric has changed during the window without a change in the rate’s denominator metric. + oneOf: + - type: number + format: double + - type: string + enum: ["Infinity", "-Infinity"] + FlowWindows: + type: object properties: current: - oneOf: - - type: number - format: double - - type: string - enum: ["Infinity"] description: "The most recent ~10s." - last_1_minute: oneOf: - - type: number - format: double - - type: string - enum: ["Infinity"] + - $ref: "#/components/schemas/FlowValue" + last_1_minute: + $ref: "#/components/schemas/FlowValue" last_5_minutes: - oneOf: - - type: number - format: double - - type: string - enum: ["Infinity"] + $ref: "#/components/schemas/FlowValue" last_15_minutes: - oneOf: - - type: number - format: double - - type: string - enum: ["Infinity"] + $ref: "#/components/schemas/FlowValue" last_1_hour: - oneOf: - - type: number - format: double - - type: string - enum: ["Infinity"] + $ref: "#/components/schemas/FlowValue" last_24_hours: - oneOf: - - type: number - format: double - - type: string - enum: ["Infinity"] + $ref: "#/components/schemas/FlowValue" lifetime: - oneOf: - - type: number - format: double - - type: string - enum: ["Infinity"] description: "The lifetime of the relevant pipeline or process." + oneOf: + - $ref: "#/components/schemas/FlowValue" + additionalProperties: false FlowStatsPart1: type: object properties: From 7efc970293758bd103beb3719f255691d12d4971 Mon Sep 17 00:00:00 2001 From: Ry Biesemeyer Date: Fri, 14 Mar 2025 20:57:45 +0000 Subject: [PATCH 05/11] openapi: use descriptive groupings for flow stats --- docs/static/spec/openapi/logstash-api.yaml | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/static/spec/openapi/logstash-api.yaml b/docs/static/spec/openapi/logstash-api.yaml index b3ce3c5bfe9..9c2c87d6613 100644 --- a/docs/static/spec/openapi/logstash-api.yaml +++ b/docs/static/spec/openapi/logstash-api.yaml @@ -1786,7 +1786,7 @@ components: oneOf: - $ref: "#/components/schemas/FlowValue" additionalProperties: false - FlowStatsPart1: + FlowStatsCommon: type: object properties: input_throughput: @@ -1822,7 +1822,7 @@ components: A process is also considered "saturated" when its top-level worker_concurrency flow metric approaches the cumulative pipeline.workers across all pipelines, and similarly can be addressed by tuning the individual pipelines that are saturated. allOf: # need to use allOf to keep the description - $ref: "#/components/schemas/FlowWindows" - FlowStatsPart2: + FlowStatsWorker: type: object properties: worker_utilization: @@ -1834,7 +1834,7 @@ components: A pipeline is considered "starved" when `worker_utilization` approaches 0, because it indicates that none of its workers are being kept busy. This is typically an indication that the inputs are not receiving or retrieving enough volume to keep the pipeline workers busy. Tuning a starved pipeline to have fewer workers can help it to consume less memory and CPU, freeing up resources for other pipelines. allOf: # need to use allOf to keep the description - $ref: "#/components/schemas/FlowWindows" - FlowStatsPart3: + FlowStatsPersistedQueue: type: object properties: queue_persisted_growth_bytes: @@ -1852,14 +1852,14 @@ components: PipelineMQFlowStats: type: object allOf: - - $ref: "#/components/schemas/FlowStatsPart1" - - $ref: "#/components/schemas/FlowStatsPart2" + - $ref: "#/components/schemas/FlowStatsCommon" + - $ref: "#/components/schemas/FlowStatsWorker" PipelinePQFlowStats: type: object allOf: - - $ref: "#/components/schemas/FlowStatsPart1" - - $ref: "#/components/schemas/FlowStatsPart2" - - $ref: "#/components/schemas/FlowStatsPart3" + - $ref: "#/components/schemas/FlowStatsCommon" + - $ref: "#/components/schemas/FlowStatsWorker" + - $ref: "#/components/schemas/FlowStatsPersistedQueue" PipelineFlowStats: type: object description: | @@ -1869,7 +1869,7 @@ components: properties: flow: type: object - oneOf: + anyOf: - $ref: "#/components/schemas/PipelineMQFlowStats" # For memory queue - $ref: "#/components/schemas/PipelinePQFlowStats" # For persisted queue @@ -1877,7 +1877,7 @@ components: type: object properties: flow: - $ref: "#/components/schemas/FlowStatsPart1" + $ref: "#/components/schemas/FlowStatsCommon" Thread: type: object From 7ef4c0d94895cd00370418215b747a67149f829a Mon Sep 17 00:00:00 2001 From: Ry Biesemeyer Date: Fri, 14 Mar 2025 21:00:18 +0000 Subject: [PATCH 06/11] openapi: make flows required --- docs/static/spec/openapi/logstash-api.yaml | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/static/spec/openapi/logstash-api.yaml b/docs/static/spec/openapi/logstash-api.yaml index 9c2c87d6613..106a918b3c5 100644 --- a/docs/static/spec/openapi/logstash-api.yaml +++ b/docs/static/spec/openapi/logstash-api.yaml @@ -1822,6 +1822,12 @@ components: A process is also considered "saturated" when its top-level worker_concurrency flow metric approaches the cumulative pipeline.workers across all pipelines, and similarly can be addressed by tuning the individual pipelines that are saturated. allOf: # need to use allOf to keep the description - $ref: "#/components/schemas/FlowWindows" + required: + - input_throughput + - filter_throughput + - output_throughput + - queue_backpressure + - worker_concurrency FlowStatsWorker: type: object properties: @@ -1834,6 +1840,8 @@ components: A pipeline is considered "starved" when `worker_utilization` approaches 0, because it indicates that none of its workers are being kept busy. This is typically an indication that the inputs are not receiving or retrieving enough volume to keep the pipeline workers busy. Tuning a starved pipeline to have fewer workers can help it to consume less memory and CPU, freeing up resources for other pipelines. allOf: # need to use allOf to keep the description - $ref: "#/components/schemas/FlowWindows" + required: + - worker_utilization FlowStatsPersistedQueue: type: object properties: @@ -1849,6 +1857,9 @@ components: This metric is expressed in events-per-second, and is the rate of change of the number of unacknowledged events in the queue, relative to wall-clock time (`queue.events_count` / second). A positive number indicates that the queue’s event-count is growing, and a negative number indicates that the queue is shrinking. allOf: # need to use allOf to keep the description - $ref: "#/components/schemas/FlowWindows" + required: + - queue_persisted_growth_bytes + - queue_persisted_growth_events PipelineMQFlowStats: type: object allOf: From 58071e9f5cc15c2567e18db702223f69e5defe12 Mon Sep 17 00:00:00 2001 From: Ry Biesemeyer Date: Fri, 14 Mar 2025 21:17:27 +0000 Subject: [PATCH 07/11] openapi: prefer `patternProperties` using pattern with descriptive named capture --- docs/static/spec/openapi/logstash-api.yaml | 234 +++++++++++---------- 1 file changed, 121 insertions(+), 113 deletions(-) diff --git a/docs/static/spec/openapi/logstash-api.yaml b/docs/static/spec/openapi/logstash-api.yaml index 106a918b3c5..430093db3fc 100644 --- a/docs/static/spec/openapi/logstash-api.yaml +++ b/docs/static/spec/openapi/logstash-api.yaml @@ -188,8 +188,10 @@ paths: properties: pipelines: type: object - additionalProperties: - $ref: '#/components/schemas/NodeInfoPipeline' + patternProperties: + "^(?.+)$": + $ref: '#/components/schemas/NodeInfoPipeline' + additionalProperties: false example: pipelines: aggregation-pipeline: @@ -235,8 +237,10 @@ paths: properties: pipelines: type: object - additionalProperties: - $ref: '#/components/schemas/NodeInfoPipeline' + patternProperties: + "^(?.+)$": + $ref: '#/components/schemas/NodeInfoPipeline' + additionalProperties: false example: pipelines: aggregation-pipeline: @@ -1521,82 +1525,84 @@ paths: type: string indicators: type: object - additionalProperties: - description: "pipeline name" - type: object - properties: - status: - $ref: '#/components/schemas/Status' - symptom: - type: string - description: "A message providing information about the current health status." - example: "The pipeline is healthy" - details: - type: object - description: "An object that contains additional information about the indicator that has led to the current health status result." - properties: - status: + patternProperties: + "^(?.+)$": + description: "pipeline name" + type: object + properties: + status: + $ref: '#/components/schemas/Status' + symptom: + type: string + description: "A message providing information about the current health status." + example: "The pipeline is healthy" + details: + type: object + description: "An object that contains additional information about the indicator that has led to the current health status result." + properties: + status: + type: object + properties: + state: + type: string + enum: + - LOADING + - RUNNING + - FINISHED + - TERMINATED + flow: + type: object + properties: + worker_utilization: + $ref: '#/components/schemas/FlowWindows' + impacts: + type: array + description: "If a non-healthy status is returned, indicators may include a list of impacts that this health status will have on Logstash." + items: type: object properties: - state: + id: type: string - enum: - - LOADING - - RUNNING - - FINISHED - - TERMINATED - flow: + description: | + A unique identifier that may appear associated with a known impacts or issue. + This ID follows a structured format that helps identify the specific problem. + example: "logstash:health:pipeline:flow:impact:blocked_processing" + severity: + type: integer + minimum: 1 + maximum: 10 + description: "How important this impact is to the functionality of Logstash. A value of 1 is the highest severity, with larger values indicating lower severity." + description: + type: string + description: "A description of the impact on Logstash." + impact_areas: + type: array + description: "The areas of Logstash affected by the health status. Possible values are:" + example: ["pipeline_execution"] + items: + type: string + diagnosis: + type: array + items: type: object properties: - worker_utilization: - $ref: '#/components/schemas/FlowWindows' - impacts: - type: array - description: "If a non-healthy status is returned, indicators may include a list of impacts that this health status will have on Logstash." - items: - type: object - properties: - id: - type: string - description: | - A unique identifier that may appear associated with a known impacts or issue. - This ID follows a structured format that helps identify the specific problem. - example: "logstash:health:pipeline:flow:impact:blocked_processing" - severity: - type: integer - minimum: 1 - maximum: 10 - description: "How important this impact is to the functionality of Logstash. A value of 1 is the highest severity, with larger values indicating lower severity." - description: - type: string - description: "A description of the impact on Logstash." - impact_areas: - type: array - description: "The areas of Logstash affected by the health status. Possible values are:" - example: ["pipeline_execution"] - items: + id: type: string - diagnosis: - type: array - items: - type: object - properties: - id: - type: string - description: | - A unique identifier that may appear associated with a known diagnosis or issue. - This ID follows a structured format that helps identify the specific problem. - example: "logstash:health:pipeline:flow:worker_utilization:diagnosis:5m-blocked" - cause: - type: string - description: "A description of a root cause of this health problem." - action: - type: string - description: "A brief description of the steps that should be taken to remediate the problem. A more detailed step-by-step guide to remediate the problem is provided by the `help_url` field." - help_url: - type: string - format: uri - description: "A link to the troubleshooting guide that will fix the health problem." + description: | + A unique identifier that may appear associated with a known diagnosis or issue. + This ID follows a structured format that helps identify the specific problem. + example: "logstash:health:pipeline:flow:worker_utilization:diagnosis:5m-blocked" + cause: + type: string + description: "A description of a root cause of this health problem." + action: + type: string + description: "A brief description of the steps that should be taken to remediate the problem. A more detailed step-by-step guide to remediate the problem is provided by the `help_url` field." + help_url: + type: string + format: uri + description: "A link to the troubleshooting guide that will fix the health problem." + additionalProperties: false examples: normalTerminatedCase: description: "The pipeline has finished without errors or interruptions." @@ -2168,45 +2174,47 @@ components: type: object description: | A map where each key is a user-defined pipeline name, and the value contains the metrics for that pipeline. - additionalProperties: - description: "Metrics of each plugin in the pipeline, flow statistics, event statistics and queue statistics." - type: object - allOf: - - $ref: "#/components/schemas/EventsStats" - - $ref: "#/components/schemas/PipelineFlowStats" - - type: object - properties: - plugins: - type: object - properties: - inputs: - type: array - items: - $ref: "#/components/schemas/InputPluginStats" - codecs: - type: array - items: - $ref: "#/components/schemas/CodecPluginStats" - filters: - type: array - items: - $ref: "#/components/schemas/FilterOutputPluginStats" - outputs: - type: array - items: - $ref: "#/components/schemas/FilterOutputPluginStats" - - $ref: "#/components/schemas/PipelineReloadStats" - - $ref: "#/components/schemas/PipelineQueueStats" - - $ref: "#/components/schemas/PipelineSettings" - - type: object - properties: - hash: - type: string - description: "A unique hash identifier." - ephemeral_id: - type: string - format: uuid - description: "A temporary unique identifier for the instance." + patternProperties: + "^(?.+)$": + description: "Metrics of each plugin in the pipeline, flow statistics, event statistics and queue statistics." + type: object + allOf: + - $ref: "#/components/schemas/EventsStats" + - $ref: "#/components/schemas/PipelineFlowStats" + - type: object + properties: + plugins: + type: object + properties: + inputs: + type: array + items: + $ref: "#/components/schemas/InputPluginStats" + codecs: + type: array + items: + $ref: "#/components/schemas/CodecPluginStats" + filters: + type: array + items: + $ref: "#/components/schemas/FilterOutputPluginStats" + outputs: + type: array + items: + $ref: "#/components/schemas/FilterOutputPluginStats" + - $ref: "#/components/schemas/PipelineReloadStats" + - $ref: "#/components/schemas/PipelineQueueStats" + - $ref: "#/components/schemas/PipelineSettings" + - type: object + properties: + hash: + type: string + description: "A unique hash identifier." + ephemeral_id: + type: string + format: uuid + description: "A temporary unique identifier for the instance." + additionalProperties: false PipelineReloadStats: type: object From 67401ebd6dd7bc6ed0979ca94c389e5dda0ef2f4 Mon Sep 17 00:00:00 2001 From: Ry Biesemeyer Date: Mon, 17 Mar 2025 17:47:56 +0000 Subject: [PATCH 08/11] openapi docs: mark required fields & ensure presence in examples --- docs/static/spec/openapi/logstash-api.yaml | 111 ++++++++++++++++++++- 1 file changed, 110 insertions(+), 1 deletion(-) diff --git a/docs/static/spec/openapi/logstash-api.yaml b/docs/static/spec/openapi/logstash-api.yaml index 430093db3fc..793e032452f 100644 --- a/docs/static/spec/openapi/logstash-api.yaml +++ b/docs/static/spec/openapi/logstash-api.yaml @@ -889,6 +889,8 @@ paths: workers: 4 batch_size: 125 batch_delay: 50 + hash: 09a35286efbb04cb7349b2f5767faabd549fc34d0e1512ce1942a60a590f24fc + ephemeral_id: a34fb011-8a9b-42b1-b10e-69f6f8054c18 heartbeat-ruby-stdout: events: queue_push_duration_in_millis: 159 @@ -1428,6 +1430,8 @@ paths: # - $ref: '#/components/schemas/Common' # - $ref: '#/components/schemas/PipelineSettings' - type: object + required: + - hot_threads properties: hot_threads: type: object @@ -1440,6 +1444,10 @@ paths: type: array items: $ref: '#/components/schemas/Thread' + required: + - time + - busiest_threads + - threads examples: nodeHotThreadsExample1: value: @@ -1508,6 +1516,9 @@ paths: allOf: - $ref: '#/components/schemas/Common' - type: object + required: + - symptom + - indicators properties: symptom: type: string @@ -1518,6 +1529,10 @@ paths: properties: pipelines: type: object + required: + - status + - symptom + - indicators properties: status: $ref: '#/components/schemas/Status' @@ -1529,6 +1544,9 @@ paths: "^(?.+)$": description: "pipeline name" type: object + required: + - status + - symptom properties: status: $ref: '#/components/schemas/Status' @@ -1560,6 +1578,9 @@ paths: description: "If a non-healthy status is returned, indicators may include a list of impacts that this health status will have on Logstash." items: type: object + required: + - severity + - description properties: id: type: string @@ -1585,6 +1606,10 @@ paths: type: array items: type: object + required: + - cause + - action + - help_url properties: id: type: string @@ -1603,10 +1628,20 @@ paths: format: uri description: "A link to the troubleshooting guide that will fix the health problem." additionalProperties: false + required: + - pipelines examples: normalTerminatedCase: description: "The pipeline has finished without errors or interruptions." value: + host: "0.0.0.0" + version: "9.0.0" + snapshot: false + http_address: "0.0.0.0:9600" + id: "908aa01c-4e96-4872-8980-736e0536373a" + name: "node.name" + ephemeral_id: "33bee016-b884-4a41-b79e-7e3991ed3711" + status: "yellow" symptom: "1 indicator is concerning (`pipelines`)" indicators: pipelines: @@ -1619,14 +1654,24 @@ paths: diagnosis: - cause: "pipeline has finished running because its inputs have been closed and events have been processed" action: "if you expect this pipeline to run indefinitely, you will need to configure its inputs to continue receiving or fetching events" + help_url: "https://www.elastic.co/guide/en/logstash/9.0/health-report-pipeline-status.html#finished" impacts: - - impact_areas: ["pipeline_execution"] + - description: "pipeline has finished running" + severity: 10 + impact_areas: ["pipeline_execution"] details: status: state: "FINISHED" abnormalTerminatedCase: description: "The pipeline is terminated with errors." value: + host: "0.0.0.0" + version: "9.0.0" + snapshot: false + http_address: "0.0.0.0:9600" + id: "908aa01c-4e96-4872-8980-736e0536373a" + name: "node.name" + ephemeral_id: "33bee016-b884-4a41-b79e-7e3991ed3711" status: "red" symptom: "1 indicator is unhealthy (`pipelines`)" indicators: @@ -1640,8 +1685,10 @@ paths: diagnosis: - cause: "pipeline is not running, likely because it has encountered an error" action: "view logs to determine the cause of abnormal pipeline shutdown" + help_url: "https://www.elastic.co/guide/en/logstash/9.0/health-report-pipeline-status.html#terminated" impacts: - description: "the pipeline is not currently processing" + severity: 1 impact_areas: [ "pipeline_execution" ] details: status: @@ -1649,6 +1696,13 @@ paths: backpressureCase: description: "A pipeline is blocked by slow downstream processing." value: + host: "0.0.0.0" + version: "9.0.0" + snapshot: false + http_address: "0.0.0.0:9600" + id: "908aa01c-4e96-4872-8980-736e0536373a" + name: "node.name" + ephemeral_id: "33bee016-b884-4a41-b79e-7e3991ed3711" status: "red" symptom: "1 indicator is unhealthy (`pipelines`)" indicators: @@ -1663,6 +1717,7 @@ paths: - id: "logstash:health:pipeline:flow:worker_utilization:diagnosis:5m-blocked" cause: "pipeline workers have been completely blocked for at least five minutes" action: "address bottleneck or add resources" + help_url: "https://www.elastic.co/guide/en/logstash/9.0/health-report-pipeline-flow-worker-utilization.html#blocked-5m" impacts: - id: "logstash:health:pipeline:flow:impact:blocked_processing" severity: 1 @@ -1691,6 +1746,15 @@ components: schemas: Common: type: object + required: + - host + - version + - http_address + - id + - name + - ephemeral_id + - snapshot + - status properties: host: type: string @@ -1718,6 +1782,8 @@ components: PipelineSettings: type: object + required: + - pipeline properties: pipeline: type: object @@ -1883,6 +1949,8 @@ components: Each pipeline’s entry in the API response includes a number of pipeline-scoped [flow rates](https://www.elastic.co/guide/en/logstash/current/node-stats-api.html#flow-stats) such as `input_throughput`, `worker_concurrency`, and `queue_backpressure` to provide visibility into the flow of events through the pipeline. When configured with a [persistent queue](https://www.elastic.co/guide/en/logstash/current/persistent-queues.html, the pipeline’s flow will include additional rates to provide visibility into the health of the pipeline’s persistent queue: + required: + - flow properties: flow: type: object @@ -1892,6 +1960,8 @@ components: NodeStatsFlow: type: object + required: + - flow properties: flow: $ref: "#/components/schemas/FlowStatsCommon" @@ -1915,6 +1985,8 @@ components: EventsStats: type: object + required: + - events properties: events: type: object @@ -1937,6 +2009,8 @@ components: JVMStats: type: object + required: + - jvm properties: jvm: type: object @@ -2032,6 +2106,8 @@ components: OSStats: type: object + required: + - os properties: os: type: object @@ -2047,6 +2123,8 @@ components: ProcessStats: type: object + required: + - process properties: process: type: object @@ -2108,6 +2186,11 @@ components: format: int64 InputPluginStats: type: object + required: + - id + - name + - flow + - events properties: id: type: string @@ -2131,6 +2214,11 @@ components: format: int64 FilterOutputPluginStats: type: object + required: + - id + - name + - flow + - events properties: id: type: string @@ -2145,6 +2233,9 @@ components: pattern: "^[a-z][a-z0-9_]*$" CodecPluginStats: type: object + required: + - id + - name properties: id: type: string @@ -2169,6 +2260,8 @@ components: PipelinesStats: type: object + required: + - pipelines properties: pipelines: type: object @@ -2182,9 +2275,14 @@ components: - $ref: "#/components/schemas/EventsStats" - $ref: "#/components/schemas/PipelineFlowStats" - type: object + required: + - plugins properties: plugins: type: object + required: + - inputs + - outputs properties: inputs: type: array @@ -2206,6 +2304,9 @@ components: - $ref: "#/components/schemas/PipelineQueueStats" - $ref: "#/components/schemas/PipelineSettings" - type: object + required: + - hash + - ephemeral_id properties: hash: type: string @@ -2218,6 +2319,8 @@ components: PipelineReloadStats: type: object + required: + - reloads properties: reloads: type: object @@ -2242,6 +2345,8 @@ components: ReloadStats: type: object + required: + - reloads properties: reloads: type: object @@ -2314,6 +2419,8 @@ components: format: int64 PipelineQueueStats: type: object + required: + - queue properties: queue: type: object @@ -2327,6 +2434,8 @@ components: persisted: "#/components/schemas/PipelineQueueStatsPersisted" QueueStats: type: object + required: + - queue properties: queue: type: object From 2d9b197c0bd6acd3eac6b5c5750d66dc96211cfc Mon Sep 17 00:00:00 2001 From: Ry Biesemeyer Date: Mon, 17 Mar 2025 17:50:00 +0000 Subject: [PATCH 09/11] openapi docs: mark non-composable atoms prohibiting additional fields --- docs/static/spec/openapi/logstash-api.yaml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/static/spec/openapi/logstash-api.yaml b/docs/static/spec/openapi/logstash-api.yaml index 793e032452f..91ca2aa3d5e 100644 --- a/docs/static/spec/openapi/logstash-api.yaml +++ b/docs/static/spec/openapi/logstash-api.yaml @@ -1448,6 +1448,7 @@ paths: - time - busiest_threads - threads + additionalProperties: false examples: nodeHotThreadsExample1: value: @@ -1794,6 +1795,7 @@ components: type: integer batch_delay: type: integer + additionalProperties: false NodeInfoPipeline: type: object @@ -1810,6 +1812,7 @@ components: type: integer dead_letter_queue_enabled: type: boolean + additionalProperties: false Status: type: string @@ -2006,6 +2009,7 @@ components: queue_push_duration_in_millis: type: integer format: int64 + additionalProperties: false JVMStats: type: object @@ -2200,6 +2204,7 @@ components: $ref: "#/components/schemas/ThroughputStats" events: $ref: "#/components/schemas/InputPluginEventsStats" + additionalProperties: false FilterOutputPluginEventsStats: type: object properties: @@ -2300,6 +2305,7 @@ components: type: array items: $ref: "#/components/schemas/FilterOutputPluginStats" + additionalProperties: false - $ref: "#/components/schemas/PipelineReloadStats" - $ref: "#/components/schemas/PipelineQueueStats" - $ref: "#/components/schemas/PipelineSettings" From 1cbdb7dac827ced8fcb1bd07c7b10222315aa6ef Mon Sep 17 00:00:00 2001 From: Ry Biesemeyer Date: Mon, 17 Mar 2025 17:50:38 +0000 Subject: [PATCH 10/11] openapi docs: minor health report fixes --- docs/static/spec/openapi/logstash-api.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/static/spec/openapi/logstash-api.yaml b/docs/static/spec/openapi/logstash-api.yaml index 91ca2aa3d5e..7b601331799 100644 --- a/docs/static/spec/openapi/logstash-api.yaml +++ b/docs/static/spec/openapi/logstash-api.yaml @@ -1543,7 +1543,8 @@ paths: type: object patternProperties: "^(?.+)$": - description: "pipeline name" + description: | + An indicator for the individual named pipeline type: object required: - status @@ -1826,9 +1827,9 @@ components: - `red`: Logstash is experiencing an outage or certain features are unavailable for use. enum: - green - - red - unknown - yellow + - red FlowValue: description: | From 134a6bc02d7c0b33b6b72ed72368950b8bdbd8d7 Mon Sep 17 00:00:00 2001 From: Ry Biesemeyer Date: Tue, 18 Mar 2025 22:38:48 +0000 Subject: [PATCH 11/11] openapi: specify server with variables to get default localhost:9600 --- docs/static/spec/openapi/logstash-api.yaml | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/static/spec/openapi/logstash-api.yaml b/docs/static/spec/openapi/logstash-api.yaml index 7b601331799..1f536d30d82 100644 --- a/docs/static/spec/openapi/logstash-api.yaml +++ b/docs/static/spec/openapi/logstash-api.yaml @@ -27,7 +27,19 @@ info: 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: / + - url: "{scheme}://{address}:{port}" + variables: + scheme: + default: http + enum: + - http + - https + address: + default: localhost + description: the hostname or ip address of your logstash instance + port: + default: 9600 + description: the port on which your Logstash API is running security: - {} # Allows requests without authentication - BasicAuth: [] # Allows requests with Basic Authentication