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

​Recipe Serve Advanced CLI

​Quick Reference

​Command Options

​Rate Limiting

​Test Rate Limiting

​Request Size Limits

​Test Size Limit

​Metrics Endpoint

​Sample Output

​Prometheus Integration

​Admin Endpoints

​Response

​Workers

​Notes

​OpenTelemetry Tracing

​Install Dependencies

​OpenAPI Specification

​Configuration File

​Production Examples

​Basic Production

​Full Production

​Docker

​Kubernetes

​Environment Variables

​Troubleshooting

​Rate Limit Not Working

​Metrics Endpoint 404

​Admin Endpoint 401

​Workers with Reload

​Next Steps

Recipe Serve Advanced CLI

Quick Reference

Command Options

Rate Limiting

Test Rate Limiting

Request Size Limits

Test Size Limit

Metrics Endpoint

Sample Output

Prometheus Integration

Admin Endpoints

Response

Workers

Notes

OpenTelemetry Tracing

Install Dependencies

OpenAPI Specification

Configuration File

Production Examples

Basic Production

Full Production

Docker

Kubernetes

Environment Variables

Troubleshooting

Rate Limit Not Working

Metrics Endpoint 404

Admin Endpoint 401

Workers with Reload

Next Steps