Production-ready Azure bootstrap library for seamless integration of Azure App Configuration, Key Vault, and Application Insights into Azure Functions applications.
This repository contains the source code and build configuration for the azure-bootstrap pip library - a reusable bootstrap package used across 17+ Azure Functions repositories in the organization.
Package Name: azure-bootstrap
Current Version: 2.1.0
Distribution: PyPI (public)
v1 solved the logging β configuration circular dependency for Azure Functions apps. v2 expands that into the entire cross-cutting layer every Vizius Azure project used to re-implement on top of v1.
- Bootstrap Logging β works immediately, before configuration loads
- Configuration Loading β Azure App Configuration + Key Vault
- Telemetry Setup β Application Insights via OpenTelemetry
- Environment Loading β all configs auto-loaded to
os.environ
- Structured logging with
ExtraFieldsFormatter, correlation IDs viacorrelation_scope, secret/email/control-char masking, noisy-logger silencing - Tracing β
@traceddecorator with latency histograms, slow-budget alerts, sensitive-arg masking, async auto-detection - Tiered alerts β
alert_dev_teamwith WARN / ERROR / CRITICAL, dedup + rate-limit + escalation,install_global_exception_hooks - Error vocabulary β
PipelineErrorβUnrecoverableError/TransientErrorwithis_unrecoverable(exc)classifier; soft-fail- per-phase guards
- Ingress hardening β 4-gate attachment classifier (extension β MIME β size β magic-byte), zip-bomb defense, PDF action stripping, bidi-stripping filename sanitizer + root confinement
- Service Bus consumer β
handle_messagewith dead-letter-vs-abandon routing,lock_for_processcovering long-running handlers - Webhook + auth β
install_graph_webhook_routewith validation handshake, clientState verification, dedup, rate limit - AI usage tracker β tokens + cost across sliding windows, soft TPM cap, threshold-based CRITICAL alerts
- Operational β health probes, FastAPI middleware, heartbeat +
consumer watchdog, dynamic log-level refresh, DLQ digest with
HMAC-signed resubmit tokens,
/api/metricsaggregator
See CHANGELOG.md for the full v2 surface and MIGRATING-FROM-V1.md for the adoption order.
- Quick Start
- Installation
- Configuration
- Usage Examples
- API Reference
- Migration Guide
- Development
- Contributing
- Troubleshooting
from azure_bootstrap.alerts import install_global_exception_hooks, register_dispatcher
from azure_bootstrap.bootstrap import ensure_bootstrap
from azure_bootstrap.logging import configure_logging
def my_email_sender(recipients, subject, html_body):
... # any callable matching this signature
configure_logging()
install_global_exception_hooks()
ensure_bootstrap()
register_dispatcher(my_email_sender, recipients=["dev-alerts@example.com"])Every line emitted via stdlib logging now carries correlation IDs, extra
fields render as greppable key=repr(value) pairs, noisy third-party loggers
are silenced, and uncaught exceptions fire CRITICAL alerts (with dedup +
rate-limit + escalation). See MIGRATING-FROM-V1.md
for the full extras matrix.
"""function_app.py"""
import os
import azure.functions as func
from azure_bootstrap import initialize_application, get_bootstrap_logger
_bootstrap_initialized = False
_logger = None
def _ensure_bootstrap():
global _bootstrap_initialized, _logger
if _bootstrap_initialized:
return
_logger = get_bootstrap_logger(__name__)
config_repo = initialize_application()
_bootstrap_initialized = True
app = func.FunctionApp()
@app.route(route="hello")
def hello(req):
_ensure_bootstrap()
db_host = os.getenv("DATABASE_HOST") # All configs in os.environ
return func.HttpResponse(f"Hello! DB: {db_host}")git clone https://github.com/TheViziusGroup/azure-bootstrap
cd azure-bootstrap
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
pytestpip install azure-bootstrap# requirements.txt
azure-bootstrap>=2.0,<3
| Extra | Pulls | When you need |
|---|---|---|
[alerts] |
stdlib only | Tiered alert dispatcher + global excepthooks |
[health] |
core deps | App Config + App Insights health probes |
[fastapi] |
fastapi |
Request middleware, webhook route, rate-limit dep |
[heartbeat] |
stdlib only | Background heartbeat + consumer watchdog |
[config-refresh] |
stdlib only | Dynamic LOG_LEVEL refresh via App Config |
[servicebus] |
azure-servicebus |
DLQ digest, growth alarm, consumer wrapper, sb_lock |
[openai] |
stdlib only | AI usage tracker (SDK-agnostic) |
[tokens] |
stdlib only | HMAC action tokens |
[scheduler] |
apscheduler |
NCRONTAB parser |
[metrics] |
stdlib only | /api/metrics aggregator |
[retry] |
tenacity |
Pre-configured retry wrappers |
[ingress] |
stdlib only | 4-gate attachment classifier |
[pdf-safety] |
pypdf |
PDF action stripping |
[ratelimit] |
stdlib only | TokenBucket |
[notify] |
stdlib only | Two-tier notification builders + throttle |
[subscription] |
stdlib only | Renewal loop pattern |
[identity] |
core deps | build_credential (Workload Identity preferred) |
[auth] |
(pair with [fastapi]) |
Graph webhook + API-key helpers |
[sb-lock] |
(pair with [servicebus]) |
Message lock auto-renewer |
[audit] |
stdlib only | Audit-log conventions |
[failclose] |
stdlib only | Env-var fail-closed-vs-open helpers |
[transports] |
stdlib only | Logging transport registry (console / App Insights / Sumo Logic) |
[sumologic] |
requests |
Buffered POST to a Sumo Logic HTTP Source (urllib3 Retry, gzip, Retry-After) |
[all] |
everything above | All extras at once |
# Common combinations
pip install 'azure-bootstrap[alerts,fastapi,health]'
pip install 'azure-bootstrap[servicebus,sb-lock,retry,heartbeat]'
pip install 'azure-bootstrap[all]'local.settings.json:
{
"Values": {
"AZURE_APP_CONFIGURATION_CONNECTION_STRING": "Endpoint=https://...;Id=...;Secret=...",
"AZURE_KEY_VAULT_URL": "https://myvault.vault.azure.net/",
"AZURE_APP_CONFIG_LABEL": "dev"
}
}local.settings.json:
{
"Values": {
"DATABASE_HOST": "localhost",
"DATABASE_NAME": "mydb",
"API_KEY": "your-api-key"
}
}The library gracefully falls back to environment variables when App Configuration is not available.
Priority Order (highest to lowest):
- Environment variables (
os.environ) - Local overrides win - Azure App Configuration - Centralized config
- Key Vault secrets - Secure secrets (via App Config references)
- Default values - Fallback
Example:
# local.settings.json sets: USE_MOCK_DB = "true"
# App Config has: USE_MOCK_DB = "false"
# After bootstrap: os.getenv("USE_MOCK_DB") β "true" (local wins!)The full examples library lives in examples/ β 37 numbered
single-concept files plus 3 end-to-end app templates. Each example is
runnable with USE_MOCK_BOOTSTRAP=true (no real Azure needed) and ends
with a # ββ Expected output ββ block.
Start here:
| File | Concept |
|---|---|
| examples/01_quickstart.py | 30-second setup |
| examples/03_correlation_scope.py | Correlation IDs across nested calls |
| examples/04_traced_decorator.py | @traced sync + async |
| examples/09_soft_fail.py | Degraded-result pattern |
| examples/15_ingress_classifier.py | 4-gate attachment pipeline |
| examples/21_consumer_wrapper.py | Service Bus handler |
| examples/27_alerts_dispatcher.py | Tiered alerts |
| examples/e2e_azure_function.py | Full Azure Function (v2) |
| examples/e2e_fastapi_pipeline.py | Full FastAPI app |
| examples/e2e_aks_sb_worker.py | Full AKS Service Bus consumer |
See examples/README.md for the full index + reading order + per-example pip-extra requirements.
from azure_bootstrap import initialize_application, get_bootstrap_logger
logger = get_bootstrap_logger(__name__)
config_repo = initialize_application()
# All configs now in os.environ
db_host = os.getenv("DATABASE_HOST")The library exports ~40 top-level symbols and 30+ subpackages. Rather than duplicating the spec here, each module's public surface is documented in three places:
- Module docstrings β every
azure_bootstrap/<module>/__init__.pyopens with a docstring explaining the module's purpose and invariants. - Per-symbol runnable examples β examples/ covers every public function with at least one focused demo (see the table above).
- CHANGELOG.md β the v2.0.0 entry catalogs every new public symbol, organized by tier.
The original 20 entries in v1's __all__ are still exported with the
same signatures and behavior. See
azure_bootstrap/__init__.py for the
authoritative list. The four most-used:
initialize_application(secrets_repository=None)βEnhancedConfigRepositoryget_bootstrap_logger(name)βlogging.Loggercreate_enhanced_config_repository(app_config_connection_string, ...)βEnhancedConfigRepositorytelemetry_managerβ the singletonTelemetryManagerinstance
The most common v2 primitives are re-exported from the top-level namespace for ergonomic import:
from azure_bootstrap import (
# Logging
configure_logging, correlation_scope, get_correlation_id, set_correlation_id,
mask_api_key, mask_email_address, mask_secrets_in_dict, sanitize_for_log,
# Tracing + counters
traced, latency_snapshot, bump_counter, counter_snapshot,
# Bootstrap
ensure_bootstrap, bootstrap_initialized, load_local_settings, refresh_setting,
# Exception hierarchy
PipelineError, UnrecoverableError, TransientError,
InvalidMessageError, RateLimitError, NetworkError, is_unrecoverable,
# Soft-fail + phases + validation
soft_fail, soft_fail_with, SoftFailResult,
run_phase, run_phases, PhaseResult,
validate_message, MessageSchema, queue_message_schema,
# Path / security
sanitize_path_segment, confine_to_root, compare_secrets,
)Everything else is reachable via its subpackage (e.g.
from azure_bootstrap.alerts import alert_dev_team).
TL;DR: Pin azure-bootstrap>=2.0,<3. No code changes needed β
v1 imports keep working. The full migration document is
MIGRATING-FROM-V1.md, including the suggested
adoption order for v2 primitives, the extras matrix, and the small list
of behavior changes to be aware of (notably: DEBUG_LOGGING_ENABLED is
now a required second factor for DEBUG output).
The original v0 β v1 migration (extracting bootstrap code out of a
project's src/infrastructure/) is preserved in git history at the
1.0.0 tag β see the Migration Guide section of that revision's
README if you're maintaining a legacy app that hasn't crossed the
boundary yet.
# Clone repository
git clone https://github.com/TheViziusGroup/azure-bootstrap
cd azure-bootstrap
# Create virtual environment
python -m venv .venv
.venv\Scripts\activate # Windows
source .venv/bin/activate # Linux/Mac
# Install with dev dependencies
pip install -e ".[dev]"
# Verify setup
pytest# All tests with coverage
pytest --cov=azure_bootstrap --cov-report=term-missing
# Specific test
pytest test/services/test_application_bootstrap.py -v
# Generate HTML coverage report
pytest --cov=azure_bootstrap --cov-report=html
open htmlcov/index.html# Install build tools
pip install build twine
# Build wheel and source distribution
python -m build
# Output:
# dist/azure_bootstrap-2.1.0-py3-none-any.whl
# dist/azure_bootstrap-2.1.0.tar.gz
# Verify package
twine check dist/*# Manual publish
pip install twine
twine upload dist/*
# Or automated via pipeline (preferred β uses OIDC Trusted Publisher)
git tag v2.1.0
git push origin main --tagsWe welcome contributions! Please follow these guidelines:
main (production)
βββ dev (integration)
βββ feature/feature-name
βββ bugfix/bug-description
βββ hotfix/critical-fix
- feature/* - New features (branch from
dev, merge todev) - bugfix/* - Bug fixes (branch from
dev, merge todev) - hotfix/* - Critical fixes (branch from
main, merge tomainANDdev) - release/* - Release preparation (branch from
dev, merge tomainanddev)
- β Test Coverage: Minimum 85% (90% for new code) β raised at v2.0.0
- β Code Style: Black formatting, Ruff linting
- β Type Hints: Required for all public APIs
- β Documentation: Docstrings for all public functions
- β Commit Messages: Conventional Commits format
# Format code
black azure_bootstrap/ test/
# Lint code
ruff check azure_bootstrap/ test/
# Type check
mypy azure_bootstrap/
# Run tests
pytest --cov=azure_bootstrap --cov-report=term-missing
# All checks must pass β
See CONTRIBUTING.md for complete guidelines.
# Solution
pip install azure-bootstrap# WRONG
from azure_bootstrap.infrastructure import initialize_application
# CORRECT
from azure_bootstrap import initialize_application# Clean environment
rm -rf .venv
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[test]"
pytest# Verify the package is published
pip install azure-bootstrap --verbose| Document | Audience | Purpose |
|---|---|---|
| README.md | Everyone | Library overview (you are here) |
| CHANGELOG.md | Everyone | Complete release-by-release surface |
| MIGRATING-FROM-V1.md | v1 adopters | v1 β v2 upgrade path + adoption order |
| examples/README.md | New adopters | Reading order through ~40 runnable examples |
| CLAUDE.md | AI Assistants & Developers | Development context, version history, CI/CD setup |
| CONTRIBUTING.md | Contributors | Git workflow, quality standards, tooling setup, PR process |
| LICENSE | Everyone | License terms |
The examples/ directory contains a flat, numbered library of single-concept files plus three end-to-end app templates. Every numbered file is self-contained β drop one into your project as a starting point. See examples/README.md for the full index.
azure-bootstrap/
βββ azure_bootstrap/ # π¦ Main package
β βββ __init__.py # Public API surface (v1 + v2)
β βββ py.typed # PEP 561 type-hint marker
β β
β β v1 (preserved unchanged)
β βββ models/ # ConfigurationError / RepositoryError / KeyVaultError
β βββ repositories/ # App Config + Key Vault loaders + interfaces
β βββ services/ # ApplicationBootstrap, BootstrapLogger, TelemetryManager
β β
β β v2 Tier 1 (always-on, stdlib only)
β βββ logging/ # configure_logging, formatter, masking, correlation, noise, JsonLogFormatter
β βββ transports/ # transport registry + console/app_insights/sumo_logic
β βββ tracing/ # @traced, latency histograms, slow thresholds
β βββ counters/ # bump_counter, counter_snapshot
β βββ bootstrap/ # ensure_bootstrap, load_local_settings
β βββ exceptions/ # PipelineError tree + is_unrecoverable
β βββ softfail/ # soft_fail, soft_fail_with
β βββ phases/ # run_phase, run_phases
β βββ validation/ # queue_message_schema, validate_message
β βββ path_safety/ # sanitize_path_segment, confine_to_root
β βββ security/ # compare_secrets, verify_api_key_header
β βββ identity/ # build_credential, credential_health
β βββ audit/ # build_audit_extra
β βββ failclose/ # require_env, optional_env, fail_open_env
β β
β β v2 Tier 2 (opt-in extras)
β βββ alerts/ # alert_dev_team + dispatcher + escalation + render
β βββ health/ # check_app_config_health / app_insights / handler-detect
β βββ fastapi_middleware/ # install_middleware (request timing + 5xx alerts)
β βββ heartbeat/ # background heartbeat + consumer watchdog
β βββ config_refresh/ # refresh_log_flags
β βββ retry/ # build_retry, retry_azure_transient, retry_ai_transient
β βββ ingress/ # 4-gate attachment classifier
β βββ ratelimit/ # TokenBucket + presets
β βββ notify/ # two-tier notification builders + sender throttle
β βββ subscription/ # ensure_resource + renewal_loop
β βββ auth/ # install_graph_webhook_route + WebhookDedup
β β
β β v2 Tier 3 (advanced opt-in)
β βββ servicebus/ # handle_message + DLQ digest + growth alarm + tokens
β βββ openai/ # AI usage tracker (SDK-agnostic)
β βββ tokens/ # issue/verify_action_token (HMAC-SHA256)
β βββ scheduler/ # parse_cron_trigger (NCRONTAB)
β βββ metrics/ # build_metrics_snapshot
β βββ pdf_safety/ # sanitize_pdf_for_passthrough
β βββ sb_lock/ # lock_for_process, ManagedLock
β
βββ test/ # π§ͺ Test suite (469 tests, 87.48% coverage)
βββ examples/ # π‘ Examples library β see examples/README.md
βββ .github/workflows/ci-cd.yml # π GitHub Actions CI/CD
βββ .githooks/ # πͺ Git hooks (pre-commit, pre-push)
βββ .vscode/ # π» VS Code workspace config
βββ pyproject.toml # βοΈ Package metadata + ~24 optional extras
βββ README.md # π You are here
βββ CHANGELOG.md # π Full release surface
βββ MIGRATING-FROM-V1.md # π v1 β v2 adoption guide
βββ CLAUDE.md # π€ AI assistant context + CI/CD ops
βββ CONTRIBUTING.md # π₯ Contribution guidelines + tooling
βββ LICENSE # π MIT
- Current: 87.07% overall, 423 passing tests
- Requirement: 85% minimum (raised from 80% at v2.0.0), 90% new code
- Critical Paths: 100% coverage (bootstrap flow, exception classifier, alert dispatcher)
pytest # All tests
pytest -v # Verbose
pytest --cov # With coverage
pytest test/alerts/ -v # Specific subpackage
pytest test/tracing/ -v # Another subpackageThe test suite uses AZURE_BOOTSTRAP_ALLOW_RESET=1 (set automatically
via test/conftest.py) to gate the library's test-only reset_state()
helpers. Don't set this in production.
β
Package code (azure_bootstrap/ β ~70 .py files across 30+ subpackages)
β
Type hints (py.typed marker)
β
LICENSE file
β Tests (test/)
β Examples (examples/)
β Development files (.gitignore, .githooks/, .vscode/, etc.)
β Build artifacts (dist/, build/, htmlcov/)
See MANIFEST.in for distribution control.
The library uses GitHub Actions for continuous integration and deployment. The workflow automatically:
- Build & Test - Installs dependencies, runs tests with coverage
- Publish - Uploads package to PyPI (main branch and tags only)
- Validate - Tests installation from feed
- Push to main β Stable release (e.g.,
2.0.0) - Push to develop β Development release with timestamp (e.g.,
2.0.0.dev20260518123456) - Pull requests β Build and test only (no publish)
- Tags (v)* β Tagged stable release
See .github/workflows/ci-cd.yml for workflow configuration.
For complete CI/CD setup instructions, see the CI/CD Setup section in CLAUDE.md.
- Major (X.0.0) β Breaking API changes
- Minor (0.X.0) β New features (backwards compatible)
- Patch (0.0.X) β Bug fixes
v2.1.0 adds the logging transport layer (console / App Insights / Sumo Logic) and is strictly additive β the public API surface is unchanged. Like v2.0.0, every v1 public symbol is preserved byte-identical. See CHANGELOG.md for the full release surface and MIGRATING-FROM-V1.md for the adoption order.
This library is used across 17+ Azure Functions / FastAPI / AKS-worker repositories at Vizius β payroll ingestion, NETA report generation, email-driven document pipelines, HITL review tooling, vector store managers, and more.
- Python 3.11+
- Azure subscription with (any/all optional):
- Azure App Configuration
- Azure Key Vault
- Application Insights
- Azure Service Bus
- Azure OpenAI / Microsoft Graph
azure-appconfiguration-provider >= 1.0.0
azure-keyvault-secrets >= 4.7.0
azure-identity >= 1.15.0
azure-monitor-opentelemetry >= 1.2.0
opentelemetry-api >= 1.22.0
# Pinned for CVE remediation:
azure-core >= 1.38.0 # CVE-2026-21226
filelock >= 3.20.3 # CVE-2025-68146, CVE-2026-22701
urllib3 >= 2.6.3 # CVE-2026-21441Optional extras pull additional runtime deps only when installed β see the Installation table near the top of this file for the full matrix.
- β Single Source of Truth - One codebase for 17+ projects
- β Consistent Behavior - Same bootstrap logic everywhere
- β Easy Maintenance - Fix bugs once, benefit everywhere
- β Version Control - Semantic versioning with changelogs
- β
Simple Integration - Just
pip installand 2-line import - β No Implementation Knowledge - Use public API, done
- β Type-Safe - Full type hints for IDE support
- β Well-Tested - 80%+ coverage, production-proven
- β Centralized Updates - Deploy improvements once
- β Reduced Duplication - No copy-paste errors
- β Better Monitoring - Consistent telemetry
- β Easier Debugging - Same code across projects
MIT License - See LICENSE for details.
- Repository: https://github.com/TheViziusGroup/azure-bootstrap
- Issues: https://github.com/TheViziusGroup/azure-bootstrap/issues
- PyPI: https://pypi.org/project/azure-bootstrap/
Ready to get started? pip install azure-bootstrap, then open
examples/01_quickstart.py for the
30-second setup and examples/README.md for the
full reading order.