Recipe Serve Advanced CLI

CLI options for rate limiting, metrics, admin, workers, and tracing

Recipe Serve Advanced CLI

Advanced CLI options for the recipe server including rate limiting, metrics, admin endpoints, workers, and OpenTelemetry tracing.

Quick Reference

praisonai serve recipe \
  --host 0.0.0.0 \
  --port 8765 \
  --auth api-key \
  --workers 4 \
  --rate_limit 100 \
  --max_request_size 10485760 \
  --enable_metrics \
  --enable_admin \
  --trace_exporter otlp

Command Options

Option	Description	Default
--workers <num>	Number of worker processes	1
--rate_limit <num>	Requests per minute per client	disabled
--max_request_size <bytes>	Maximum request body size	10485760 (10MB)
--enable_metrics	Enable /metrics endpoint	false
--enable_admin	Enable /admin/* endpoints	false
--trace_exporter <type>	Tracing: none, otlp, jaeger, zipkin	none

Rate Limiting

Protect your server from abuse.

# Enable rate limiting (100 requests/minute per client)
praisonai serve recipe --rate_limit 100

# Stricter limit for public API
praisonai serve recipe --rate_limit 30 --auth api-key

When combined with --workers N, the configured --rate_limit is divided across workers (rate_limit // workers, floor 1) so the aggregate stays close to the value you set. A startup warning prints exactly what value each worker enforces. For exact cross-process limiting, front the service with a shared-store limiter (API gateway or Redis).

Test Rate Limiting

# Start server with low limit for testing
praisonai serve recipe --rate_limit 5

# In another terminal, make rapid requests
for i in {1..10}; do
  curl -s http://localhost:8765/v1/recipes | head -c 50
  echo " - Request $i"
done

Expected output after 5 requests:

{"error":{"code":"rate_limited","message":"Too many requests"}}

Request Size Limits

Prevent oversized payloads.

# Set 5MB limit
praisonai serve recipe --max_request_size 5242880

# Set 1MB limit for strict environments
praisonai serve recipe --max_request_size 1048576

Test Size Limit

# Start server with small limit
praisonai serve recipe --max_request_size 100

# Send large request
curl -X POST http://localhost:8765/v1/recipes/run \
  -H "Content-Type: application/json" \
  -d '{"recipe": "test", "input": {"data": "'"$(head -c 200 /dev/urandom | base64)"'"}}'

Expected response:

{"error":{"code":"request_too_large","message":"Request body too large. Max: 100 bytes"}}

Metrics Endpoint

Expose Prometheus metrics.

# Enable metrics
praisonai serve recipe --enable_metrics

# Verify metrics endpoint
curl http://localhost:8765/metrics

Sample Output

# HELP praisonai_http_requests_total Total HTTP requests
# TYPE praisonai_http_requests_total counter
praisonai_http_requests_total{path="/health",method="GET",status="200"} 5

# HELP praisonai_http_request_duration_seconds HTTP request duration
# TYPE praisonai_http_request_duration_seconds histogram
praisonai_http_request_duration_seconds_sum{path="/health",method="GET"} 0.025
praisonai_http_request_duration_seconds_count{path="/health",method="GET"} 5

Prometheus Integration

# prometheus.yml
scrape_configs:
  - job_name: 'praisonai'
    static_configs:
      - targets: ['localhost:8765']
    metrics_path: '/metrics'
    scrape_interval: 15s

Admin Endpoints

Hot-reload recipes without restart.

# Enable admin endpoints (requires auth)
praisonai serve recipe --enable_admin --auth api-key

# Reload recipes
curl -X POST http://localhost:8765/admin/reload \
  -H "X-API-Key: $PRAISONAI_API_KEY"

Response

{
  "status": "reloaded",
  "timestamp": "2024-01-15T10:30:00Z"
}

Workers

Scale with multiple processes.

# Start with 4 workers
praisonai serve recipe --workers 4 --auth api-key

# Recommended: 2 * CPU cores + 1
praisonai serve recipe --workers $(( $(nproc) * 2 + 1 )) --auth api-key

As of PraisonAI PR #5231, --workers N > 1 actually spawns N uvicorn worker processes; previously the CLI accepted the flag but silently ran a single worker.

Notes

• Workers > 1 automatically disables --reload
• Each worker has independent rate limiter state; --rate_limit is split across workers (rate_limit // workers, floor 1) with a startup warning
• For distributed rate limiting, use external store (Redis)

OpenTelemetry Tracing

Distributed tracing support.

# OTLP exporter
praisonai serve recipe --trace_exporter otlp

# With custom endpoint
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317 \
  praisonai serve recipe --trace_exporter otlp

# Jaeger
praisonai serve recipe --trace_exporter jaeger

# Zipkin
praisonai serve recipe --trace_exporter zipkin

Install Dependencies

# For OTLP
pip install opentelemetry-sdk opentelemetry-exporter-otlp

# For Jaeger
pip install opentelemetry-sdk opentelemetry-exporter-jaeger

# For Zipkin
pip install opentelemetry-sdk opentelemetry-exporter-zipkin

OpenAPI Specification

Get the API specification.

# Get OpenAPI spec
curl http://localhost:8765/openapi.json

# Save to file
curl http://localhost:8765/openapi.json > openapi.json

# Pretty print
curl -s http://localhost:8765/openapi.json | python3 -m json.tool

Configuration File

All CLI options can be set in serve.yaml:

# serve.yaml
host: 0.0.0.0
port: 8765
auth: api-key
api_key: ${PRAISONAI_API_KEY}

# Advanced options
workers: 4
rate_limit: 100
max_request_size: 10485760
enable_metrics: true
enable_admin: true
trace_exporter: otlp
otlp_endpoint: http://otel-collector:4317
service_name: praisonai-recipe

Use with:

praisonai serve recipe --config serve.yaml

Production Examples

Basic Production

export PRAISONAI_API_KEY="your-secret-key"
praisonai serve recipe \
  --host 0.0.0.0 \
  --port 8765 \
  --auth api-key \
  --workers 4 \
  --preload

Full Production

export PRAISONAI_API_KEY="your-secret-key"
praisonai serve recipe \
  --host 0.0.0.0 \
  --port 8765 \
  --auth api-key \
  --workers 4 \
  --rate_limit 100 \
  --max_request_size 10485760 \
  --enable_metrics \
  --enable_admin \
  --trace_exporter otlp \
  --preload

Docker

FROM python:3.11-slim
RUN pip install praisonai[serve]
COPY serve.yaml /app/
WORKDIR /app
EXPOSE 8765
CMD ["praisonai", "recipe", "serve", "--config", "serve.yaml"]

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: recipe-server
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: server
        image: praisonai-recipe:latest
        args:
        - recipe
        - serve
        - --host=0.0.0.0
        - --port=8765
        - --auth=api-key
        - --workers=2
        - --enable_metrics
        ports:
        - containerPort: 8765
        env:
        - name: PRAISONAI_API_KEY
          valueFrom:
            secretKeyRef:
              name: api-secrets
              key: praisonai-key

Environment Variables

Variable	Description
PRAISONAI_API_KEY	API key for authentication
PRAISONAI_SERVE_HOST	Default host
PRAISONAI_SERVE_PORT	Default port
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP collector endpoint

Troubleshooting

Rate Limit Not Working

Check if path is exempt:

# /health and /metrics are exempt by default
curl http://localhost:8765/health  # Always works

Metrics Endpoint 404

Enable metrics:

praisonai serve recipe --enable_metrics

Admin Endpoint 401

Provide authentication:

curl -X POST http://localhost:8765/admin/reload \
  -H "X-API-Key: your-key"

Workers with Reload

Cannot use both:

# This will warn and disable reload
praisonai serve recipe --workers 4 --reload

Next Steps

• See Python Usage for programmatic configuration
• Review Recipe Serve Basics
• Explore Endpoints CLI