haive.core.utils.debugkit.config

Development utilities configuration system.

This module provides centralized configuration for all development utilities including debugging, logging, profiling, and static analysis tools.

Classes

DevConfig	Centralized configuration for all development utilities.
Environment	Supported runtime environments.
LogLevel	Logging levels for development utilities.
StorageBackend	Storage backends for analysis data.

Module Contents

class haive.core.utils.debugkit.config.DevConfig

Centralized configuration for all development utilities.

This class provides comprehensive configuration options for debugging, logging, profiling, tracing, and static analysis tools. It automatically adjusts settings based on the runtime environment.

enabled

Whether development utilities are enabled globally

environment

Current runtime environment

debug_enabled

Enable debug utilities (icecream, pdb, etc.)

log_enabled

Enable logging utilities

trace_enabled

Enable execution tracing

profile_enabled

Enable performance profiling

benchmark_enabled

Enable benchmarking utilities

static_analysis_enabled

Enable static analysis tools

production_safe

Automatically reduce overhead in production

trace_sampling_rate

Percentage of traces to capture (0.0-1.0)

profile_overhead_limit

Maximum acceptable performance overhead

storage_enabled

Enable persistent storage of analysis data

storage_backend

Backend for storing analysis data

storage_path

Path for file-based storage

storage_config

Additional storage configuration

use_rich

Enable rich terminal formatting

color_enabled

Enable colored output

verbose

Enable verbose output

log_level

Minimum logging level

auto_analyze

Automatically analyze instrumented functions

runtime_type_check

Enable runtime type checking

correlation_enabled

Enable correlation ID tracking

dashboard_enabled

Enable web dashboard

dashboard_port

Port for web dashboard

max_file_size

Maximum size for analysis files (bytes)

retention_days

Days to retain analysis data

excluded_paths

Paths to exclude from analysis

included_tools

Static analysis tools to include

excluded_tools

Static analysis tools to exclude

Examples

Basic usage with defaults:

config = DevConfig()
print(f"Environment: {config.environment}")
print(f"Debug enabled: {config.debug_enabled}")

Custom configuration:

config = DevConfig(
    environment=Environment.PRODUCTION,
    trace_sampling_rate=0.01,
    storage_backend=StorageBackend.POSTGRESQL
)

Environment-based configuration:

config = DevConfig.from_env()
config.configure_for_testing()

classmethod from_env()

Create configuration from environment variables.

Reads configuration from environment variables with HAIVE_ prefix. Provides a convenient way to configure the system through environment variables in containerized or CI/CD environments.

Returns:

Configuration instance populated from environment

Return type:

DevConfig

Environment Variables:

HAIVE_ENV: Runtime environment (development/testing/staging/production) HAIVE_DEV_ENABLED: Enable development utilities (true/false) HAIVE_DEBUG_ENABLED: Enable debug utilities (true/false) HAIVE_LOG_ENABLED: Enable logging utilities (true/false) HAIVE_TRACE_ENABLED: Enable tracing utilities (true/false) HAIVE_PROFILE_ENABLED: Enable profiling utilities (true/false) HAIVE_BENCHMARK_ENABLED: Enable benchmarking utilities (true/false) HAIVE_STATIC_ANALYSIS_ENABLED: Enable static analysis (true/false) HAIVE_TRACE_SAMPLING_RATE: Trace sampling rate (0.0-1.0) HAIVE_STORAGE_BACKEND: Storage backend (none/memory/sqlite/postgresql/file) HAIVE_STORAGE_PATH: Path for file-based storage HAIVE_LOG_LEVEL: Minimum logging level (TRACE/DEBUG/INFO/WARNING/ERROR) HAIVE_DASHBOARD_ENABLED: Enable web dashboard (true/false) HAIVE_DASHBOARD_PORT: Port for web dashboard (integer) HAIVE_VERBOSE: Enable verbose output (true/false)

Examples

Load from environment:

# Set environment variables
os.environ["HAIVE_ENV"] = "production"
os.environ["HAIVE_TRACE_SAMPLING_RATE"] = "0.01"

# Create config
config = DevConfig.from_env()
assert config.environment == Environment.PRODUCTION
assert config.trace_sampling_rate == 0.01

get_effective_log_level()

Get the effective log level as string.

Returns:

Log level string compatible with logging libraries

Return type:

str

Examples

Configure logger:

import logging
logging.basicConfig(level=config.get_effective_log_level())

get_storage_config()

Get complete storage configuration.

Returns:

Storage configuration dictionary

Return type:

Dict[str, Any]

Examples

Get storage settings:

storage_config = config.get_storage_config()
backend = storage_config["backend"]
path = storage_config["path"]

is_tool_enabled(tool_name)

Check if a specific tool is enabled.

Parameters:

tool_name (str) – Name of the tool to check

Returns:

True if the tool is enabled, False otherwise

Return type:

bool

Examples

Check tool availability:

if config.is_tool_enabled("mypy"):
    # Run mypy analysis
    pass

should_sample_trace()

Determine if current trace should be sampled.

Uses the configured sampling rate to decide whether to capture a trace. This helps reduce overhead in high-throughput environments.

Returns:

True if trace should be captured, False otherwise

Return type:

bool

Examples

Conditional tracing:

if config.should_sample_trace():
    # Capture detailed trace
    trace_function()

to_dict()

Convert configuration to dictionary.

Returns:

Configuration as dictionary

Return type:

Dict[str, Any]

Examples

Serialize config:

config_dict = config.to_dict()
json.dump(config_dict, file)

update(**kwargs)

Update configuration with new values.

Parameters:

**kwargs (Any) – Configuration values to update

Return type:

None

Examples

Update multiple values:

config.update(
    verbose=True,
    log_level=LogLevel.DEBUG,
    trace_sampling_rate=0.5
)

class haive.core.utils.debugkit.config.Environment

Bases: str, enum.Enum

Supported runtime environments.

DEVELOPMENT

Local development environment with full debugging

TESTING

Test environment with reduced overhead

STAGING

Staging environment with minimal debugging

PRODUCTION

Production environment with error logging only

Initialize self. See help(type(self)) for accurate signature.

class haive.core.utils.debugkit.config.LogLevel

Bases: str, enum.Enum

Logging levels for development utilities.

TRACE

Most verbose logging including execution traces

DEBUG

Debug information for development

INFO

General information messages

WARNING

Warning messages for potential issues

ERROR

Error messages only

Initialize self. See help(type(self)) for accurate signature.

class haive.core.utils.debugkit.config.StorageBackend

Bases: str, enum.Enum

Storage backends for analysis data.

NONE

No persistent storage

MEMORY

In-memory storage (lost on restart)

SQLITE

SQLite database storage

POSTGRESQL

PostgreSQL database storage

FILE

File-based storage

Initialize self. See help(type(self)) for accurate signature.