# azure-functions-doctor

> Pre-deploy diagnostic CLI for Azure Functions Python v2 projects — catch configuration issues, missing dependencies, and environment problems before deployment.

## Package Info

- PyPI: `pip install azure-functions-doctor`
- Version: 0.16.2
- Python: >=3.10, <3.15
- License: MIT
- Docs: https://yeongseon.github.io/azure-functions-doctor/
- Repository: https://github.com/yeongseon/azure-functions-doctor

## What It Does

Runs 14+ diagnostic checks on Azure Functions Python v2 projects to detect:
- **Missing dependencies** — azure-functions not in requirements.txt, discovered only at cold start
- **Invalid configuration** — host.json misconfigured, extensionBundle missing or outdated
- **Runtime incompatibilities** — Python version mismatch with Azure Functions runtime
- **Silent failures** — no virtual environment, Core Tools not installed, Application Insights key missing

Outputs to table, JSON, SARIF, or JUnit formats. Integrates with CI/CD pipelines as a deployment gate.

## CLI Commands

Main entry points (all aliases):
- `azure-functions doctor` — Run all diagnostics
- `azure-functions-doctor doctor` — Same as above
- `fdoctor doctor` — Short alias

### Key Options

- `--path <PATH>` — Path to the Azure Functions app (default: current directory)
- `--format <FORMAT>` — Output format: table (default), json, sarif, junit
- `--output <PATH>` — Save output to file
- `--profile <PROFILE>` — Rule profile: minimal (required only) or full (default)
- `--rules <PATH>` — Custom rules file (JSON)
- `--summary-json <PATH>` — Write JSON summary (passed/warned/failed counts)
- `--verbose` — Show detailed hints for failed checks
- `--debug` — Enable debug logging to stderr

## Quick Start

```bash
# Run diagnostics in current directory
azure-functions-doctor

# Run on specific project
azure-functions-doctor --path ./my-app

# Show verbose hints for failures
azure-functions-doctor --verbose

# Output JSON for CI integration
azure-functions-doctor --format json --output diagnostics.json

# Use minimal profile (required checks only)
azure-functions-doctor --profile minimal

# Custom rules
azure-functions-doctor --rules ./custom-rules.json

# SARIF output for GitHub Security tab
azure-functions-doctor --format sarif --output sarif.json

# JUnit output for CI systems
azure-functions-doctor --format junit --output test-results.xml
```

## Diagnostic Rules

**14+ built-in checks** covering:
- **Programming Model** — Confirms v2 decorator usage (@app.route, @bp.trigger)
- **Python Environment** — Python version, virtual environment, executable path
- **Dependencies** — requirements.txt, azure-functions package, no forbidden packages
- **Project Structure** — host.json, function files, proper layout
- **Host Configuration** — extensionBundle, functionTimeout, extensionBundleVersion
- **Durable Functions** — durableFunctionsMonitor, dfmEndpoint setup
- **Application Insights** — APPINSIGHTS_INSTRUMENTATION_KEY, logging.json config
- **Triggers** — Proper HTTP/Timer/Storage trigger usage and configuration
- **Core Tools** — Local Azure Functions Core Tools availability

Rules support two profiles:
- **minimal** — Required checks only
- **full** — All checks including recommended best practices

## Documentation

- [Getting Started](https://yeongseon.github.io/azure-functions-doctor/getting-started/)
- [API Reference](https://yeongseon.github.io/azure-functions-doctor/api/)
- [Rules Reference](https://yeongseon.github.io/azure-functions-doctor/rules/)
- [CI Integration](https://yeongseon.github.io/azure-functions-doctor/examples/ci_integration/)
- [Custom Rules](https://yeongseon.github.io/azure-functions-doctor/custom-rules/)

## Ecosystem

Part of the Azure Functions Python DX Toolkit:
- **azure-functions-validation** — Request/response validation
- **azure-functions-openapi** — OpenAPI spec and Swagger UI
- **azure-functions-langgraph** — LangGraph deployment adapter
- **azure-functions-logging** — Structured logging and observability
- **azure-functions-scaffold** — Project scaffolding
- **azure-functions-python-cookbook** — Recipes and examples

## Exit Codes

- `0` — All required checks passed
- `1` — At least one required check failed
