Skip to main content

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.
In a uv project, use 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:
Set 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 instrumentation 1.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

Importing impact 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_ENDPOINT to the exact /v1/traces URL from the intended product’s OpenTelemetry exporter settings and IMPACT_API_KEY to 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_ENDPOINT to its application API origin and IMPACT_API_KEY to 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.
Local configuration errors raise before activation. On remote discovery failure, the default 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 honor Accept-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 via endpoint= 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.
Impact exports detached copies and keeps the customer records and samplers intact. A conflicting 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, set IMPACT_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.
Presence sends bounded metadata with the discovered Product and Environment, generated runtime ID, SDK and Python versions, service name and supplied deployed-version reference if known. Use 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 of IMPACT_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