Python Installation

RegisterConfig controls how Hud instruments your Python service:

include_modules

List of module name patterns to explicitly include for instrumentation. Useful when you want to focus on specific internal packages. Accepts glob-like strings.
Type: List[str] · Default: [] (instrument all first-party code excluding third-party)

max_mapped_functions

Upper bound on the number of functions Hud will map and monitor. Helps keep overhead predictable in very large codebases.
Type: int · Default: 50000

min_pod_memory_mb

Minimum memory threshold in MB expected for the runtime. Hud may adjust behavior if available memory is below this value.
Type: int · Default: 250 MB

max_file_size_bytes

Maximum source file size that Hud will parse when mapping functions. Larger files are skipped to avoid heavy processing.
Type: int · Default: 2097152 bytes (2 MB)

init_timeout

Timeout in seconds for initialization tasks such as mapping and startup handshakes.
Type: int · Default: 30 seconds

verbose

Enables verbose logging from the SDK for debugging and development.
Type: bool · Default: false

Example:

from hud_sdk import RegisterConfig

config = RegisterConfig(
    include_modules=["my_company.*", "internal_pkg"],
    max_mapped_functions=50000,
    min_pod_memory_mb=250,
    max_file_size_bytes=2 * 1024 * 1024,
    init_timeout=30,
    verbose=True
)

If your deployment environment prevents passing secrets (like API keys or service names) as command line arguments, you can still use hud-run safely by omitting the parameters and initializing Hud within your code.

Run your service using:

hud-run --config ./hud_config.py python main.py

Then, in your code:

import hud_sdk

hud_sdk.init_session(<hud_api_key>, <your_service_name>, tags={"region": "us-east", "env": "production"}, deployment_id="v2.4.1")

Call hud_sdk.init_session() early in your code. The tags and deployment_id parameters are optional — use tags to attach key-value metadata for filtering, and deployment_id to attribute data to a specific code version.

If your environment doesn't allow using the hud-run CLI wrapper, you can start Hud directly from within your Python code:

import hud_sdk

hud_sdk.register(hud_sdk.RegisterConfig())
hud_sdk.init_session(<hud_api_key>, <your_service_name>, tags={"region": "us-east"}, deployment_id="v2.4.1")

Note: hud_sdk.register should be present as early as possible in your code. Hud will not instrument any files that were loaded before it

Functions in the same file also won't be instrumented - for full coverage, use hud-run.