Skip to main content
Ready-to-run examples demonstrating OISP Sensor in real-world scenarios.

​
What are Cookbooks?

Cookbooks are complete, runnable examples that show:
  • How to integrate OISP Sensor with specific frameworks/tools
  • Expected event output
  • Common patterns and configurations
  • Best practices
Each cookbook includes:
  • ✅ Complete source code
  • ✅ Docker Compose setup
  • ✅ Step-by-step instructions
  • ✅ Expected events with validation
  • ✅ CI-tested and working

​
Repository

All cookbooks live in: github.com/oximyhq/oisp-cookbook 
git clone https://github.com/oximyhq/oisp-cookbook.git
cd oisp-cookbook

​
Quick Start

# Run any cookbook
cd oisp-cookbook/<category>/<example>
docker-compose up

# View captured events
cat output/events.jsonl | jq

​
Categories

​
Python Examples

CookbookDescriptionUse Case
OpenAI SimpleBasic chat completionGetting started
LiteLLMMulti-provider abstractionProvider flexibility
LangChain AgentAgent with tool callsAgent workflows
FastAPI ServiceAPI service with AIProduction APIs

​
Node.js Examples

CookbookDescriptionUse Case
OpenAI SimpleTypeScript chat appNode.js integration

​
Self-Hosted

CookbookDescriptionUse Case
n8nn8n workflow automationNo-code AI workflows

​
Multi-Process

CookbookDescriptionUse Case
Python CeleryDistributed workersBackground job processing

​
Kubernetes

CookbookDescriptionUse Case
DaemonSetCluster-wide monitoringK8s deployments

​
Edge Cases

CookbookDescriptionUse Case
NVM Node.jsStatic OpenSSL handlingNVM environments
pyenv PythonStatic OpenSSL handlingpyenv environments

​
Anatomy of a Cookbook

Each cookbook follows this structure: 
oisp-cookbook/<category>/<example>/
├── README.md              # Step-by-step instructions
├── docker-compose.yml     # Run everything with one command
├── app.py / index.ts      # Application code
├── requirements.txt       # Dependencies
├── Dockerfile             # App container (if needed)
├── expected-events.json   # Event validation rules
├── test.sh                # CI test script
└── Makefile               # Common tasks

​
Running a Cookbook

cd oisp-cookbook/python/01-openai-simple

# Start OISP Sensor + run app
docker-compose up

# Events are captured to output/events.jsonl

​
Without Docker

cd oisp-cookbook/python/01-openai-simple

# Install dependencies
pip install -r requirements.txt

# Start sensor in one terminal
sudo oisp-sensor record --output output/events.jsonl

# Run app in another terminal
python app.py

# View events
cat output/events.jsonl | jq

​
Validating Events

Each cookbook includes expected event validation: 
# Run validation
./validate.sh

# Or manually
python shared/scripts/validate.py \
  --events output/events.jsonl \
  --expected expected-events.json
Example expected-events.json: 
{
  "event_types": [
    "ai.request",
    "ai.response"
  ],
  "providers": ["OpenAI"],
  "models": ["gpt-4o-mini"],
  "min_events": 2
}

​
CI Testing

All cookbooks are tested in CI:
  • Nightly builds - Run all cookbooks every night
  • On sensor release - Validate compatibility with new versions
  • Pull requests - Test cookbook changes
See CI workflows

​
Contributing

Want to add a cookbook?
  1. Fork oisp-cookbook
  2. Create your cookbook following the structure
  3. Add expected-events.json
  4. Add test.sh for CI
  5. Submit a pull request
See CONTRIBUTING.md

​
Common Patterns

​
Pattern 1: Development Monitoring

# docker-compose.yml
version: '3.8'
services:
  app:
    build: .
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}

  sensor:
    image: ghcr.io/oximyhq/sensor:latest
    privileged: true
    network_mode: host
    pid: host
    volumes:
      - /sys:/sys:ro
      - /usr:/usr:ro
      - /lib:/lib:ro
      - ./output:/var/log/oisp
    command: record --output /var/log/oisp/events.jsonl

​
Pattern 2: Production API

See FastAPI Service for production patterns:
  • Health checks
  • Structured logging
  • Error handling
  • Metrics export

​
Pattern 3: Agent Workflows

See LangChain Agent for:
  • Tool call tracing
  • Multi-turn conversations
  • Agentic patterns

​
Next Steps