Telemetry and Context
Relevant source files
The following files were used as context for generating this wiki page:
Telemetry and context management within the Infrahub Python SDK provide a structured approach to tracking execution states and metadata across various environments. These systems ensure that operations—whether performed in the CLI, workers, or core pipeline—carry the necessary environment details and safety constraints.
The SDK utilizes an ExecutionContext to define where code is running, which directly influences available features like Jinja2 filters. Telemetry services, integrated via the CLI, handle the collection of operational data to assist in debugging and usage tracking.
Sources: infrahub_sdk/template/filters.py:8-13, infrahub_sdk/ctl/telemetry.py, AGENTS.md
Execution Context
The execution context defines the operational environment of the SDK. It uses a flag-based enumeration to categorize whether the code resides within the core system, a worker node, a local machine, or all environments.
Context Types
The ExecutionContext enum provides specific flags used to restrict or allow operations based on the trust level of the environment.
| Flag | Value | Description |
|---|---|---|
CORE | 1 | Represents the internal core pipeline environment. |
WORKER | 2 | Represents an asynchronous worker or execution agent. |
LOCAL | 4 | Represents a local developer machine or CLI environment. |
ALL | 7 | A combination flag covering all environments. |
Sources: infrahub_sdk/template/filters.py:8-13
Filter Security Architecture
The SDK uses ExecutionContext to enforce security boundaries for Jinja2 template filters. Each filter definition specifies which contexts it is allowed to run in, preventing high-risk operations in sensitive environments like CORE.
The system includes a backward-compatibility layer where a trusted property maps to context flags: trusted=True aligns with ALL, while trusted=False restricts the filter to LOCAL.
Sources: infrahub_sdk/template/filters.py:16-29, dev/specs/infp-504-artifact-composition/tasks.md:21-23
Telemetry Management
Telemetry services are primarily managed through the CLI (infrahubctl) and the underlying SDK control layer. The telemetry system tracks interactions and provides data necessary for infrastructure management.
Key Telemetry Operations
The telemetry module handles the setup and transmission of operational data. This is crucial for the "Automate inside Infrahub" and "Integrate with external systems" use cases defined in the project architecture.
| Component | Responsibility |
|---|---|
infrahub_sdk/ctl/telemetry.py | Manages CLI-level telemetry collection and reporting. |
tasks.py | Automates documentation generation for telemetry and CLI commands. |
AGENTS.md | Defines operational boundaries for telemetry and API usage. |
Sources: infrahub_sdk/ctl/telemetry.py, tasks.py:64-70, AGENTS.md
SDK Configuration and Environment
The SDK configuration, which acts as a global context for the client, is managed through Pydantic models. This configuration determines how the SDK interacts with the Infrahub API, including authentication and server endpoints.
Client Initialization Flow
The configuration context must be initialized before the SDK can perform telemetry-tracked operations.
Development Guidelines
According to the Infrahub Python SDK Constitution, telemetry and context implementations must adhere to specific principles:
- Public API Stability: Names exported via
infrahub_sdk/__init__.pyand documentedConfigfields are guaranteed stable. - Layered Architecture: CLI telemetry logic must remain a thin layer over reusable SDK methods.
- Typed Errors: Context-related failures must raise specific subclasses from the
infrahub_sdk.exceptionshierarchy.
Sources: dev/constitution.md:39-45, dev/constitution.md:60-64, dev/constitution.md:82-86
Summary
Telemetry and Context systems provide the essential metadata and security gating required for infrastructure automation. By utilizing ExecutionContext for filter security and structured telemetry for operational tracking, the SDK ensures that developers can safely interact with infrastructure data across local, worker, and core environments.