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.

Rate limiter internals

The middleware buckets requests by the strongest identity the auth layer has already validated — never by a raw client header — so rotating a header cannot defeat the limit.

RateLimiter exposes two entry points:

• check(client_id) — synchronous, thread-safe (backward-compatible). check_sync remains as an alias.
• check_async(client_id) — async, guarded by an asyncio.Lock. Used by the middleware hot path so overlapping requests can never both pass the length check before either appends.

Precedence: jwt:<sub> > apikey:<key> (only in api-key mode) > ip:<host> > "anonymous".

Configuration Options

Common Patterns

Programmatic rate limiter

from praisonai.recipe.serve import create_rate_limiter

limiter = create_rate_limiter(requests_per_minute=100)

# Backward-compatible sync API. Guarded by a threading.Lock.
allowed, retry_after = limiter.check("ip:127.0.0.1")
# `check_sync` is retained as an alias of `check`.
if not allowed:
    print(f"Rate limited. Retry after {retry_after} seconds")

import asyncio
from praisonai.recipe.serve import create_rate_limiter

limiter = create_rate_limiter(requests_per_minute=5)

async def burst():
    # 100 concurrent checks — exactly 5 succeed (async race closed).
    results = await asyncio.gather(
        *[limiter.check_async("burst") for _ in range(100)]
    )
    return sum(1 for allowed, _ in results if allowed)

print(asyncio.run(burst()))  # -> 5

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

Related