# Autolog Demo - Zero-Code ML Instrumentation

Demonstrates automatic instrumentation for scikit-learn models with complete Registry API integration.

## What is Autolog?

The `autolog()` function automatically instruments popular ML frameworks (scikit-learn, XGBoost, LightGBM) to emit OpenTelemetry metrics and traces without requiring manual code changes.

### Before Autolog (Manual Instrumentation)

```python
# Every prediction needs manual wrapping
@client.predict()
def make_prediction(features):
    return model.predict(features)
```

### After Autolog (Zero-Code Instrumentation)

```python
from mca_sdk import MCAClient, autolog

client = MCAClient(...)
autolog()  # One line!

# Now sklearn/xgboost/lightgbm predictions are automatically instrumented
predictions = model.predict(features)  # Automatically tracked!
```

## Features Demonstrated

- ✅ GCP Authentication (Application Default Credentials)
- ✅ OTel Collector connectivity verification
- ✅ Registry API integration (model config fetch)
- ✅ Zero-code instrumentation with `autolog()`
- ✅ Automatic prediction tracking (no decorators needed)
- ✅ Telemetry verification in GCP services

## Prerequisites

### 1. Install Dependencies

```bash
pip install mca-sdk[gcp]>=0.6.1 scikit-learn>=1.0
```

### 2. Configure GCP Authentication

```bash
gcloud auth application-default login
```

### 3. VPN Connection (if outside GKE cluster)

The GCP dev OTel Collector (`10.164.76.55`) is only accessible from inside the GKE cluster or via VPN.

## Usage

### Run Against GCP Dev Collector (Default)

```bash
python sklearn_autolog_example.py
```

**Note:** Requires VPN access if running outside the GKE cluster.

### Run Against Local Collector (Optional)

```bash
docker-compose up -d otel-collector
export MCA_COLLECTOR_ENDPOINT=http://localhost:4318
python sklearn_autolog_example.py
```

## Using GCP Development Infrastructure

To test against the real GCP dev environment instead of a local collector:

```bash
# Use Docker Compose override
docker-compose -f ../../docker-compose.yml -f ../../docker-compose.gcp-dev.yml up autolog-demo

# Or set environment variables for local testing
export MCA_COLLECTOR_ENDPOINT=http://10.164.76.55:4318
export MCA_ALLOW_INSECURE_COLLECTOR=true
python sklearn_autolog_example.py
```

See [GCP Dev Environment Guide](../../../docs/gcp-dev-environment.md) for complete setup instructions and troubleshooting.

### Verification

After running against GCP dev, verify telemetry in GCP Console:

```bash
# View logs
gcloud logging read "logName=projects/bhsf-ai-team-projects/logs/emms-model-telemetry" --limit=10

# View traces
gcloud trace list --project=bhsf-ai-team-projects --limit=10
```

Or use the GCP Console:
- **Logs**: [https://console.cloud.google.com/logs/query?project=bhsf-ai-team-projects](https://console.cloud.google.com/logs/query?project=bhsf-ai-team-projects)
- **Traces**: [https://console.cloud.google.com/traces/list?project=bhsf-ai-team-projects](https://console.cloud.google.com/traces/list?project=bhsf-ai-team-projects)

### Troubleshooting GCP Connectivity

**Cannot connect to 10.164.76.55:**
- Verify VPC connectivity or VPN access
- Test with: `curl http://10.164.76.55:4318/`

**Telemetry not appearing in GCP Console:**
- Verify collector endpoint is set correctly
- Check collector health: `curl http://10.164.76.55:13133/health/status`
- Wait 15 seconds for batch processing

## Expected Output

The script will:
1. Verify GCP authentication and collector connectivity
2. Fetch model configuration from registry
3. Initialize SDK with registry config
4. Enable autolog for automatic instrumentation
5. Train a RandomForest model
6. Make predictions (automatically tracked)
7. Flush telemetry to collector
8. Print verification URLs for GCP Console

## Telemetry Generated

### Metrics
- `model.prediction.count`: Counter for prediction calls
- `model.prediction.latency`: Histogram of prediction latencies
- Attributes: `framework=sklearn`, `model_class=RandomForestClassifier`

### Traces
- Span name: `sklearn.RandomForestClassifier.predict`
- Span attributes: framework, model_class, method

## Configuration Options

```python
# Enable autolog for specific frameworks only
autolog(frameworks=["sklearn"])

# Exclude specific frameworks
autolog(exclude=["lightgbm"])

# Capture input/output data with size limits (use with caution - Sensitive Data risk)
autolog(capture_input=True, capture_output=True, max_payload_size=5000)
```

## Robustness Features

### Payload Size Limiting
Large batch predictions can cause memory bloat. Autolog automatically truncates captured data to `max_payload_size` bytes (default: 10,000 bytes).

### Graceful Client Handling
If predictions are made before MCAClient is initialized, autolog logs a warning once and predictions execute without telemetry (no crash).

### Error Recording
When predictions fail, autolog:
1. Records the exception in the OpenTelemetry span
2. Marks the span status as ERROR
3. Records failure metrics with error details
4. Re-raises the exception to preserve application behavior

## Important Notes

1. **MCAClient must be initialized BEFORE calling autolog()**
   ```python
   client = MCAClient(...)  # Initialize first
   autolog()                # Then enable autolog
   ```

2. **Framework Detection**: autolog() only patches frameworks that are already imported
   - Import the framework before calling autolog()

3. **Sensitive Data Considerations**: Be cautious when using `capture_input=True` or `capture_output=True`
   - Input/output data may contain Protected Health Information (Sensitive Data)
   - Sanitize Sensitive Data before enabling capture

## Supported Frameworks

| Framework | Methods Instrumented | Status |
|-----------|---------------------|--------|
| **scikit-learn** | `predict()`, `predict_proba()`, `fit()` | ✅ Supported |
| **XGBoost** | `Booster.predict()`, `XGBClassifier.predict()`, `XGBRegressor.predict()` | ✅ Supported |
| **LightGBM** | `Booster.predict()`, `LGBMClassifier.predict()`, `LGBMRegressor.predict()` | ✅ Supported |

## See Also

- [Internal Model Example](../internal-model/) - Manual instrumentation approach
- [MCA SDK Documentation](../../README.md) - Full SDK documentation
