Azure Functions Host.json Configuration

The host.json file is used to configure global settings for your Azure Functions host. It allows you to control aspects like logging, HTTP settings, and distributed tracing.

Schema Overview

The host.json file follows a specific schema. Here's a common structure and an explanation of its key properties:

{
  "version": "2.0",
  "logging": {
    "applicationInsights": {
      "samplingSettings": {
        "isEnabled": true,
        "excludedTypes": "Request"
      }
    },
    "logLevel": {
      "default": "Information",
      "Host.Results": "Error",
      "Function.MyFunctionName": "Debug"
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[1.*, 2.0.0)"
  },
  "http": {
    "routePrefix": "api",
    "maxOutstandingRequests": 200,
    "maxConcurrentRequests": 100
  },
  "singleton": {
    "lockPeriod": "00:00:15",
    "graceTime": "00:00:10",
    "retryTimeout": "00:00:05"
  },
  "concurrency": {
    "dynamicConcurrencyEnabled": true
  },
  "functions": {
    "MyFunctionName": {
      "scriptFile": "run.py",
      "entryPoint": "main",
      "timeout": "00:05:00",
      "trigger": null,
      "disabled": false
    }
  },
  "customHandler": {
    "description": {
      "defaultExecutablePath": "handler.sh",
      "workingDirectory": "",
      "arguments": []
    }
  }
}

Key Configuration Properties

version

Specifies the version of the host.json schema. The recommended value is "2.0".

logging

Configures logging behavior. This section is crucial for monitoring your functions.

• applicationInsights: Settings for Application Insights integration.
  • samplingSettings: Controls adaptive sampling.
    • isEnabled (boolean): Enables or disables sampling. Defaults to true.
    • excludedTypes (string): Comma-separated list of telemetry types to exclude from sampling (e.g., "Request", "Dependency").
• logLevel: Sets the minimum log level for different categories.
  • default (string): The default log level for all categories (e.g., "Information", "Warning", "Error", "Debug").
  • Specific function or host categories can override the default (e.g., "Host.Results", "Function.MyFunctionName").

extensionBundle

Defines which extension bundles to use. Bundles provide pre-packaged bindings and extensions.

• id (string): The identifier for the bundle (e.g., "Microsoft.Azure.Functions.ExtensionBundle").
• version (string): The version range for the bundle (e.g., "[1.*, 2.0.0)").

http

Settings for the HTTP trigger.

• routePrefix (string): A prefix to prepend to all HTTP routes defined in your functions. For example, setting it to "api" would make your functions accessible at /api/FunctionName. Defaults to an empty string.
• maxOutstandingRequests (integer): The maximum number of concurrent HTTP requests allowed to be outstanding.
• maxConcurrentRequests (integer): The maximum number of concurrent HTTP requests processed by the Functions host.

singleton

Configuration for singleton execution, often used with durable functions or specific triggers that require exclusive processing.

• lockPeriod (timespan): The duration for which a singleton lock is held.
• graceTime (timespan): An additional period to allow a function to finish processing before a new instance takes over.
• retryTimeout (timespan): The time to wait before retrying to acquire a singleton lock.

concurrency

Settings related to function concurrency and scaling.

• dynamicConcurrencyEnabled (boolean): Enables or disables dynamic concurrency, allowing the Functions host to scale concurrency based on load. Defaults to true.

functions

Allows you to configure settings on a per-function basis. This overrides global settings for specific functions.

• <FunctionName> (object): An object where the key is the name of your function.
  • scriptFile (string): The relative path to the function's script file.
  • entryPoint (string): The name of the method or function to execute within the script file.
  • timeout (timespan): The maximum time a function execution can take before being timed out. Format: HH:MM:SS.
  • trigger: Specific trigger configurations (often handled by attributes in code, but can be defined here).
  • disabled (boolean): Set to true to disable the function globally.

customHandler

Used for custom handlers, where the execution logic is external to the Functions host.

• description (object): Provides details about the executable.
  • defaultExecutablePath (string): The path to the executable file.
  • workingDirectory (string): The working directory for the executable.
  • arguments (array): An array of arguments to pass to the executable.