You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
626 lines
31 KiB
626 lines
31 KiB
// Copyright The Prometheus Authors
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
// you may not use this file except in compliance with the License.
|
|
// You may obtain a copy of the License at
|
|
//
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
|
//
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
// See the License for the specific language governing permissions and
|
|
// limitations under the License.
|
|
|
|
// This file defines all API path specifications including parameters, request bodies,
|
|
// and response schemas. Each path definition corresponds to an endpoint registered in api.go.
|
|
package v1
|
|
|
|
import (
|
|
"time"
|
|
|
|
"github.com/pb33f/libopenapi/datamodel/high/base"
|
|
v3 "github.com/pb33f/libopenapi/datamodel/high/v3"
|
|
"github.com/pb33f/libopenapi/orderedmap"
|
|
)
|
|
|
|
// Path definition methods for API endpoints.
|
|
|
|
func (*OpenAPIBuilder) queryPath() *v3.PathItem {
|
|
params := []*v3.Parameter{
|
|
queryParamWithExample("limit", "The maximum number of metrics to return.", false, integerSchema(), []example{{"example", 100}}),
|
|
queryParamWithExample("time", "The evaluation timestamp (optional, defaults to current time).", false, timestampSchema(), timestampExamples(exampleTime)),
|
|
queryParamWithExample("query", "The PromQL query to execute.", true, stringSchema(), []example{{"example", "up"}}),
|
|
queryParamWithExample("timeout", "Evaluation timeout. Optional. Defaults to and is capped by the value of the -query.timeout flag.", false, stringSchema(), []example{{"example", "30s"}}),
|
|
queryParamWithExample("lookback_delta", "Override the lookback period for this query. Optional.", false, stringSchema(), []example{{"example", "5m"}}),
|
|
queryParamWithExample("stats", "When provided, include query statistics in the response. The special value 'all' enables more comprehensive statistics.", false, stringSchema(), []example{{"example", "all"}}),
|
|
}
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "query",
|
|
Summary: "Evaluate an instant query",
|
|
Tags: []string{"query"},
|
|
Parameters: params,
|
|
Responses: responsesWithErrorExamples("QueryOutputBody", queryResponseExamples(), errorResponseExamples(), "Query executed successfully.", "Error executing query."),
|
|
},
|
|
Post: &v3.Operation{
|
|
OperationId: "query-post",
|
|
Summary: "Evaluate an instant query",
|
|
Tags: []string{"query"},
|
|
RequestBody: formRequestBodyWithExamples("QueryPostInputBody", queryPostExamples(), "Submit an instant query. This endpoint accepts the same parameters as the GET version."),
|
|
Responses: responsesWithErrorExamples("QueryOutputBody", queryResponseExamples(), errorResponseExamples(), "Instant query executed successfully.", "Error executing instant query."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) queryRangePath() *v3.PathItem {
|
|
params := []*v3.Parameter{
|
|
queryParamWithExample("limit", "The maximum number of metrics to return.", false, integerSchema(), []example{{"example", 100}}),
|
|
queryParamWithExample("start", "The start time of the query.", true, timestampSchema(), timestampExamples(exampleTime.Add(-1*time.Hour))),
|
|
queryParamWithExample("end", "The end time of the query.", true, timestampSchema(), timestampExamples(exampleTime)),
|
|
queryParamWithExample("step", "The step size of the query.", true, stringSchema(), []example{{"example", "15s"}}),
|
|
queryParamWithExample("query", "The query to execute.", true, stringSchema(), []example{{"example", "rate(prometheus_http_requests_total{handler=\"/api/v1/query\"}[5m])"}}),
|
|
queryParamWithExample("timeout", "Evaluation timeout. Optional. Defaults to and is capped by the value of the -query.timeout flag.", false, stringSchema(), []example{{"example", "30s"}}),
|
|
queryParamWithExample("lookback_delta", "Override the lookback period for this query. Optional.", false, stringSchema(), []example{{"example", "5m"}}),
|
|
queryParamWithExample("stats", "When provided, include query statistics in the response. The special value 'all' enables more comprehensive statistics.", false, stringSchema(), []example{{"example", "all"}}),
|
|
}
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "query-range",
|
|
Summary: "Evaluate a range query",
|
|
Tags: []string{"query"},
|
|
Parameters: params,
|
|
Responses: responsesWithErrorExamples("QueryRangeOutputBody", queryRangeResponseExamples(), errorResponseExamples(), "Range query executed successfully.", "Error executing range query."),
|
|
},
|
|
Post: &v3.Operation{
|
|
OperationId: "query-range-post",
|
|
Summary: "Evaluate a range query",
|
|
Tags: []string{"query"},
|
|
RequestBody: formRequestBodyWithExamples("QueryRangePostInputBody", queryRangePostExamples(), "Submit a range query. This endpoint accepts the same parameters as the GET version."),
|
|
Responses: responsesWithErrorExamples("QueryRangeOutputBody", queryRangeResponseExamples(), errorResponseExamples(), "Range query executed successfully.", "Error executing range query."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) queryExemplarsPath() *v3.PathItem {
|
|
params := []*v3.Parameter{
|
|
queryParamWithExample("start", "Start timestamp for exemplars query.", false, timestampSchema(), timestampExamples(exampleTime.Add(-1*time.Hour))),
|
|
queryParamWithExample("end", "End timestamp for exemplars query.", false, timestampSchema(), timestampExamples(exampleTime)),
|
|
queryParamWithExample("query", "PromQL query to extract exemplars for.", true, stringSchema(), []example{{"example", "prometheus_http_requests_total"}}),
|
|
}
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "query-exemplars",
|
|
Summary: "Query exemplars",
|
|
Tags: []string{"query"},
|
|
Parameters: params,
|
|
Responses: responsesWithErrorExamples("QueryExemplarsOutputBody", queryExemplarsResponseExamples(), errorResponseExamples(), "Exemplars retrieved successfully.", "Error retrieving exemplars."),
|
|
},
|
|
Post: &v3.Operation{
|
|
OperationId: "query-exemplars-post",
|
|
Summary: "Query exemplars",
|
|
Tags: []string{"query"},
|
|
RequestBody: formRequestBodyWithExamples("QueryExemplarsPostInputBody", queryExemplarsPostExamples(), "Submit an exemplars query. This endpoint accepts the same parameters as the GET version."),
|
|
Responses: responsesWithErrorExamples("QueryExemplarsOutputBody", queryExemplarsResponseExamples(), errorResponseExamples(), "Exemplars query completed successfully.", "Error processing exemplars query."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) formatQueryPath() *v3.PathItem {
|
|
params := []*v3.Parameter{
|
|
queryParamWithExample("query", "PromQL expression to format.", true, stringSchema(), []example{{"example", "sum(rate(http_requests_total[5m])) by (job)"}}),
|
|
}
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "format-query",
|
|
Summary: "Format a PromQL query",
|
|
Tags: []string{"query"},
|
|
Parameters: params,
|
|
Responses: responsesWithErrorExamples("FormatQueryOutputBody", formatQueryResponseExamples(), errorResponseExamples(), "Query formatted successfully.", "Error formatting query."),
|
|
},
|
|
Post: &v3.Operation{
|
|
OperationId: "format-query-post",
|
|
Summary: "Format a PromQL query",
|
|
Tags: []string{"query"},
|
|
RequestBody: formRequestBodyWithExamples("FormatQueryPostInputBody", formatQueryPostExamples(), "Submit a PromQL query to format. This endpoint accepts the same parameters as the GET version."),
|
|
Responses: responsesWithErrorExamples("FormatQueryOutputBody", formatQueryResponseExamples(), errorResponseExamples(), "Query formatting completed successfully.", "Error formatting query."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) parseQueryPath() *v3.PathItem {
|
|
params := []*v3.Parameter{
|
|
queryParamWithExample("query", "PromQL expression to parse.", true, stringSchema(), []example{{"example", "up{job=\"prometheus\"}"}}),
|
|
}
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "parse-query",
|
|
Summary: "Parse a PromQL query",
|
|
Tags: []string{"query"},
|
|
Parameters: params,
|
|
Responses: responsesWithErrorExamples("ParseQueryOutputBody", parseQueryResponseExamples(), errorResponseExamples(), "Query parsed successfully.", "Error parsing query."),
|
|
},
|
|
Post: &v3.Operation{
|
|
OperationId: "parse-query-post",
|
|
Summary: "Parse a PromQL query",
|
|
Tags: []string{"query"},
|
|
RequestBody: formRequestBodyWithExamples("ParseQueryPostInputBody", parseQueryPostExamples(), "Submit a PromQL query to parse. This endpoint accepts the same parameters as the GET version."),
|
|
Responses: responsesWithErrorExamples("ParseQueryOutputBody", parseQueryResponseExamples(), errorResponseExamples(), "Query parsed successfully via POST.", "Error parsing query via POST."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) labelsPath() *v3.PathItem {
|
|
params := []*v3.Parameter{
|
|
queryParamWithExample("start", "Start timestamp for label names query.", false, timestampSchema(), timestampExamples(exampleTime.Add(-1*time.Hour))),
|
|
queryParamWithExample("end", "End timestamp for label names query.", false, timestampSchema(), timestampExamples(exampleTime)),
|
|
queryParamWithExample("match[]", "Series selector argument.", false, base.CreateSchemaProxy(&base.Schema{
|
|
Type: []string{"array"},
|
|
Items: &base.DynamicValue[*base.SchemaProxy, bool]{A: stringSchema()},
|
|
}), []example{{"example", []string{"{job=\"prometheus\"}"}}}),
|
|
queryParamWithExample("limit", "Maximum number of label names to return.", false, integerSchema(), []example{{"example", 100}}),
|
|
}
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "labels",
|
|
Summary: "Get label names",
|
|
Tags: []string{"labels"},
|
|
Parameters: params,
|
|
Responses: responsesWithErrorExamples("LabelsOutputBody", labelsResponseExamples(), errorResponseExamples(), "Label names retrieved successfully.", "Error retrieving label names."),
|
|
},
|
|
Post: &v3.Operation{
|
|
OperationId: "labels-post",
|
|
Summary: "Get label names",
|
|
Tags: []string{"labels"},
|
|
RequestBody: formRequestBodyWithExamples("LabelsPostInputBody", labelsPostExamples(), "Submit a label names query. This endpoint accepts the same parameters as the GET version."),
|
|
Responses: responsesWithErrorExamples("LabelsOutputBody", labelsResponseExamples(), errorResponseExamples(), "Label names retrieved successfully via POST.", "Error retrieving label names via POST."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) labelValuesPath() *v3.PathItem {
|
|
params := []*v3.Parameter{
|
|
pathParam("name", "Label name.", stringSchema()),
|
|
queryParamWithExample("start", "Start timestamp for label values query.", false, timestampSchema(), timestampExamples(exampleTime.Add(-1*time.Hour))),
|
|
queryParamWithExample("end", "End timestamp for label values query.", false, timestampSchema(), timestampExamples(exampleTime)),
|
|
queryParamWithExample("match[]", "Series selector argument.", false, base.CreateSchemaProxy(&base.Schema{
|
|
Type: []string{"array"},
|
|
Items: &base.DynamicValue[*base.SchemaProxy, bool]{A: stringSchema()},
|
|
}), []example{{"example", []string{"{job=\"prometheus\"}"}}}),
|
|
queryParamWithExample("limit", "Maximum number of label values to return.", false, integerSchema(), []example{{"example", 1000}}),
|
|
}
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "label-values",
|
|
Summary: "Get label values",
|
|
Tags: []string{"labels"},
|
|
Parameters: params,
|
|
Responses: responsesWithErrorExamples("LabelValuesOutputBody", labelValuesResponseExamples(), errorResponseExamples(), "Label values retrieved successfully.", "Error retrieving label values."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) seriesPath() *v3.PathItem {
|
|
params := []*v3.Parameter{
|
|
queryParamWithExample("start", "Start timestamp for series query.", false, timestampSchema(), timestampExamples(exampleTime.Add(-1*time.Hour))),
|
|
queryParamWithExample("end", "End timestamp for series query.", false, timestampSchema(), timestampExamples(exampleTime)),
|
|
queryParamWithExample("match[]", "Series selector argument.", true, base.CreateSchemaProxy(&base.Schema{
|
|
Type: []string{"array"},
|
|
Items: &base.DynamicValue[*base.SchemaProxy, bool]{A: stringSchema()},
|
|
}), []example{{"example", []string{"{job=\"prometheus\"}"}}}),
|
|
queryParamWithExample("limit", "Maximum number of series to return.", false, integerSchema(), []example{{"example", 100}}),
|
|
}
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "series",
|
|
Summary: "Find series by label matchers",
|
|
Tags: []string{"series"},
|
|
Parameters: params,
|
|
Responses: responsesWithErrorExamples("SeriesOutputBody", seriesResponseExamples(), errorResponseExamples(), "Series returned matching the provided label matchers.", "Error retrieving series."),
|
|
},
|
|
Post: &v3.Operation{
|
|
OperationId: "series-post",
|
|
Summary: "Find series by label matchers",
|
|
Tags: []string{"series"},
|
|
RequestBody: formRequestBodyWithExamples("SeriesPostInputBody", seriesPostExamples(), "Submit a series query. This endpoint accepts the same parameters as the GET version."),
|
|
Responses: responsesWithErrorExamples("SeriesOutputBody", seriesResponseExamples(), errorResponseExamples(), "Series returned matching the provided label matchers via POST.", "Error retrieving series via POST."),
|
|
},
|
|
Delete: &v3.Operation{
|
|
OperationId: "delete-series",
|
|
Summary: "Delete series",
|
|
Description: "Delete series matching selectors. Note: This is deprecated, use POST /admin/tsdb/delete_series instead.",
|
|
Tags: []string{"series"},
|
|
Responses: responsesWithErrorExamples("SeriesDeleteOutputBody", seriesDeleteResponseExamples(), errorResponseExamples(), "Series marked for deletion.", "Error deleting series."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) metadataPath() *v3.PathItem {
|
|
params := []*v3.Parameter{
|
|
queryParamWithExample("limit", "The maximum number of metrics to return.", false, integerSchema(), []example{{"example", 100}}),
|
|
queryParamWithExample("limit_per_metric", "The maximum number of metadata entries per metric.", false, integerSchema(), []example{{"example", 10}}),
|
|
queryParamWithExample("metric", "A metric name to filter metadata for.", false, stringSchema(), []example{{"example", "http_requests_total"}}),
|
|
}
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "get-metadata",
|
|
Summary: "Get metadata",
|
|
Tags: []string{"metadata"},
|
|
Parameters: params,
|
|
Responses: responsesWithErrorExamples("MetadataOutputBody", metadataResponseExamples(), errorResponseExamples(), "Metric metadata retrieved successfully.", "Error retrieving metadata."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) scrapePoolsPath() *v3.PathItem {
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "get-scrape-pools",
|
|
Summary: "Get scrape pools",
|
|
Tags: []string{"targets"},
|
|
Responses: responsesWithErrorExamples("ScrapePoolsOutputBody", scrapePoolsResponseExamples(), errorResponseExamples(), "Scrape pools retrieved successfully.", "Error retrieving scrape pools."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) targetsPath() *v3.PathItem {
|
|
params := []*v3.Parameter{
|
|
queryParamWithExample("scrapePool", "Filter targets by scrape pool name.", false, stringSchema(), []example{{"example", "prometheus"}}),
|
|
queryParamWithExample("state", "Filter by state: active, dropped, or any.", false, stringSchema(), []example{{"example", "active"}}),
|
|
}
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "get-targets",
|
|
Summary: "Get targets",
|
|
Tags: []string{"targets"},
|
|
Parameters: params,
|
|
Responses: responsesWithErrorExamples("TargetsOutputBody", targetsResponseExamples(), errorResponseExamples(), "Target discovery information retrieved successfully.", "Error retrieving targets."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) targetsMetadataPath() *v3.PathItem {
|
|
params := []*v3.Parameter{
|
|
queryParamWithExample("match_target", "Label selector to filter targets.", false, stringSchema(), []example{{"example", "{job=\"prometheus\"}"}}),
|
|
queryParamWithExample("metric", "Metric name to retrieve metadata for.", false, stringSchema(), []example{{"example", "http_requests_total"}}),
|
|
queryParamWithExample("limit", "Maximum number of targets to match.", false, integerSchema(), []example{{"example", 10}}),
|
|
}
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "get-targets-metadata",
|
|
Summary: "Get targets metadata",
|
|
Tags: []string{"targets"},
|
|
Parameters: params,
|
|
Responses: responsesWithErrorExamples("TargetMetadataOutputBody", targetsMetadataResponseExamples(), errorResponseExamples(), "Target metadata retrieved successfully.", "Error retrieving target metadata."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) targetsRelabelStepsPath() *v3.PathItem {
|
|
params := []*v3.Parameter{
|
|
queryParamWithExample("scrapePool", "Name of the scrape pool.", true, stringSchema(), []example{{"example", "prometheus"}}),
|
|
queryParamWithExample("labels", "JSON-encoded labels to apply relabel rules to.", true, stringSchema(), []example{{"example", "{\"__address__\":\"localhost:9090\",\"job\":\"prometheus\"}"}}),
|
|
}
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "get-targets-relabel-steps",
|
|
Summary: "Get targets relabel steps",
|
|
Tags: []string{"targets"},
|
|
Parameters: params,
|
|
Responses: responsesWithErrorExamples("TargetRelabelStepsOutputBody", targetsRelabelStepsResponseExamples(), errorResponseExamples(), "Relabel steps retrieved successfully.", "Error retrieving relabel steps."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) rulesPath() *v3.PathItem {
|
|
params := []*v3.Parameter{
|
|
queryParamWithExample("type", "Filter by rule type: alert or record.", false, stringSchema(), []example{{"example", "alert"}}),
|
|
queryParamWithExample("rule_name[]", "Filter by rule name.", false, base.CreateSchemaProxy(&base.Schema{
|
|
Type: []string{"array"},
|
|
Items: &base.DynamicValue[*base.SchemaProxy, bool]{A: stringSchema()},
|
|
}), []example{{"example", []string{"HighErrorRate"}}}),
|
|
queryParamWithExample("rule_group[]", "Filter by rule group name.", false, base.CreateSchemaProxy(&base.Schema{
|
|
Type: []string{"array"},
|
|
Items: &base.DynamicValue[*base.SchemaProxy, bool]{A: stringSchema()},
|
|
}), []example{{"example", []string{"example_alerts"}}}),
|
|
queryParamWithExample("file[]", "Filter by file path.", false, base.CreateSchemaProxy(&base.Schema{
|
|
Type: []string{"array"},
|
|
Items: &base.DynamicValue[*base.SchemaProxy, bool]{A: stringSchema()},
|
|
}), []example{{"example", []string{"/etc/prometheus/rules.yml"}}}),
|
|
queryParamWithExample("match[]", "Label matchers to filter rules.", false, base.CreateSchemaProxy(&base.Schema{
|
|
Type: []string{"array"},
|
|
Items: &base.DynamicValue[*base.SchemaProxy, bool]{A: stringSchema()},
|
|
}), []example{{"example", []string{"{severity=\"critical\"}"}}}),
|
|
queryParamWithExample("exclude_alerts", "Exclude active alerts from response.", false, stringSchema(), []example{{"example", "false"}}),
|
|
queryParamWithExample("group_limit", "Maximum number of rule groups to return.", false, integerSchema(), []example{{"example", 100}}),
|
|
queryParamWithExample("group_next_token", "Pagination token for next page.", false, stringSchema(), []example{{"example", "abc123"}}),
|
|
}
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "rules",
|
|
Summary: "Get alerting and recording rules",
|
|
Tags: []string{"rules"},
|
|
Parameters: params,
|
|
Responses: responsesWithErrorExamples("RulesOutputBody", rulesResponseExamples(), errorResponseExamples(), "Rules retrieved successfully.", "Error retrieving rules."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) alertsPath() *v3.PathItem {
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "alerts",
|
|
Summary: "Get active alerts",
|
|
Tags: []string{"alerts"},
|
|
Responses: responsesWithErrorExamples("AlertsOutputBody", alertsResponseExamples(), errorResponseExamples(), "Active alerts retrieved successfully.", "Error retrieving alerts."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) alertmanagersPath() *v3.PathItem {
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "alertmanagers",
|
|
Summary: "Get Alertmanager discovery",
|
|
Tags: []string{"alerts"},
|
|
Responses: responsesWithErrorExamples("AlertmanagersOutputBody", alertmanagersResponseExamples(), errorResponseExamples(), "Alertmanager targets retrieved successfully.", "Error retrieving Alertmanager targets."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) statusConfigPath() *v3.PathItem {
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "get-status-config",
|
|
Summary: "Get status config",
|
|
Tags: []string{"status"},
|
|
Responses: responsesWithErrorExamples("StatusConfigOutputBody", statusConfigResponseExamples(), errorResponseExamples(), "Configuration retrieved successfully.", "Error retrieving configuration."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) statusRuntimeInfoPath() *v3.PathItem {
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "get-status-runtimeinfo",
|
|
Summary: "Get status runtimeinfo",
|
|
Tags: []string{"status"},
|
|
Responses: responsesWithErrorExamples("StatusRuntimeInfoOutputBody", statusRuntimeInfoResponseExamples(), errorResponseExamples(), "Runtime information retrieved successfully.", "Error retrieving runtime information."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) statusBuildInfoPath() *v3.PathItem {
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "get-status-buildinfo",
|
|
Summary: "Get status buildinfo",
|
|
Tags: []string{"status"},
|
|
Responses: responsesWithErrorExamples("StatusBuildInfoOutputBody", statusBuildInfoResponseExamples(), errorResponseExamples(), "Build information retrieved successfully.", "Error retrieving build information."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) statusFlagsPath() *v3.PathItem {
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "get-status-flags",
|
|
Summary: "Get status flags",
|
|
Tags: []string{"status"},
|
|
Responses: responsesWithErrorExamples("StatusFlagsOutputBody", statusFlagsResponseExamples(), errorResponseExamples(), "Command-line flags retrieved successfully.", "Error retrieving flags."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) statusTSDBPath() *v3.PathItem {
|
|
params := []*v3.Parameter{
|
|
queryParamWithExample("limit", "The maximum number of items to return per category.", false, integerSchema(), []example{{"example", 10}}),
|
|
}
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "status-tsdb",
|
|
Summary: "Get TSDB status",
|
|
Tags: []string{"status"},
|
|
Parameters: params,
|
|
Responses: responsesWithErrorExamples("StatusTSDBOutputBody", statusTSDBResponseExamples(), errorResponseExamples(), "TSDB status retrieved successfully.", "Error retrieving TSDB status."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) statusTSDBBlocksPath() *v3.PathItem {
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "status-tsdb-blocks",
|
|
Summary: "Get TSDB blocks information",
|
|
Tags: []string{"status"},
|
|
Responses: responsesWithErrorExamples("StatusTSDBBlocksOutputBody", statusTSDBBlocksResponseExamples(), errorResponseExamples(), "TSDB blocks information retrieved successfully.", "Error retrieving TSDB blocks."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) statusWALReplayPath() *v3.PathItem {
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "get-status-walreplay",
|
|
Summary: "Get status walreplay",
|
|
Tags: []string{"status"},
|
|
Responses: responsesWithErrorExamples("StatusWALReplayOutputBody", statusWALReplayResponseExamples(), errorResponseExamples(), "WAL replay status retrieved successfully.", "Error retrieving WAL replay status."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) adminDeleteSeriesPath() *v3.PathItem {
|
|
params := []*v3.Parameter{
|
|
queryParamWithExample("match[]", "Series selectors to identify series to delete.", true, base.CreateSchemaProxy(&base.Schema{
|
|
Type: []string{"array"},
|
|
Items: &base.DynamicValue[*base.SchemaProxy, bool]{A: stringSchema()},
|
|
}), []example{{"example", []string{"{__name__=~\"test.*\"}"}}}),
|
|
queryParamWithExample("start", "Start timestamp for deletion.", false, timestampSchema(), timestampExamples(exampleTime.Add(-1*time.Hour))),
|
|
queryParamWithExample("end", "End timestamp for deletion.", false, timestampSchema(), timestampExamples(exampleTime)),
|
|
}
|
|
return &v3.PathItem{
|
|
Post: &v3.Operation{
|
|
OperationId: "deleteSeriesPost",
|
|
Summary: "Delete series matching selectors",
|
|
Description: "Deletes data for a selection of series in a time range.",
|
|
Tags: []string{"admin"},
|
|
Parameters: params,
|
|
Responses: responsesWithErrorExamples("DeleteSeriesOutputBody", deleteSeriesResponseExamples(), errorResponseExamples(), "Series deleted successfully.", "Error deleting series."),
|
|
},
|
|
Put: &v3.Operation{
|
|
OperationId: "deleteSeriesPut",
|
|
Summary: "Delete series matching selectors via PUT",
|
|
Description: "Deletes data for a selection of series in a time range using PUT method.",
|
|
Tags: []string{"admin"},
|
|
Parameters: params,
|
|
Responses: responsesWithErrorExamples("DeleteSeriesOutputBody", deleteSeriesResponseExamples(), errorResponseExamples(), "Series deleted successfully via PUT.", "Error deleting series via PUT."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) adminCleanTombstonesPath() *v3.PathItem {
|
|
return &v3.PathItem{
|
|
Post: &v3.Operation{
|
|
OperationId: "cleanTombstonesPost",
|
|
Summary: "Clean tombstones in the TSDB",
|
|
Description: "Removes deleted data from disk and cleans up existing tombstones.",
|
|
Tags: []string{"admin"},
|
|
Responses: responsesWithErrorExamples("CleanTombstonesOutputBody", cleanTombstonesResponseExamples(), errorResponseExamples(), "Tombstones cleaned successfully.", "Error cleaning tombstones."),
|
|
},
|
|
Put: &v3.Operation{
|
|
OperationId: "cleanTombstonesPut",
|
|
Summary: "Clean tombstones in the TSDB via PUT",
|
|
Description: "Removes deleted data from disk and cleans up existing tombstones using PUT method.",
|
|
Tags: []string{"admin"},
|
|
Responses: responsesWithErrorExamples("CleanTombstonesOutputBody", cleanTombstonesResponseExamples(), errorResponseExamples(), "Tombstones cleaned successfully via PUT.", "Error cleaning tombstones via PUT."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) adminSnapshotPath() *v3.PathItem {
|
|
params := []*v3.Parameter{
|
|
queryParamWithExample("skip_head", "If true, do not snapshot data in the head block.", false, stringSchema(), []example{{"example", "false"}}),
|
|
}
|
|
return &v3.PathItem{
|
|
Post: &v3.Operation{
|
|
OperationId: "snapshotPost",
|
|
Summary: "Create a snapshot of the TSDB",
|
|
Description: "Creates a snapshot of all current data.",
|
|
Tags: []string{"admin"},
|
|
Parameters: params,
|
|
Responses: responsesWithErrorExamples("SnapshotOutputBody", snapshotResponseExamples(), errorResponseExamples(), "Snapshot created successfully.", "Error creating snapshot."),
|
|
},
|
|
Put: &v3.Operation{
|
|
OperationId: "snapshotPut",
|
|
Summary: "Create a snapshot of the TSDB via PUT",
|
|
Description: "Creates a snapshot of all current data using PUT method.",
|
|
Tags: []string{"admin"},
|
|
Parameters: params,
|
|
Responses: responsesWithErrorExamples("SnapshotOutputBody", snapshotResponseExamples(), errorResponseExamples(), "Snapshot created successfully via PUT.", "Error creating snapshot via PUT."),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) remoteReadPath() *v3.PathItem {
|
|
return &v3.PathItem{
|
|
Post: &v3.Operation{
|
|
OperationId: "remoteRead",
|
|
Summary: "Remote read endpoint",
|
|
Description: "Prometheus remote read endpoint for federated queries. Accepts and returns Protocol Buffer encoded data.",
|
|
Tags: []string{"remote"},
|
|
Responses: responsesNoContent(),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) remoteWritePath() *v3.PathItem {
|
|
return &v3.PathItem{
|
|
Post: &v3.Operation{
|
|
OperationId: "remoteWrite",
|
|
Summary: "Remote write endpoint",
|
|
Description: "Prometheus remote write endpoint for sending metrics. Accepts Protocol Buffer encoded write requests.",
|
|
Tags: []string{"remote"},
|
|
Responses: responsesNoContent(),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) otlpWritePath() *v3.PathItem {
|
|
return &v3.PathItem{
|
|
Post: &v3.Operation{
|
|
OperationId: "otlpWrite",
|
|
Summary: "OTLP metrics write endpoint",
|
|
Description: "OpenTelemetry Protocol metrics ingestion endpoint. Accepts OTLP/HTTP metrics in Protocol Buffer format.",
|
|
Tags: []string{"otlp"},
|
|
Responses: responsesNoContent(),
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) notificationsPath() *v3.PathItem {
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "get-notifications",
|
|
Summary: "Get notifications",
|
|
Tags: []string{"notifications"},
|
|
Responses: responsesWithErrorExamples("NotificationsOutputBody", notificationsResponseExamples(), errorResponseExamples(), "Notifications retrieved successfully.", "Error retrieving notifications."),
|
|
},
|
|
}
|
|
}
|
|
|
|
// notificationsLivePath defines the /notifications/live endpoint.
|
|
// This endpoint uses OpenAPI 3.2's itemSchema feature for documenting SSE streams.
|
|
// It is excluded from the OpenAPI 3.1 specification.
|
|
func (*OpenAPIBuilder) notificationsLivePath() *v3.PathItem {
|
|
codes := orderedmap.New[string, *v3.Response]()
|
|
content := orderedmap.New[string, *v3.MediaType]()
|
|
|
|
// Create a schema for the SSE message structure.
|
|
// Each SSE message has a 'data' field containing JSON.
|
|
sseItemProps := orderedmap.New[string, *base.SchemaProxy]()
|
|
sseItemProps.Set("data", base.CreateSchemaProxy(&base.Schema{
|
|
Type: []string{"string"},
|
|
Description: "SSE data field containing JSON-encoded notification.",
|
|
ContentMediaType: "application/json",
|
|
ContentSchema: schemaRef("#/components/schemas/Notification"),
|
|
}))
|
|
|
|
content.Set("text/event-stream", &v3.MediaType{
|
|
// Use ItemSchema (OpenAPI 3.2) instead of Schema to describe each SSE message.
|
|
ItemSchema: base.CreateSchemaProxy(&base.Schema{
|
|
Type: []string{"object"},
|
|
Title: "Server Sent Event Message",
|
|
Description: "A single SSE message. The data field contains a JSON-encoded Notification object.",
|
|
Properties: sseItemProps,
|
|
Required: []string{"data"},
|
|
AdditionalProperties: &base.DynamicValue[*base.SchemaProxy, bool]{N: 1, B: false},
|
|
}),
|
|
Examples: notificationLiveExamples(),
|
|
})
|
|
|
|
codes.Set("200", &v3.Response{
|
|
Description: "Server-sent events stream established.",
|
|
Content: content,
|
|
})
|
|
codes.Set("default", errorResponse())
|
|
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "notifications-live",
|
|
Summary: "Stream live notifications via Server-Sent Events",
|
|
Description: "Subscribe to real-time server notifications using SSE. Each event contains a JSON-encoded Notification object in the data field.",
|
|
Tags: []string{"notifications"},
|
|
Responses: &v3.Responses{Codes: codes},
|
|
},
|
|
}
|
|
}
|
|
|
|
func (*OpenAPIBuilder) featuresPath() *v3.PathItem {
|
|
return &v3.PathItem{
|
|
Get: &v3.Operation{
|
|
OperationId: "get-features",
|
|
Summary: "Get features",
|
|
Tags: []string{"features"},
|
|
Responses: responsesWithErrorExamples("FeaturesOutputBody", featuresResponseExamples(), errorResponseExamples(), "Feature flags retrieved successfully.", "Error retrieving features."),
|
|
},
|
|
}
|
|
}
|
|
|