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

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

Notes

Workers > 1 automatically disables --reload
Each worker has independent rate limiter state
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

CLI

Documentation Index

​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