Recipe Serve Advanced Features

Rate limiting, metrics, admin endpoints, workers, and OpenTelemetry

from praisonaiagents import Agent

agent = Agent(name="recipe-server", instructions="Serve advanced recipes as HTTP endpoints.")
agent.start("Serve the data-analysis recipe on port 8000.")

The user calls a hardened recipe HTTP endpoint; rate limits, metrics, and auth guard production traffic.

Harden a recipe HTTP server with rate limits, Prometheus metrics, admin reload, and distributed tracing.

import os
from praisonai.recipe.serve import serve

serve(
    host="0.0.0.0",
    port=8765,
    workers=2,
    config={
        "auth": "api-key",
        "api_key": os.environ["PRAISONAI_API_KEY"],
        "rate_limit": 100,
        "enable_metrics": True,
    },
)

How It Works

Quick Start

1. Simple Usage

   Enable rate limiting and metrics on an existing server:

   from praisonai.recipe.serve import serve
   
   serve(
       host="127.0.0.1",
       port=8765,
       config={
           "rate_limit": 100,
           "enable_metrics": True,
       },
   )
   

   Scrape metrics at GET /metrics (Prometheus format).

2. With Configuration

   Production setup with auth, admin reload, workers, and tracing:

   import os
   from praisonai.recipe.serve import serve
   
   serve(
       host="0.0.0.0",
       port=8765,
       workers=4,
       config={
           "auth": "api-key",
           "api_key": os.environ["PRAISONAI_API_KEY"],
           "rate_limit": 100,
           "max_request_size": 10 * 1024 * 1024,
           "enable_metrics": True,
           "enable_admin": True,
           "trace_exporter": "otlp",
           "otlp_endpoint": "http://localhost:4317",
           "service_name": "praisonai-recipe",
       },
   )
   

---

How It Works

Advanced features layer onto the base recipe server from Recipe Serve. Rate limiting uses a sliding window per client; metrics expose request counts and latency; admin endpoints hot-reload recipes without restart.

Feature	Endpoint / API	Purpose
Rate limiting	middleware	Cap requests per minute per client
Metrics	GET /metrics	Prometheus exposition
Admin reload	POST /admin/reload	Refresh recipe registry
Tracing	OpenTelemetry	Distributed request spans
Workers	serve(workers=N)	Multi-process scaling

---

Configuration Options

Key	Type	Default	Description
rate_limit	int	0 (disabled)	Requests per minute per client
rate_limit_exempt_paths	list	["/health", "/metrics"]	Paths exempt from rate limiting
max_request_size	int	10485760 (10MB)	Maximum request body size
enable_metrics	bool	false	Enable /metrics endpoint
enable_admin	bool	false	Enable /admin/* endpoints
trace_exporter	str	"none"	Tracing exporter (none, otlp, jaeger, zipkin)
otlp_endpoint	str	"http://localhost:4317"	OTLP collector endpoint
service_name	str	"praisonai-recipe"	Service name for tracing
workers	int	1	Worker processes (serve() argument)

---

Common Patterns

Programmatic rate limiter

from praisonai.recipe.serve import create_rate_limiter

limiter = create_rate_limiter(requests_per_minute=100)
allowed, retry_after = limiter.check("client-ip-or-key")

if not allowed:
    print(f"Rate limited. Retry after {retry_after} seconds")

Admin reload

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

Prometheus scrape config

scrape_configs:
  - job_name: praisonai-recipe
    static_configs:
      - targets: ["localhost:8765"]
    metrics_path: /metrics

OpenTelemetry dependencies

pip install opentelemetry-sdk opentelemetry-exporter-otlp

OpenTelemetry is lazily imported — if packages are missing, the server logs a warning and continues without tracing.

---

Best Practices

Always enable auth with admin endpoints

Set enable_admin=True only alongside auth: api-key and load the key from PRAISONAI_API_KEY. Admin reload can change live behaviour — protect it.

Use workers for CPU-bound recipe loads

Set workers to roughly 2 × CPU cores + 1. Workers above 1 disable hot reload automatically.

Exempt health and metrics from rate limits

Keep /health and /metrics in rate_limit_exempt_paths so orchestrators and Prometheus can poll without consuming quota.

Use Redis for distributed rate limiting

The built-in limiter is in-memory per worker. For multi-node deployments, place a shared rate limiter in front of the service (API gateway or Redis-backed middleware).

---

Related

Recipe Serve

Programmatic server configuration and deployment

Endpoints Code

Client-side code for calling recipe endpoints