Goals & Metrics

Goals and metrics provide a framework for defining success criteria and measuring service performance in PrioStack. While the full monitoring infrastructure is planned for future releases, the goals framework establishes the foundation for observable and accountable services.

Understanding Goals

Goals represent the success criteria for your services. They define measurable objectives that indicate whether your service is performing as expected. Goals make your service requirements explicit and accountable.

Why Define Goals?

• Clarity: Goals make service expectations explicit
• Accountability: Goals provide measurable success criteria
• Monitoring Foundation: Goals establish what to monitor
• Continuous Improvement: Goals guide optimization efforts

Goal Configuration

Goals are defined in service YAML files under the goals section. Each goal specifies a metric, target value, and description.

Basic Goal Structure

goals:
  - name: apiResponseTime
    metric: latency
    target: "< 200ms"
    description: API responses should be under 200ms for good user experience

Goal Fields

Available Metrics

PrioStack supports several standard metrics that cover common service performance aspects. These metrics provide comprehensive coverage of service health and performance.

Performance Metrics

latency

Measures response time for operations. Critical for user experience and identifying performance bottlenecks.

- name: apiResponseTime
  metric: latency
  target: "< 500ms"
  description: API responses should be under 500ms

throughput

Measures the rate of successful operations per unit time. Important for capacity planning and scaling decisions.

- name: requestThroughput
  metric: throughput
  target: "> 1000 req/min"
  description: Service should handle at least 1000 requests per minute

Reliability Metrics

errorRate

Measures the percentage of failed operations. Critical for service reliability and identifying problematic areas.

- name: apiErrorRate
  metric: errorRate
  target: "< 0.1%"
  description: Error rate should be below 0.1%

availability

Measures the percentage of time the service is operational. Essential for SLA compliance and user trust.

- name: serviceAvailability
  metric: availability
  target: "> 99.9%"
  description: Service should be available 99.9% of the time

Resource Metrics

cpuUsage

Measures CPU utilization. Helps identify compute-intensive operations and scaling needs.

- name: cpuUtilization
  metric: cpuUsage
  target: "< 80%"
  description: CPU usage should stay below 80%

memoryUsage

Measures memory utilization. Important for preventing memory leaks and ensuring stable operation.

- name: memoryUtilization
  metric: memoryUsage
  target: "< 85%"
  description: Memory usage should stay below 85%

Business Metrics

custom

Allows defining custom business-specific metrics. Useful for tracking domain-specific KPIs and business outcomes.

- name: conversionRate
  metric: custom
  target: "> 3.5%"
  description: Shopping cart conversion rate should exceed 3.5%

Target Expressions

Target values use simple comparison expressions to define acceptable ranges. These expressions will be evaluated against actual metric values.

Comparison Operators

Range Expressions

For more complex requirements, you can use range expressions:

# Between two values
target: "100ms..500ms"

# Outside a range
target: "< 100ms || > 2000ms"

Goal Categories

Goals can be categorized to help organize and prioritize different aspects of service performance and business objectives.

Technical Goals

Focus on system performance and reliability:

• Response time and latency
• Error rates and availability
• Resource utilization
• Throughput and capacity

Business Goals

Focus on business outcomes and user experience:

• User satisfaction metrics
• Conversion rates
• Business process efficiency
• Customer retention indicators

Operational Goals

Focus on operational excellence:

• Deployment frequency
• Incident response time
• Mean time between failures
• Mean time to recovery

Resource Contracts

Goals can include resource contracts that declare the service's resource requirements and quality-of-service expectations. Resource contracts separate business logic from resource economics.

Contract Structure

Resource contracts are optional fields added to goal definitions:

goals:
  - name: apiResponseTime
    metric: latency
    target: "< 200ms"
    resourceContract:
      priority: high
      computeUnits: 100
      maxWaitTime: "5s"
      futuresEnabled: true
      fallbackBehavior: retry
      costCeiling: 10

Contract Fields

Priority Levels

Fallback Behaviors

When resource contracts cannot be fulfilled:

• queue: Wait in queue (default)
• retry: Retry with backoff
• degrade: Execute with reduced quality
• fail: Return error immediately

Goal Validation

While full runtime validation is planned for future releases, you can currently validate goal syntax and structure during bundle deployment.

Syntax Validation

PrioStack validates that:

• Goal names are unique within the service
• Metric names are recognized
• Target expressions are syntactically valid
• Required fields are present

Future Runtime Validation

Planned features include:

• Continuous monitoring against goals
• Automated alerts when goals are violated
• Historical trend analysis
• Goal-based autoscaling triggers

Example Service with Goals

Here's a complete example of a service with comprehensive goals covering different aspects of performance and reliability.

name: user-service
description: User management and authentication service
version: 1.0.0

api:
  basePath: "/api/v1/users"
  endpoints:
    - name: getUser
      method: GET
      path: "/:id"
      to: wasm:users:getUser
    - name: createUser
      method: POST
      path: "/"
      to: wasm:users:createUser

goals:
  # Performance goals
  - name: apiLatency
    metric: latency
    target: "< 300ms"
    description: API responses should be under 300ms for good UX

  - name: throughput
    metric: throughput
    target: "> 500 req/min"
    description: Handle at least 500 requests per minute

  # Reliability goals
  - name: errorRate
    metric: errorRate
    target: "< 0.5%"
    description: Keep error rate below 0.5%

  - name: availability
    metric: availability
    target: "> 99.5%"
    description: Service should be available 99.5% of the time

  # Resource goals
  - name: cpuUsage
    metric: cpuUsage
    target: "< 75%"
    description: CPU utilization should stay under 75%

  - name: memoryUsage
    metric: memoryUsage
    target: "< 80%"
    description: Memory usage should stay under 80%

Best Practices

Goal Setting

• Start Simple: Begin with 3-5 key goals per service
• Be Specific: Use concrete, measurable targets
• Be Realistic: Set achievable goals based on your requirements
• Focus on Impact: Prioritize goals that matter to users and business

Goal Categories

• Balance: Include goals for performance, reliability, and resources
• Hierarchy: Have primary goals and secondary goals
• Evolution: Review and adjust goals as your service matures

Measurement

• Consistency: Use consistent measurement periods
• Context: Consider seasonal variations and special circumstances
• Trends: Look at trends over time, not just snapshots