---
name: infra-core-azure-storage
description: Use when working with infra-core Azure Blob storage, run manifest generation, or monitoring helpers. Covers AzureStorageSettings/get_client, AzureStorageClient, build_manifest, HeartbeatMonitor, RunLogWriter, and TelemetryClient.
---

# infra-core-azure-storage

Use this skill when the task is about Azure Blob uploads/downloads, artifact manifests, heartbeat files, run logs, or telemetry through infra-core.

## Preferred imports

- `from infra_core.azure import AzureStorageSettings, AzureStorageClient, get_client`
- `from infra_core.azure import build_manifest`
- `from infra_core.azure import HeartbeatMonitor, RunLogWriter, TelemetryClient, TelemetryConfig`

## Selection guide

- Use `AzureStorageSettings.from_env()` or `.from_env_with_prefix()` to resolve config and mode explicitly.
- Use `get_client(settings, mode)` for the shared Blob client path.
- Use `AzureStorageClient.from_settings(...)` when you need an explicitly managed client instance.
- Use `build_manifest(...)` to generate artifact manifests instead of hand-assembling file metadata and blob URLs.
- Use `HeartbeatMonitor` and `RunLogWriter` when a long-running job needs mirrored local and Azure-visible status/log files.
- Use `TelemetryClient` only when you actually need structured telemetry output; it is not a generic logger replacement.

## Important behavior

- Azure helpers require the `infra-core[azure]` extra.
- Storage is explicit and mode-aware. `strict` is the default; `best-effort` and `dev-skip` are intentional opt-outs.
- Prefer explicit `azure_client=` injection over implicit global fallback patterns.
- `build_manifest()` only falls back to blob listing when the client is configured.
- If you add a new public helper in this area, update `CAPABILITIES.md` and `src/infra_core/capabilities.py`.

## Read next when needed

- [CAPABILITIES.md](../../CAPABILITIES.md)
- [README.md](../../README.md)
- [src/infra_core/azure/storage.py](../../src/infra_core/azure/storage.py)
- [src/infra_core/azure/run_storage.py](../../src/infra_core/azure/run_storage.py)
- [src/infra_core/azure/monitoring.py](../../src/infra_core/azure/monitoring.py)
- [examples/download_and_mirror_asset.py](../../examples/download_and_mirror_asset.py)
- [tests/test_azure_storage.py](../../tests/test_azure_storage.py)
- [tests/azure/test_run_storage.py](../../tests/azure/test_run_storage.py)
- [tests/azure/test_monitoring.py](../../tests/azure/test_monitoring.py)
- [tests/test_heartbeat_critical_upload.py](../../tests/test_heartbeat_critical_upload.py)
