> ## Documentation Index
> Fetch the complete documentation index at: https://docs.impact.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python setup and lifecycle

> Install Impact, configure routing and keep existing OpenTelemetry providers.

## 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.

```sh theme={null}
python -m pip install 'impact==1.2.0rc10'
```

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:

```sh theme={null}
python -m pip install -r requirements.txt "$sdk_wheel"
```

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](https://docs.impact.ai/sdk/python/integrations.md) 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](https://github.com/open-telemetry/opentelemetry-python/security/advisories/GHSA-xcq7-p3pf-p88h)
·
[OpenTelemetry traceparent advisory](https://github.com/open-telemetry/opentelemetry-python/security/advisories/GHSA-mf5v-w3w3-f6cg)

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](https://github.com/urllib3/urllib3/releases/tag/2.8.0)

## 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](https://docs.impact.ai/sdk/python/api#runtime-api)
describes the entry points and [privacy settings](https://docs.impact.ai/sdk/python/capture.md) 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](https://docs.impact.ai/sdk/python/simulation.md) and [Protect](https://docs.impact.ai/sdk/python/protect.md)
  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:

```python theme={null}
import impact

runtime = await impact.init_async()
try:
    # Use the application's ordinary asynchronous provider clients here.
    print(runtime.status())
    await runtime.flush(timeout_ms=1000)
finally:
    await runtime.shutdown(timeout_ms=3000)
```

`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](https://docs.impact.ai/sdk/python/troubleshooting.md) 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.

```python theme={null}
import os

import impact

runtime = impact.init(
    service_name="support-agent",
    tracer_provider=customer_tracer_provider,
    logger_provider=customer_logger_provider,
    endpoint=os.environ["IMPACT_ENDPOINT"],
    api_key=os.environ["IMPACT_API_KEY"],
)
```

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.

```python theme={null}
runtime = impact.init(presence=True)
```

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](https://docs.impact.ai/sdk/python/api.md#provenance-and-source-references) 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](https://docs.impact.ai/sdk/python/troubleshooting.md) · [Setup plugin](https://docs.impact.ai/quickstart.md#plugin)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.