Execution Context, Context Scopes & Tracing
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Forze framework utilizes a robust execution system centered around the ExecutionContext, which serves as the primary mechanism for resolving infrastructure dependencies, managing invocation metadata, and handling transaction scopes. This system ensures that domain logic remains decoupled from specific infrastructure implementations by providing a unified interface to access ports such as document queries, search engines, and storage commands.
The architecture relies on nested scopes and tracing sessions to maintain observability and consistency across complex call chains. By utilizing an ExecutionRuntime, applications can manage the lifecycle of these contexts, ensuring that every request or background task has access to the necessary dependencies and identity information while automatically handling observability through OpenTelemetry integration.
Execution Context Architecture
The ExecutionContext is the entry point for all infrastructure interactions within Forze. It provides a namespaced API to resolve ports and manage the current execution state.
Core Components
The execution context is composed of several key sub-contexts and managers:
| Component | Description |
|---|---|
deps | A dependency manager used to provide or resolve configurable dependencies. |
inv_ctx | Invocation metadata context, holding identity (Authn/Tenant) and correlation IDs. |
document | Gateway for DocumentQueryPort and DocumentCommandPort. |
search | Interface for simple, hub, and federated search operations. |
tx_ctx | Transaction context manager for handling unit-of-work scopes. |
resilience | Executor for applying resilience policies like retries or circuit breakers. |
Sources: skills/forze-framework-usage/SKILL.md, src/forze/application/execution/context/execution.py
Dependency Resolution Flow
Handlers resolve infrastructure by logical specification (e.g., DocumentSpec) via the context. The following diagram illustrates how a handler interacts with the ExecutionContext to perform an operation:
Context Scopes and Lifecycle
Execution in Forze happens within controlled scopes managed by the ExecutionRuntime. A scope defines the temporal boundary for resource availability.
Execution Runtime
The ExecutionRuntime manages the DepsRegistry and LifecyclePlan. It is responsible for:
- Draining: Managing graceful shutdowns within a specified timeout (default 10s).
- Deployment Profiles: Enforcing safety checks for singleton steps in "Fleet" deployments.
- Scope Management: Creating the
ExecutionContextfor a block of work.
Invocation Metadata and Tenancy
The InvocationContext (accessible via ctx.inv_ctx) stores critical request-scoped data:
- Identity:
AuthnIdentity(who is calling) andTenantIdentity(which tenant context). - Tracing IDs:
execution_id,correlation_id, andcausation_id. - Binding: Identity is typically bound at the interface boundary (e.g., FastAPI middleware) using
ctx.inv_ctx.bind(...).
Sources: skills/forze-wiring/SKILL.md, skills/forze-observability-errors/SKILL.md, skills/forze-framework-usage/SKILL.md
Tracing and Observability
Forze integrates deeply with OpenTelemetry to provide structured diagnostics and performance monitoring.
Tracing Sessions
A TracingSession encapsulates the observability state for a specific execution thread. It tracks:
- Operation Keys: The logical name of the operation being executed.
- Spans: OpenTelemetry spans for timing and parent-child relationship tracking.
- Metrics: Emits
forze.operationsandforze.operation.durationautomatically.
Active Operations
When an operation is executed, an ActiveOperation context is established. This tracks the "plan" being executed and allows for stage-based hooks (e.g., BeforeStep, OnSuccessStep).
Transactional Scopes
The tx_ctx provides an async context manager for managing transactions. It supports nesting and post-commit side effects.
Transaction Management Features
- Reuse: Nested calls reuse the active transaction (using savepoints where supported by the adapter).
- Side Effects:
ctx.tx_ctx.defer_after_commit()allows scheduling logic to run only if the root transaction successfully commits. - Routing: Transactions are routed by name (e.g.,
"default"), allowing different infrastructure modules to manage their own transaction boundaries.
Sources: skills/forze-framework-usage/SKILL.md, skills/forze-specs-infrastructure/SKILL.md
Summary
The Execution Context system in Forze provides a unified, observable, and transaction-aware environment for application logic. By isolating infrastructure concerns into a resolvable context, Forze enables developers to write pure domain handlers that are easily testable via mocks and fully instrumented for production environments. The combination of scoped lifecycles, invocation metadata binding, and integrated tracing ensures that every operation is executed with the necessary context and visibility.