Install
Impact requires Python 3.11 or newer. Pin the full version, including its prerelease suffix, and resolve it together with your application’s existing dependencies.uv add 'impact==1.2.0rc10'. If Impact supplies a wheel, pass its absolute path to
uv add. For a pip requirements workflow, install the wheel and your requirements in the same command:
sdk_wheel to the supplied wheel path and retain the dependency in the application’s requirements. Use
uv add for an existing uv project so it updates the project and lockfile. uv pip install is suited to a
disposable environment.
For the standalone quickstart with a supplied wheel, replace only impact==1.2.0rc10 with its wheel path
and keep openai==3.46.0. Verify runtime.status().artifact["version"] against the supplied candidate.
Dependency compatibility
The base package includes capture machinery. Keep your compatible native clients and frameworks. Extras are convenience sets for a new environment. The integration catalogue identifies the native versions and operation boundaries independently of dependency resolution. The SDK uses the GenAI instrumentation1.3b0 family and Anthropic’s native 2.6.0 tracing. It requires
OpenTelemetry >=1.45.2,<1.46 with the corresponding 0.66b2 or later instrumentation family. A project
pinned to OpenTelemetry SDK 1.39.1 and FastAPI instrumentation 0.60b1 needs a coordinated telemetry upgrade.
Resolve the complete application together to avoid leaving older middleware incompatible or using unpatched
propagation dependencies.
OpenTelemetry tracestate advisory
·
OpenTelemetry traceparent advisory
Use separate environments for the gemini and adk extras. gemini selects Google Gen AI 3.0.0. adk
selects ADK 2.14.1, Google Gen AI 2.34.0 and OpenTelemetry SDK 1.45.2. An existing ADK app can install base
impact alongside its compatible dependencies.
The base package admits protobuf 6.33.5 through 7.x, Requests 2.33 through 2.x and urllib3 2.8.0 through 2.x.
urllib3 2.8.0 security fixes
Application startup
Importingimpact is passive. Initialize Impact before constructing the native clients and retain the
returned runtime for status, flush and shutdown. The init() reference
describes the entry points and privacy settings cover content capture.
- Direct OTLP. Set
IMPACT_ENDPOINTto the exact/v1/tracesURL from the intended product’s OpenTelemetry exporter settings andIMPACT_API_KEYto its raw ingest key. Impact adds the Bearer header. Authentication and receiver reachability are checked when records are sent, including when startup is strict. - Product-key discovery. When the deployment offers discovery, set
IMPACT_ENDPOINTto its application API origin andIMPACT_API_KEYto the Product key with its required grant. The SDK uses connection protocol v2. Traces require the Traces grant. Simulation and Protect each require explicit activation and their own authority.
startup="fail-open" returns an unavailable runtime so the application can continue. Inspect
runtime.status().cause, .action and .limitations. startup="strict" raises instead. Equivalent
concurrent calls share one attempt and apply their own failure policy. After a settled failure, correct the
configuration and call init again to retry. Use the new handle after the retry. Each unavailable handle
reports only its own status and cannot close a newer active runtime.
Async applications
Use the async view from your application’s running event loop:init_async() returns AsyncRuntime. status() and tracer_provider are synchronous local reads. Startup,
delivery, shutdown and explicit capability activation keep blocking SDK work off the application loop.
Equivalent sync and async calls share one runtime and its resources. The two views use timeout_ms for their
lifecycle calls. Application clients and customer telemetry remain application-owned.
A cancelled init_async() caller receives CancelledError. If all callers cancel before activation commits,
Impact skips activation and discards late discovery results. After the commit, activation settles
independently. A successful runtime stays active and a surviving waiter or equivalent retry receives it.
Delivery and shutdown deadlines
Impact-owned OTLP, setup and presence HTTP attempts share an absolute deadline through headers and acknowledgement reads. Direct TCP addresses use the remaining budget and expiry interrupts connected socket I/O. System DNS can outlive that budget. An expired attempt sends nothing once the lookup returns. Optional SOCKS proxy backends own their connection negotiation timeout. Customer trace and log callbacks return without waiting for Impact to drain. A late, incomplete or oversized OTLP success acknowledgement leaves delivery unknown. The SDK does not resend a known HTTP success. A setup attempt may retry an uncertain acknowledgement with the same report ID and bytes, which the receiver must deduplicate. Receivers should honorAccept-Encoding: identity for these
bounded acknowledgements. Presence has its own delivery status.
SDK-owned Simulation and Protect WebSockets reject redirects and join their owned connection work on close. A
blocking DNS lookup can delay cleanup there too. Retry an incomplete shutdown to join the same pending work.
Completed cleanup phases are skipped. Use troubleshooting to check delivery
independently of shutdown.
OpenTelemetry routing
Let Impact own the destination
In managed mode, supply the endpoint and key as environment variables or viaendpoint= and api_key=.
IMPACT_SERVICE_NAME or service_name= labels the service. With no tracer_provider, Impact owns the
capture TracerProvider. If the process has no registered global tracer provider, Impact registers its managed
provider through OpenTelemetry’s public API so native instrumentation can route through it. An existing global
provider stays registered and status().provider_ownership["global_traces"] is "external".
Impact owns its LoggerProvider when an endpoint is present and the application supplies no logger provider. In
managed mode, sampling takes "all" (the default), "none" or a finite float greater than zero and at most
one, such as 0.1, for parent-aware whole-operation sampling.
Keep your existing providers
Pass the application’s existing tracer provider and optional logger provider. Supply both Impact route values explicitly to add a destination. The application in this example has already configured both providers.sampling=
value raises before activation. Omitting both route options selects customer-routed delivery even when
managed-mode variables are present. For a Product Trace, that exporter must already send to Impact. In this
mode correlated content logs require an explicit LoggerProvider.
shutdown() closes SDK-owned resources. Impact processors on customer providers remain installed but inactive
after shutdown because Python OpenTelemetry exposes no public removal API. To configure capture again after
shutdown, start a new process.
Runtime presence
On deployments advertising an authorized presence endpoint, setIMPACT_PRESENCE=true or pass presence=True
to init(). Presence defaults off. An explicit presence=True or False takes precedence over the
environment setting. Direct OTLP supplies Trace authority. Presence requires the Product-key discovery route
and its own advertised endpoint.
status().presence for
the last local attempt and the platform’s last-seen time and finite lease for freshness. Presence establishes
runtime observations only. Trace, Simulation, Protect and Source each have their own status.
Shutdown fences renewals and attempts a bounded stopped report. The same HTTP deadline and DNS limitation
apply. If the join budget expires, shutdown reports incomplete presence cleanup and a retry joins the same
worker.
Deployed version and Source correlation
ImpactContext(version_id=...) takes precedence over IMPACT_VERSION_ID. The SDK trims the environment value
and treats a blank as absent. Supply the actual deployed ref to the running application and use the same value
in the Source CLI upload job. The SDK never infers this value from the application or repository.
The reported reference labels native Trace context (impact.product.version.id), the default Simulation
target selector and presence metadata. Source sync associates the exact ref with the captured code snapshot.
Callable discovery validates an existing Product/target/material/placement binding and can resolve a deployed
commit to a retained declaration. A canonical Builder whole-material Version UUID requires an authorized
Builder/deployment binding. See the application API for
optional callsite capture.
Setup reporting
On routes that supply setup reporting authority, provide the complete envelope from Impact. It consists ofIMPACT_SETUP_REPORT_ENDPOINT, IMPACT_SETUP_REPORT_API_KEY, IMPACT_ROUTE_ID, IMPACT_ROUTE_REVISION and
IMPACT_ENVIRONMENT_ID. The SDK sends the report automatically. When the envelope is unset, capture continues
and status().setup_report.outcome is not-configured. A partial envelope rejects at initialization.
IMPACT_ENVIRONMENT_ID alone supplies neither the envelope nor a reported environment name. Use
context=ImpactContext(environment="...") for the latter.
Troubleshooting · Setup plugin