Metrics

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.

Response Body

curl -X POST "https://example.com/sfp/api/metrics/ingest" \  -H "Content-Type: application/json" \  -d '{    "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,  "message": "Metrics accepted"}

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.

Query Parameters

Response Body

curl -X GET "https://example.com/sfp/api/metrics/query?query=sum%28rate%28sfp_build_duration_seconds%5B5m%5D%29%29"

{  "result": {}}

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.

Query Parameters

Response Body

curl -X GET "https://example.com/sfp/api/metrics/api/v1/query?query=sum%28rate%28sfp_build_duration_seconds%5B5m%5D%29%29"

{  "result": {}}

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.

Query Parameters

Response Body

curl -X GET "https://example.com/sfp/api/metrics/query_range?query=sum%28rate%28sfp_build_duration_seconds%5B5m%5D%29%29&start=1734015600&end=1734019200&step=30s"

{  "result": {}}

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.

Query Parameters

Response Body

curl -X GET "https://example.com/sfp/api/metrics/api/v1/query_range?query=sum%28rate%28sfp_build_duration_seconds%5B5m%5D%29%29&start=1734015600&end=1734019200&step=30s"

{  "result": {}}

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

Path Parameters

Query Parameters

Response Body

curl -X GET "https://example.com/sfp/api/metrics/label/string/values"

{  "result": {}}

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

Path Parameters

Query Parameters

Response Body

curl -X GET "https://example.com/sfp/api/metrics/api/v1/label/string/values"

{  "result": {}}

Aggregate the AI usage recorded by the opencode metrics lane for one repository.

Returns distinct AI sessions, prompt counts (completed + failed), token totals (input/output/reasoning/cache), model turns, total time spent, and provider-reported cost over the requested window (default 30 days).

Sourced from the per-prompt usage records the engine emits for every AI feature run (cascade merge assist, architecture analysis, version assist, AI reports, …).

Query Parameters

Response Body

curl -X GET "https://example.com/sfp/api/metrics/ai-usage?repositoryIdentifier=flxbl-io%2Fsf-core"

{  "repositoryIdentifier": "string",  "windowDays": 0,  "sessions": 0,  "prompts": 0,  "promptsFailed": 0,  "tokens": {    "input": 0,    "output": 0,    "reasoning": 0,    "cacheRead": 0,    "cacheWrite": 0  },  "turns": 0,  "durationMs": 0,  "cost": 0}