CLIPlanned

CLI Advanced Usage

Advanced patterns and workflows for using OptixLog CLI in production

CLI Advanced Usage

Important: This documentation describes the intended behavior of the CLI. However, the CLI is currently not functional and is under active development. Please use the SDK directly for now.

Advanced patterns and workflows for using OptixLog CLI in production.

Batch Processing

Instrument Multiple Files

# Instrument all Python files
for file in *.py; do
    optixlog add-logging "$file" --smart
done

# Or with find
find . -name "*.py" -exec optixlog add-logging {} --smart \;

Process Directory Recursively

# Instrument all Python files recursively
find . -type f -name "*.py" | while read file; do
    optixlog add-logging "$file" --smart
done

Skip Already Instrumented Files

for file in *.py; do
    if ! grep -q "import optixlog" "$file"; then
        optixlog add-logging "$file" --smart
    else
        echo "Skipping $file (already instrumented)"
    fi
done

CI/CD Integration

GitHub Actions

name: Run Experiments

on:
  push:
    branches: [ main ]

jobs:
  experiments:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install OptixLog CLI
        run: npm install -g optixlog-cli
      
      - name: Install OptixLog SDK
        run: pip install optixlog
      
      - name: Initialize OptixLog
        run: |
          optixlog init --project "CI_Runs" --api-key ${{ secrets.OPTIX_API_KEY }}
      
      - name: Instrument code
        run: |
          optixlog add-logging test_script.py --smart
      
      - name: Run experiments
        run: |
          python test_script.py
      
      - name: List runs
        run: |
          optixlog runs --limit 5

GitLab CI

stages:
  - test
  - log

run_experiments:
  stage: test
  image: python:3.9
  before_script:
    - apt-get update && apt-get install -y nodejs npm
    - npm install -g optixlog-cli
    - pip install optixlog
    - optixlog init --project "CI_Runs" --api-key $OPTIX_API_KEY
  script:
    - optixlog add-logging test_script.py --smart
    - python test_script.py
    - optixlog runs --limit 5

Configuration Management

Team Collaboration

Setup (Team Lead):

# Create shared config (without API key)
optixlog init --project "TeamProject" --local
# Remove API key from .optixlog.json before committing
git add .optixlog.json
git commit -m "Add OptixLog config"

Team Members:

# Clone repo
git clone repo
cd repo

# Set their own API key
optixlog config set api_key "proj_their_key"

# Use shared config
optixlog add-logging script.py

Environment-Specific Configs

# Development
optixlog init --project "Dev" --api-url "http://localhost:8000" --local

# Staging
optixlog init --project "Staging" --api-url "https://staging.optixlog.com" --local

# Production
optixlog init --project "Production" --api-url "https://optixlog.com" --local

Custom Scripts

Instrumentation Script

#!/bin/bash
# instrument.sh

PROJECT=${1:-"MyProject"}
API_KEY=${2:-$OPTIX_API_KEY}

# Initialize if needed
if [ ! -f ".optixlog.json" ]; then
    optixlog init --project "$PROJECT" --api-key "$API_KEY" --local
fi

# Instrument all Python files
for file in *.py; do
    if [ -f "$file" ]; then
        echo "Instrumenting $file..."
        optixlog add-logging "$file" --smart --no-backup
    fi
done

echo "✓ Instrumentation complete"

Run and Log Script

#!/bin/bash
# run_and_log.sh

SCRIPT=$1
PROJECT=${2:-"MyProject"}

# Instrument
optixlog add-logging "$SCRIPT" --smart

# Run
python "$SCRIPT"

# Show runs
optixlog runs --project "$PROJECT" --limit 1

Pre-commit Hooks

Git Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

# Check if Python files changed
if git diff --cached --name-only | grep -q '\.py$'; then
    echo "Checking OptixLog instrumentation..."
    
    # Check if files have OptixLog imports
    for file in $(git diff --cached --name-only | grep '\.py$'); do
        if ! grep -q "import optixlog" "$file"; then
            echo "⚠ Warning: $file doesn't have OptixLog instrumentation"
            echo "Run: optixlog add-logging $file"
        fi
    done
fi

Integration with Build Systems

Makefile

.PHONY: instrument run log

instrument:
	@echo "Instrumenting Python files..."
	@for file in *.py; do \
		optixlog add-logging $$file --smart; \
	done

run: instrument
	@echo "Running experiments..."
	@python main.py

log:
	@optixlog runs --limit 10

Justfile

# justfile

instrument:
    #!/usr/bin/env bash
    for file in *.py; do
        optixlog add-logging "$file" --smart
    done

run: instrument
    python main.py

list-runs:
    optixlog runs --limit 10

Advanced Patterns

Conditional Instrumentation

# Only instrument if not already instrumented
for file in *.py; do
    if ! grep -q "import optixlog" "$file"; then
        optixlog add-logging "$file" --smart
    fi
done

Backup Management

# Instrument with backup
optixlog add-logging script.py

# Restore from backup if needed
cp script_backup.py script.py

# Or keep backups organized
mkdir -p backups
mv *_backup.py backups/

Selective Instrumentation

# Only instrument files matching pattern
for file in experiment_*.py; do
    optixlog add-logging "$file" --smart
done

# Skip test files
for file in *.py; do
    if [[ ! "$file" =~ test_ ]]; then
        optixlog add-logging "$file" --smart
    fi
done

Monitoring and Logging

Track Instrumentation

# Log which files were instrumented
LOG_FILE="instrumentation.log"

for file in *.py; do
    echo "$(date): Instrumenting $file" >> "$LOG_FILE"
    optixlog add-logging "$file" --smart
    echo "$(date): ✓ Completed $file" >> "$LOG_FILE"
done

Error Handling

# Instrument with error handling
for file in *.py; do
    if optixlog add-logging "$file" --smart; then
        echo "✓ $file"
    else
        echo "✗ $file failed"
        # Restore backup if exists
        if [ -f "${file}_backup.py" ]; then
            cp "${file}_backup.py" "$file"
        fi
    fi
done

Best Practices

  1. Use smart mode - Better code generation
  2. Keep backups - Restore if needed
  3. Version control configs - Share project settings
  4. Don't commit API keys - Use environment variables
  5. Batch process - Instrument multiple files efficiently
  6. Check before committing - Ensure instrumentation worked
  7. Use consistent naming - Easy to find runs
  8. Monitor runs - Check optixlog runs regularly

Next Steps

On this page