Skip to content

Rules

Azure Functions Doctor executes declarative rules from a JSON ruleset.

Built-in rules are defined in:

src/azure_functions_doctor/assets/rules/v2.json

You can replace the built-in set with --rules <file>.

Rule execution model

Each rule contains:

  • identity (id, label)
  • grouping (category, section)
  • behavior (type, condition)
  • severity intent (required)
  • ordering (check_order)
  • remediation (hint, optional hint_url)

Rules are validated by:

src/azure_functions_doctor/schemas/rules.schema.json

Required vs optional

  • required: true + raw handler fail -> item status fail
  • required: false + raw handler fail -> item status warn

Only required failures produce non-zero process exit code.

Built-in rule types

  • compare_version
  • env_var_exists
  • path_exists
  • file_exists
  • package_installed
  • package_declared
  • source_code_contains
  • conditional_exists
  • callable_detection
  • executable_exists
  • any_of_exists
  • file_glob_check
  • host_json_property

Rule-by-rule reference

1) check_programming_model_v2

  • What it checks: Source contains Azure Functions decorator usage (@app.) via AST detection.
  • Why it matters: Doctor targets Python v2 projects; this check protects model compatibility.
  • How to fix: Use func.FunctionApp() and decorator-based triggers.

Example failing detail:

Keyword '@app.' not found in source code (AST)

2) check_python_version

  • What it checks: Current interpreter version is >=3.10.
  • Why it matters: Package and diagnostics support baseline starts at Python 3.10.
  • How to fix: Use Python 3.10+ locally and in CI.

Example output:

Python 3.9.18 (>=3.10)

3) check_venv

  • What it checks: Environment variable VIRTUAL_ENV exists.
  • Why it matters: Virtual environments reduce dependency drift and environment pollution.
  • How to fix: Create and activate .venv before running diagnostics.

Example failing detail:

VIRTUAL_ENV is not set

4) check_python_executable

  • What it checks: sys.executable points to an existing path.
  • Why it matters: Broken interpreter paths indicate unstable runtime environment.
  • How to fix: Reinstall or reactivate Python environment.

Example detail:

/usr/bin/python3 exists

5) check_requirements_txt

  • What it checks: requirements.txt exists at project root.
  • Why it matters: Deployability and reproducibility depend on declared dependencies.
  • How to fix: Add requirements.txt and include runtime dependencies.

Example failing detail:

/workspace/app/requirements.txt not found

6) check_azure_functions_library

  • What it checks: azure-functions appears in requirements.txt.
  • Why it matters: Function app code depends on Azure Functions Python library.
  • How to fix: Add azure-functions to dependency declarations.

Example failing detail:

Package 'azure-functions' not declared in requirements.txt

7) check_host_json

  • What it checks: host.json exists at project root.
  • Why it matters: Azure Functions host configuration is required for valid app structure.
  • How to fix: Add a valid host.json (at minimum { "version": "2.0" }).

Example failing detail:

/workspace/app/host.json not found

8) check_local_settings

  • What it checks: local.settings.json exists.
  • Why it matters: Local development often needs this file for settings and connection values.
  • How to fix: Create local settings file for local runs (do not commit secrets).

Example warning detail:

/workspace/app/local.settings.json not found (optional)

9) check_func_cli

  • What it checks: func executable is available on PATH.
  • Why it matters: Core Tools enable local hosting and rich runtime tooling.
  • How to fix: Install Azure Functions Core Tools v4+.

Example warning detail:

func not found

10) check_func_core_tools_version

  • What it checks: Core Tools version is >=4.0.
  • Why it matters: Older versions can diverge from current host/runtime expectations.
  • How to fix: Upgrade Core Tools installation.

Example warning detail:

func 3.0.3904 (>=4.0)

11) check_durabletask_config

  • What it checks: If durable usage is detected in source, $.extensions.durableTask exists in host.json.
  • Why it matters: Durable Functions need matching host configuration.
  • How to fix: Add durableTask configuration when using durable features.

Example details:

No Durable Functions usage detected; check skipped

or

Required host.json property '$.extensions.durableTask' not found

12) check_app_insights

  • What it checks: At least one telemetry signal exists:
  • APPLICATIONINSIGHTS_CONNECTION_STRING
  • APPINSIGHTS_INSTRUMENTATIONKEY
  • host.json:instrumentationKey
  • Why it matters: Telemetry is critical for production diagnostics.
  • How to fix: Configure one supported telemetry source.

Example warning detail:

Targets not found

13) check_extension_bundle

  • What it checks: $.extensionBundle exists in host.json.
  • Why it matters: Extension bundles help ensure binding dependencies are available.
  • How to fix: Add extensionBundle section to host config.

Example warning detail:

host.json property '$.extensionBundle' not found

14) check_asgi_wsgi_exposure

  • What it checks: Source has ASGI/WSGI exposure patterns.
  • Why it matters: Useful signal for framework-host integration readiness.
  • How to fix: Ensure framework callable exposure follows expected patterns.

Example warning detail:

No ASGI/WSGI callable detected in project source

15) check_unused_files

  • What it checks: Presence of unwanted patterns (for example **/*.pyc, **/__pycache__, .venv, tests/).
  • Why it matters: Reduces deployment package clutter and risk.
  • How to fix: Clean or exclude unwanted files from deployment artifacts.

Example warning detail:

Found unwanted files: ['tests/', '.venv']

Rule authoring template

{
  "id": "check_example",
  "category": "structure",
  "section": "project_structure",
  "label": "host.json",
  "description": "Checks host.json exists.",
  "type": "file_exists",
  "required": true,
  "condition": {
    "target": "host.json"
  },
  "hint": "Add host.json to project root.",
  "check_order": 10
}

Guidance for custom rules

  • Keep IDs stable and descriptive
  • Use deterministic check_order values
  • Start policy experiments as optional rules
  • Promote to required only after false-positive review
  • Include clear hint text for faster remediation

Custom rules docs: Examples: Custom Rules

Safety and trust model

Rules may inspect local files, source code, environment variables, executable presence, and importable modules.

Warning

Only run trusted custom rules files, especially in shared CI environments.