# Metrics
## Ingest CLI metrics events
> Ingest a batch of sfpowerscripts metrics events into VictoriaMetrics.\
> \
> \*\*Note:\*\* Only application tokens (CI/CD pipelines) can actually ingest metrics.\
> User tokens are silently accepted but not processed to simplify client-side logic.\
> \
> \*\*Metric Types:\*\*\
> \- \`count\`: Counter for discrete events (value auto-set to 1). Use for builds, deployments, failures.\
> \- \`guage\`: Point-in-time measurement. Use for pool sizes, queue depths.\
> \- \`timers\`: Duration measurement. Use for build time, deploy duration.\
> \
> \*\*Naming Convention:\*\* Use dot notation (e.g., \`sfpowerscripts.build.duration\`). Dots are automatically normalized for storage and querying.\
> \
> \*\*Deduplication:\*\* Metrics with identical name and tags are deduplicated within 5-minute windows.\
> \
> \*\*Retention:\*\* Metrics are retained for 12 months by default.
```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"MetricsIngestDto":{"type":"object","properties":{"events":{"type":"array","description":"A batch of metric events to ingest. Each event represents a single data point.\n\n**Supported Metric Types:**\n| Type | Value Required | Use Case | Example |\n|------|----------------|----------|---------|\n| `count` | No (auto=1) | Counting events | Builds, deployments, failures |\n| `guage` | Yes | Point-in-time values | Pool size, queue depth |\n| `timers` | Yes | Duration measurements | Build time, deploy duration |\n\n**Deduplication:** Metrics with identical name and tags within a 5-minute window are deduplicated.\n\n**Retention:** Metrics are retained for 12 months by default.","items":{"$ref":"#/components/schemas/MetricEventDto"}}},"required":["events"]},"MetricEventDto":{"type":"object","properties":{"metric":{"type":"string","description":"Metric name using dot notation. Names are sanitized: only alphanumeric, underscores, colons, and dots are allowed.","pattern":"^[a-zA-Z][a-zA-Z0-9_.:-]*$"},"type":{"$ref":"#/components/schemas/MetricType"},"value":{"type":"number","description":"Metric value. Required for `guage` and `timers` types. Ignored for `count` type (automatically set to 1)."},"timestamp":{"type":"number","description":"Unix timestamp in milliseconds when the metric was recorded."},"tags":{"description":"Additional dimensions/labels for the metric. Can be provided as:\n- **Object**: `{ \"package\": \"core\", \"org\": \"dev\" }`\n- **Array of strings**: `[\"package:core\", \"org:dev\"]` (colon-separated key:value pairs)\n\nTags are used for filtering and grouping in queries. A special `sfp_metric_type` tag is automatically added.","oneOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"array","items":{"type":"string","pattern":"^[^:]+:.+$"}}]}},"required":["metric","type","timestamp"]},"MetricType":{"type":"string","description":"Metric type determines how the value is interpreted:\n- **count**: Counter for discrete events. Value is automatically set to 1 (any provided value is ignored).\n- **guage**: Point-in-time measurement. Requires an explicit value.\n- **timers**: Duration/timing measurement. Requires an explicit value (typically milliseconds).","enum":["count","guage","timers"]},"MetricsIngestResponseDto":{"type":"object","properties":{"accepted":{"type":"number","description":"Number of events that were accepted and queued for ingestion."},"message":{"type":"string","description":"Optional message providing additional context about the ingestion."}},"required":["accepted"]}}},"paths":{"/sfp/api/metrics/ingest":{"post":{"operationId":"MetricsController_ingest","summary":"Ingest CLI metrics events","description":"Ingest a batch of sfpowerscripts metrics events into VictoriaMetrics.\n\n**Note:** Only application tokens (CI/CD pipelines) can actually ingest metrics.\nUser tokens are silently accepted but not processed to simplify client-side logic.\n\n**Metric Types:**\n- `count`: Counter for discrete events (value auto-set to 1). Use for builds, deployments, failures.\n- `guage`: Point-in-time measurement. Use for pool sizes, queue depths.\n- `timers`: Duration measurement. Use for build time, deploy duration.\n\n**Naming Convention:** Use dot notation (e.g., `sfpowerscripts.build.duration`). Dots are automatically normalized for storage and querying.\n\n**Deduplication:** Metrics with identical name and tags are deduplicated within 5-minute windows.\n\n**Retention:** Metrics are retained for 12 months by default.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsIngestDto"}}}},"responses":{"201":{"description":"Metrics accepted and queued for ingestion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsIngestResponseDto"}}}},"400":{"description":"Invalid request body - events array is empty or malformed"},"401":{"description":"Unauthorized - valid access token required"},"403":{"description":"Forbidden - Requires role: member, application"}},"tags":["Metrics"]}}}}
```
## Query metrics (instant query)
> Execute an instant query against VictoriaMetrics using MetricsQL/PromQL syntax.\
> \
> \*\*Query Examples:\*\*\
> \- \`sfpowerscripts.build.duration\` - Get latest value\
> \- \`sum(sfpowerscripts.build.completed)\` - Aggregate counts\
> \- \`sfpowerscripts.build.duration{package="core"}\` - Filter by tag\
> \- \`rate(sfpowerscripts.build.completed\[1h])\` - Calculate rate over 1 hour\
> \
> See \[MetricsQL documentation]\() for full syntax.
```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"MetricsQueryResponseDto":{"type":"object","properties":{"result":{"type":"object","description":"Opaque VictoriaMetrics response"}},"required":["result"]}}},"paths":{"/sfp/api/metrics/query":{"get":{"operationId":"MetricsController_query","summary":"Query metrics (instant query)","description":"Execute an instant query against VictoriaMetrics using MetricsQL/PromQL syntax.\n\n**Query Examples:**\n- `sfpowerscripts.build.duration` - Get latest value\n- `sum(sfpowerscripts.build.completed)` - Aggregate counts\n- `sfpowerscripts.build.duration{package=\"core\"}` - Filter by tag\n- `rate(sfpowerscripts.build.completed[1h])` - Calculate rate over 1 hour\n\nSee [MetricsQL documentation](https://docs.victoriametrics.com/metricsql/) for full syntax.","parameters":[{"name":"query","required":true,"in":"query","description":"MetricsQL / PromQL query expression","schema":{"type":"string"}},{"name":"time","required":false,"in":"query","description":"Evaluation timestamp (RFC3339 or unix seconds)","schema":{"type":"string"}},{"name":"timeout","required":false,"in":"query","description":"Query timeout (duration), forwarded to VictoriaMetrics","schema":{"type":"string"}}],"responses":{"200":{"description":"Query result from VictoriaMetrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsQueryResponseDto"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Requires role: member, application"}},"tags":["Metrics"]}}}}
```
## Query metrics (instant query)
> Execute an instant query against VictoriaMetrics using MetricsQL/PromQL syntax.\
> \
> \*\*Query Examples:\*\*\
> \- \`sfpowerscripts.build.duration\` - Get latest value\
> \- \`sum(sfpowerscripts.build.completed)\` - Aggregate counts\
> \- \`sfpowerscripts.build.duration{package="core"}\` - Filter by tag\
> \- \`rate(sfpowerscripts.build.completed\[1h])\` - Calculate rate over 1 hour\
> \
> See \[MetricsQL documentation]\() for full syntax.
```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"MetricsQueryResponseDto":{"type":"object","properties":{"result":{"type":"object","description":"Opaque VictoriaMetrics response"}},"required":["result"]}}},"paths":{"/sfp/api/metrics/api/v1/query":{"get":{"operationId":"MetricsController_query","summary":"Query metrics (instant query)","description":"Execute an instant query against VictoriaMetrics using MetricsQL/PromQL syntax.\n\n**Query Examples:**\n- `sfpowerscripts.build.duration` - Get latest value\n- `sum(sfpowerscripts.build.completed)` - Aggregate counts\n- `sfpowerscripts.build.duration{package=\"core\"}` - Filter by tag\n- `rate(sfpowerscripts.build.completed[1h])` - Calculate rate over 1 hour\n\nSee [MetricsQL documentation](https://docs.victoriametrics.com/metricsql/) for full syntax.","parameters":[{"name":"query","required":true,"in":"query","description":"MetricsQL / PromQL query expression","schema":{"type":"string"}},{"name":"time","required":false,"in":"query","description":"Evaluation timestamp (RFC3339 or unix seconds)","schema":{"type":"string"}},{"name":"timeout","required":false,"in":"query","description":"Query timeout (duration), forwarded to VictoriaMetrics","schema":{"type":"string"}}],"responses":{"200":{"description":"Query result from VictoriaMetrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsQueryResponseDto"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Requires role: member, application"}},"tags":["Metrics"]}}}}
```
## Query metrics over time range
> Execute a range query to get metrics over a time period with specified resolution.\
> \
> \*\*Use Cases:\*\*\
> \- Generate time-series data for charts\
> \- Analyze trends over time\
> \- Calculate aggregates across time windows\
> \
> \*\*Parameters:\*\*\
> \- \`start\`/\`end\`: Time range (RFC3339 or Unix seconds)\
> \- \`step\`: Resolution (e.g., \`30s\`, \`1m\`, \`5m\`, \`1h\`)\
> \
> \*\*Example:\*\* Query build durations over the last 24 hours with 1-hour resolution.
```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"MetricsQueryResponseDto":{"type":"object","properties":{"result":{"type":"object","description":"Opaque VictoriaMetrics response"}},"required":["result"]}}},"paths":{"/sfp/api/metrics/query_range":{"get":{"operationId":"MetricsController_queryRange","summary":"Query metrics over time range","description":"Execute a range query to get metrics over a time period with specified resolution.\n\n**Use Cases:**\n- Generate time-series data for charts\n- Analyze trends over time\n- Calculate aggregates across time windows\n\n**Parameters:**\n- `start`/`end`: Time range (RFC3339 or Unix seconds)\n- `step`: Resolution (e.g., `30s`, `1m`, `5m`, `1h`)\n\n**Example:** Query build durations over the last 24 hours with 1-hour resolution.","parameters":[{"name":"query","required":true,"in":"query","description":"MetricsQL / PromQL query expression","schema":{"type":"string"}},{"name":"start","required":true,"in":"query","description":"Range start (RFC3339 or unix seconds)","schema":{"type":"string"}},{"name":"end","required":true,"in":"query","description":"Range end (RFC3339 or unix seconds)","schema":{"type":"string"}},{"name":"step","required":true,"in":"query","description":"Step / resolution (duration, e.g. 30s, 1m)","schema":{"type":"string"}},{"name":"timeout","required":false,"in":"query","description":"Query timeout (duration), forwarded to VictoriaMetrics","schema":{"type":"string"}}],"responses":{"200":{"description":"Range query result with time-series data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsQueryResponseDto"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Requires role: member, application"}},"tags":["Metrics"]}}}}
```
## Query metrics over time range
> Execute a range query to get metrics over a time period with specified resolution.\
> \
> \*\*Use Cases:\*\*\
> \- Generate time-series data for charts\
> \- Analyze trends over time\
> \- Calculate aggregates across time windows\
> \
> \*\*Parameters:\*\*\
> \- \`start\`/\`end\`: Time range (RFC3339 or Unix seconds)\
> \- \`step\`: Resolution (e.g., \`30s\`, \`1m\`, \`5m\`, \`1h\`)\
> \
> \*\*Example:\*\* Query build durations over the last 24 hours with 1-hour resolution.
```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"MetricsQueryResponseDto":{"type":"object","properties":{"result":{"type":"object","description":"Opaque VictoriaMetrics response"}},"required":["result"]}}},"paths":{"/sfp/api/metrics/api/v1/query_range":{"get":{"operationId":"MetricsController_queryRange","summary":"Query metrics over time range","description":"Execute a range query to get metrics over a time period with specified resolution.\n\n**Use Cases:**\n- Generate time-series data for charts\n- Analyze trends over time\n- Calculate aggregates across time windows\n\n**Parameters:**\n- `start`/`end`: Time range (RFC3339 or Unix seconds)\n- `step`: Resolution (e.g., `30s`, `1m`, `5m`, `1h`)\n\n**Example:** Query build durations over the last 24 hours with 1-hour resolution.","parameters":[{"name":"query","required":true,"in":"query","description":"MetricsQL / PromQL query expression","schema":{"type":"string"}},{"name":"start","required":true,"in":"query","description":"Range start (RFC3339 or unix seconds)","schema":{"type":"string"}},{"name":"end","required":true,"in":"query","description":"Range end (RFC3339 or unix seconds)","schema":{"type":"string"}},{"name":"step","required":true,"in":"query","description":"Step / resolution (duration, e.g. 30s, 1m)","schema":{"type":"string"}},{"name":"timeout","required":false,"in":"query","description":"Query timeout (duration), forwarded to VictoriaMetrics","schema":{"type":"string"}}],"responses":{"200":{"description":"Range query result with time-series data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsQueryResponseDto"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Requires role: member, application"}},"tags":["Metrics"]}}}}
```
## List distinct label values
> Get all distinct values for a specific label/tag across metrics.\
> \
> \*\*Common Labels:\*\*\
> \- \`package\`: Package names\
> \- \`org\`: Org aliases\
> \- \`pipeline\`: Pipeline identifiers\
> \- \`sfp\_metric\_type\`: Metric type (count, guage, timers)\
> \- \`\_\_name\_\_\`: Metric names\
> \
> \*\*Use Cases:\*\*\
> \- Populate filter dropdowns in dashboards\
> \- Discover available dimensions for queries
```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"MetricsQueryResponseDto":{"type":"object","properties":{"result":{"type":"object","description":"Opaque VictoriaMetrics response"}},"required":["result"]}}},"paths":{"/sfp/api/metrics/label/{name}/values":{"get":{"operationId":"MetricsController_labelValues","summary":"List distinct label values","description":"Get all distinct values for a specific label/tag across metrics.\n\n**Common Labels:**\n- `package`: Package names\n- `org`: Org aliases\n- `pipeline`: Pipeline identifiers\n- `sfp_metric_type`: Metric type (count, guage, timers)\n- `__name__`: Metric names\n\n**Use Cases:**\n- Populate filter dropdowns in dashboards\n- Discover available dimensions for queries","parameters":[{"name":"name","required":true,"in":"path","schema":{"type":"string"}},{"name":"start","required":false,"in":"query","description":"Optional start time (RFC3339 or unix seconds)","schema":{"type":"string"}},{"name":"end","required":false,"in":"query","description":"Optional end time (RFC3339 or unix seconds)","schema":{"type":"string"}},{"name":"match","required":false,"in":"query","description":"Optional match[] selectors (repeatable)","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"List of distinct label values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsQueryResponseDto"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Requires role: member, application"}},"tags":["Metrics"]}}}}
```
## List distinct label values
> Get all distinct values for a specific label/tag across metrics.\
> \
> \*\*Common Labels:\*\*\
> \- \`package\`: Package names\
> \- \`org\`: Org aliases\
> \- \`pipeline\`: Pipeline identifiers\
> \- \`sfp\_metric\_type\`: Metric type (count, guage, timers)\
> \- \`\_\_name\_\_\`: Metric names\
> \
> \*\*Use Cases:\*\*\
> \- Populate filter dropdowns in dashboards\
> \- Discover available dimensions for queries
```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"MetricsQueryResponseDto":{"type":"object","properties":{"result":{"type":"object","description":"Opaque VictoriaMetrics response"}},"required":["result"]}}},"paths":{"/sfp/api/metrics/api/v1/label/{name}/values":{"get":{"operationId":"MetricsController_labelValues","summary":"List distinct label values","description":"Get all distinct values for a specific label/tag across metrics.\n\n**Common Labels:**\n- `package`: Package names\n- `org`: Org aliases\n- `pipeline`: Pipeline identifiers\n- `sfp_metric_type`: Metric type (count, guage, timers)\n- `__name__`: Metric names\n\n**Use Cases:**\n- Populate filter dropdowns in dashboards\n- Discover available dimensions for queries","parameters":[{"name":"name","required":true,"in":"path","schema":{"type":"string"}},{"name":"start","required":false,"in":"query","description":"Optional start time (RFC3339 or unix seconds)","schema":{"type":"string"}},{"name":"end","required":false,"in":"query","description":"Optional end time (RFC3339 or unix seconds)","schema":{"type":"string"}},{"name":"match","required":false,"in":"query","description":"Optional match[] selectors (repeatable)","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"List of distinct label values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsQueryResponseDto"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Requires role: member, application"}},"tags":["Metrics"]}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.flxbl.io/flxbl/sfp-server/api-reference/metrics.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.