Metrics | sfp server

Ingest CLI metrics events

post

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

Deduplication: Metrics with identical name and tags are deduplicated within 5-minute windows.

Retention: Metrics are retained for 12 months by default.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Type	Value Required	Use Case	Example
`count`	No (auto=1)	Counting events	Builds, deployments, failures
`guage`	Yes	Point-in-time values	Pool size, queue depth
`timers`	Yes	Duration measurements	Build time, deploy duration

Responses

201

Metrics accepted and queued for ingestion

application/json

400

Invalid request body - events array is empty or malformed

401

Unauthorized - valid access token required

post

/sfp/api/metrics/ingest

POST /sfp/api/metrics/ingest HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 423

{
  "events": [
    {
      "metric": "sfpowerscripts.build.duration",
      "type": "timers",
      "value": 45000,
      "timestamp": 1734019200000,
      "tags": {
        "package": "core-package",
        "org": "dev-sandbox"
      }
    },
    {
      "metric": "sfpowerscripts.build.completed",
      "type": "count",
      "timestamp": 1734019200000,
      "tags": {
        "package": "core-package",
        "status": "success"
      }
    },
    {
      "metric": "sfpowerscripts.pool.available",
      "type": "guage",
      "value": 5,
      "timestamp": 1734019200000,
      "tags": {
        "pool": "ci-pool"
      }
    }
  ]
}

{
  "accepted": 10
}

Query metrics (instant query)

get

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

querystringRequired

MetricsQL / PromQL query expression

Example: sum(rate(sfp_build_duration_seconds[5m]))

timestringOptional

Evaluation timestamp (RFC3339 or unix seconds)

Example: 1734019200

timeoutstringOptional

Query timeout (duration), forwarded to VictoriaMetrics

Example: 10s

Responses

200

Query result from VictoriaMetrics

application/json

401

Unauthorized

get

/sfp/api/metrics/query

GET /sfp/api/metrics/query?query=sum(rate(sfp_build_duration_seconds[5m])) HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "result": {}
}

Query metrics (instant query)

get

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

querystringRequired

MetricsQL / PromQL query expression

Example: sum(rate(sfp_build_duration_seconds[5m]))

timestringOptional

Evaluation timestamp (RFC3339 or unix seconds)

Example: 1734019200

timeoutstringOptional

Query timeout (duration), forwarded to VictoriaMetrics

Example: 10s

Responses

200

Query result from VictoriaMetrics

application/json

401

Unauthorized

get

/sfp/api/metrics/api/v1/query

GET /sfp/api/metrics/api/v1/query?query=sum(rate(sfp_build_duration_seconds[5m])) HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "result": {}
}

Query metrics over time range

get

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

querystringRequired

MetricsQL / PromQL query expression

Example: sum(rate(sfp_build_duration_seconds[5m]))

startstringRequired

Range start (RFC3339 or unix seconds)

Example: 1734015600

endstringRequired

Range end (RFC3339 or unix seconds)

Example: 1734019200

stepstringRequired

Step / resolution (duration, e.g. 30s, 1m)

Example: 30s

timeoutstringOptional

Query timeout (duration), forwarded to VictoriaMetrics

Example: 10s

Responses

200

Range query result with time-series data

application/json

401

Unauthorized

get

/sfp/api/metrics/query_range

GET /sfp/api/metrics/query_range?query=sum(rate(sfp_build_duration_seconds[5m]))&start=1734015600&end=1734019200&step=30s HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "result": {}
}

Query metrics over time range

get

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

querystringRequired

MetricsQL / PromQL query expression

Example: sum(rate(sfp_build_duration_seconds[5m]))

startstringRequired

Range start (RFC3339 or unix seconds)

Example: 1734015600

endstringRequired

Range end (RFC3339 or unix seconds)

Example: 1734019200

stepstringRequired

Step / resolution (duration, e.g. 30s, 1m)

Example: 30s

timeoutstringOptional

Query timeout (duration), forwarded to VictoriaMetrics

Example: 10s

Responses

200

Range query result with time-series data

application/json

401

Unauthorized

get

/sfp/api/metrics/api/v1/query_range

GET /sfp/api/metrics/api/v1/query_range?query=sum(rate(sfp_build_duration_seconds[5m]))&start=1734015600&end=1734019200&step=30s HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "result": {}
}

List distinct label values

get

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

namestringRequired

Query parameters

startstringOptional

Optional start time (RFC3339 or unix seconds)

Example: 1734015600

endstringOptional

Optional end time (RFC3339 or unix seconds)

Example: 1734019200

matchstring[]Optional

Optional match[] selectors (repeatable)

Responses

200

List of distinct label values

application/json

401

Unauthorized

get

/sfp/api/metrics/label/{name}/values

GET /sfp/api/metrics/label/{name}/values HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "result": {}
}

List distinct label values

get

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

namestringRequired

Query parameters

startstringOptional

Optional start time (RFC3339 or unix seconds)

Example: 1734015600

endstringOptional

Optional end time (RFC3339 or unix seconds)

Example: 1734019200

matchstring[]Optional

Optional match[] selectors (repeatable)

Responses

200

List of distinct label values

application/json

401

Unauthorized

get

/sfp/api/metrics/api/v1/label/{name}/values

GET /sfp/api/metrics/api/v1/label/{name}/values HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "result": {}
}

Good afternoon

Ingest CLI metrics events

Query metrics (instant query)

Query metrics (instant query)

Query metrics over time range

Query metrics over time range

List distinct label values

List distinct label values