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

# Your first Trace.

> Connect your existing app to Impact, run a request, and see what happened.

You'll need access to an Impact product and an app with a supported
[JavaScript](https://docs.impact.ai/sdk/javascript/integrations.md) or [Python](https://docs.impact.ai/sdk/python/integrations.md) integration.

> [tab] With your coding agent
>
> **1. Install the setup plugin**
>
> Choose your coding tool. Replace the example path with the **full marketplace directory or Git URL** supplied by Impact.
> Plugin distribution is currently in preview; a public install URL is not available yet.
>
> > [tab] Codex
> >
> > ```sh theme={null}
> > export IMPACT_PLUGIN_MARKETPLACE='/path/to/supplied-marketplace'
> >
> > codex plugin marketplace add "$IMPACT_PLUGIN_MARKETPLACE" --json
> > codex plugin add impact-sdk-setup@impact-sdk-review --json
> > ```
> >
> > Start a new Codex session in your app and invoke `sdk-setup`. In the desktop app, select **Impact SDK setup**
> > from the registered marketplace. This plugin targets Codex CLI and desktop; the separate Impact IDE extension
> > has its own installation.
>
> > [tab] Claude Code
> >
> > ```sh theme={null}
> > export IMPACT_PLUGIN_MARKETPLACE='/path/to/supplied-marketplace'
> >
> > claude plugin marketplace add "$IMPACT_PLUGIN_MARKETPLACE"
> > claude plugin install impact-sdk-setup@impact-sdk-review
> > ```
> >
> > Open your app in Claude Code and invoke `/impact-sdk-setup:sdk-setup`.
>
> > [accordion] Which marketplace do I use?
> >
> > Use the Git URL supplied by Impact, or a local marketplace directory containing `.agents/plugins/marketplace.json`
> > and `.claude-plugin/marketplace.json`. The standalone plugin ZIP does not contain those manifests and cannot
> > replace the full marketplace directory.
>
> **2. Ask it to instrument your app**
>
> ```text theme={null}
> Add Impact tracing to this app. Keep its existing clients and telemetry,
> then help me find one real request in Impact.
> ```
>
> The plugin checks your stack, installs the SDK and helps apply the startup and shutdown changes. Installing
> the plugin alone does not change your app.
>
> **3. Connect your Impact product**
>
> Create an ingest key in Impact and put the endpoint and raw key in your app's secret configuration. Tell your
> agent where the configuration lives; keep secret values out of chat.
>
> > [accordion] Where do I get the endpoint and key?
> >
> > Ask a workspace owner or admin to open **Ingest keys → Create ingest key** in the intended product.
> > Use the **OpenTelemetry exporter settings** URL ending in `/v1/traces` and the raw ingest key.
> > Impact adds the Bearer header. Your model-provider credentials stay as they are.
>
> **Choose your content settings before sending traffic.** Available inputs, outputs, tool, retrieval and media
> content is captured by default, within SDK limits and stricter native settings. Ask the plugin to preserve your
> application's privacy controls.
> [JavaScript controls](https://docs.impact.ai/sdk/javascript/capture.md) · [Python controls](https://docs.impact.ai/sdk/python/capture.md)
>
> The plugin uses the installed SDK's version and support facts and reports missing or unverified capture.
> Simulation, Protect, presence and Source upload are configured only when you request them.
>
> After setup, [run your app and find its Trace](https://docs.impact.ai/quickstart.md#run-your-app-open-its-trace) in a separately
> authorized Impact session. The ingest key allows delivery; it does not grant read access.
>
> > [accordion] Remove the helper
> >
> > When replacing a supplied local review bundle, remove its previous registration with the commands below,
> > then install the new bundle using the steps above.
> >
> > ```sh theme={null}
> > codex plugin remove impact-sdk-setup@impact-sdk-review --json
> > codex plugin marketplace remove impact-sdk-review --json
> > # Or in Claude Code:
> > claude plugin uninstall impact-sdk-setup@impact-sdk-review
> > claude plugin marketplace remove impact-sdk-review
> > ```
> >
> > Removing the plugin stops future helper discovery. It does not uninstall the SDK or undo application edits.

> [tab] Add the SDK yourself
>
> **1. Install the SDK**
>
> Keep the compatible provider clients your application already uses.
>
> > [tab] JavaScript
> >
> > ```sh theme={null}
> > npm install --save-exact impact-ai@0.4.0-rc.10
> > ```
> >
> > Use ESM on Node.js 22.23.5 or 24.22.3, or a later security patch in either line.
> > [Installation and compatibility](https://docs.impact.ai/sdk/javascript/setup.md).
>
> > [tab] Python
> >
> > ```sh theme={null}
> > python -m pip install 'impact==1.2.0rc10'
> > ```
> >
> > Use Python 3.11 or later and your application's virtual environment.
> > [Installation and compatibility](https://docs.impact.ai/sdk/python/setup.md).
>
> **2. Connect your Impact product**
>
> In your product, open **Ingest keys → Create ingest key** as a workspace owner or admin.
> Add these values to your app's secret configuration:
>
> ```dotenv theme={null}
> IMPACT_ENDPOINT=<exporter URL ending in /v1/traces>
> IMPACT_API_KEY=<raw ingest key>
> IMPACT_SERVICE_NAME=my-app
> ```
>
> Copy the endpoint from **OpenTelemetry exporter settings**. Keep the raw key private; Impact supplies the
> Bearer header. Your existing model-provider credentials stay as they are.
>
> > [accordion] Loading these settings locally
> >
> > Use your app's existing environment loader or secret manager. If using a local env file, exclude it from source
> > control and load it before SDK startup. Node can load it with `--env-file`; Python does not load env files automatically.
>
> **3. Initialize at startup. Shut down when done.**
>
> For a supported application-owned client, initialize Impact before creating that client. Your existing model
> calls stay in place.
>
> **At application startup:**
>
> ```javascript JavaScript theme={null}
> import * as impact from 'impact-ai';
>
> const runtime = await impact.init();
> ```
>
> ```python Python theme={null}
> import impact
>
> runtime = impact.init()
> ```
>
> **In your shutdown hook, after requests finish:**
>
> ```javascript JavaScript theme={null}
> await runtime.shutdown();
> ```
>
> ```python Python theme={null}
> runtime.shutdown()
> ```
>
> Keep the returned runtime for the lifetime of your app. These are two separate placements: a script should
> put shutdown in `finally` after its work, while a server uses its existing shutdown hook.
>
> > [accordion] Using async Python?
> >
> > Inside your application's async lifespan, use `runtime = await impact.init_async()`, then
> > `await runtime.shutdown()` after requests finish. See [async application setup](https://docs.impact.ai/sdk/python/setup.md#async-applications).
>
> > [accordion] Already using OpenTelemetry or a framework?
> >
> > Keep your current providers, sampler, processors and destinations. Use the
> > [JavaScript existing-provider setup](https://docs.impact.ai/sdk/javascript/setup.md#use-your-opentelemetry-provider) or
> > [Python setup](https://docs.impact.ai/sdk/python/setup.md) to add Impact to that pipeline. Some frameworks require an earlier preload
> > or explicit bridge; the [JavaScript](https://docs.impact.ai/sdk/javascript/integrations.md) and [Python](https://docs.impact.ai/sdk/python/integrations.md)
> > integration guides supply those recipes. The setup plugin can help select one for your app.
>
> **Choose what to capture before sending traffic.** Available content is captured by default. Configure input,
> output, tools, retrieval and media categories as needed; native privacy settings still apply.
> [JavaScript controls](https://docs.impact.ai/sdk/javascript/capture.md) · [Python controls](https://docs.impact.ai/sdk/python/capture.md)

## Run your app. Open its Trace.

Make one ordinary request using your app's existing interface.

1. Open **Traces** in the same Impact product.
2. Find your service and the request you just ran.
3. Inspect the model call, available usage and captured input and output.

> [accordion] No Trace yet?
>
> Check the endpoint and key, initialization order, supported integration and `runtime.status()`.
> A successful startup or shutdown alone does not confirm delivery. Use a signed-in Impact session to view the
> result; an ingest key does not grant read access.
> [JavaScript troubleshooting](https://docs.impact.ai/sdk/javascript/troubleshooting.md) · [Python troubleshooting](https://docs.impact.ai/sdk/python/troubleshooting.md)

## Try a complete example

These standalone examples make one billable OpenAI Responses call. Use an OpenAI project key separately from
your Impact ingest key. Set `OPENAI_MODEL` to a model your project can use and adjust the model-specific options
if needed. Imports are passive; initialize Impact before constructing the client.

> [accordion] JavaScript example
>
> Use a new directory with `npm init -y`, then install the exact prerelease and the example's client:
>
> ```sh theme={null}
> npm install --save-exact impact-ai@0.4.0-rc.10 openai@7.53.0
> ```
>
> Use Node.js 22.23.5 or 24.22.3, or a later security patch in either line, with ESM. The documented npm version is
> 11.21.2. Keep an existing application's compatible clients and lockfile instead of replacing them for this example.
>
> Add `.env.impact-quickstart` to `.gitignore` before creating it with your values:
>
> ```dotenv theme={null}
> IMPACT_ENDPOINT=<copied OTLP traces URL ending in /v1/traces>
> IMPACT_API_KEY=<raw Impact ingest secret>
> IMPACT_SERVICE_NAME=impact-quickstart
> OPENAI_API_KEY=<your OpenAI project API key>
> ```
>
> Save this as `quickstart.mjs`:
>
> ```js theme={null}
> import OpenAI from 'openai';
> import * as impact from 'impact-ai';
>
> const runtime = await impact.init({ startup: 'strict' });
> try {
>   const { artifact, runtimeId } = runtime.status();
>   console.log('Impact SDK', artifact.version, 'runtime', runtimeId);
>
>   const client = new OpenAI({ maxRetries: 0 });
>   const result = await client.responses.create({
>     model: process.env.OPENAI_MODEL ?? 'gpt-6.1-sol',
>     input: 'Say hello in one sentence.',
>     max_output_tokens: 512,
>     reasoning: { effort: 'low' },
>   });
>   console.log(result.output_text);
> } finally {
>   const result = await runtime.shutdown();
>   console.log('Impact exported spans', runtime.status().exportedSpans);
>   if (!result.completed) console.warn('Impact shutdown incomplete', result.message);
> }
> ```
>
> ```sh theme={null}
> node --env-file=.env.impact-quickstart quickstart.mjs
> ```
>
> If the environment variables are already set, run `node quickstart.mjs`. In the same Impact product, find
> `impact-quickstart` and match the printed runtime ID to `impact.runtime.id`. Check **Recorded fields** for the
> model and available usage, then compare the prompt and printed reply when your product retains content.
> Confirm the selected SDK version in the output. See [installation](https://docs.impact.ai/sdk/javascript/setup.md) for supplied archives
> and [troubleshooting](https://docs.impact.ai/sdk/javascript/troubleshooting.md) for zero exported spans or missing Traces.

> [accordion] Python example
>
> Use Python 3.11 or later. These commands use a POSIX shell:
>
> ```sh theme={null}
> python3 -m venv .venv
> . .venv/bin/activate
> python -m pip install 'impact==1.2.0rc10' 'openai==3.46.0'
> ```
>
> Set `IMPACT_ENDPOINT`, `IMPACT_API_KEY`, `IMPACT_SERVICE_NAME=impact-quickstart` and `OPENAI_API_KEY` through
> your application's secret configuration as described above. Keep the complete prerelease pin. In an existing
> uv project, use `uv add 'impact==1.2.0rc10'` alongside its compatible clients. See
> [installation](https://docs.impact.ai/sdk/python/setup.md) for supplied wheels and existing OpenTelemetry.
>
> Save this as `quickstart.py`:
>
> ```python theme={null}
> import os
>
> import impact
>
> runtime = impact.init(startup="strict")
> try:
>     from openai import OpenAI
>
>     status = runtime.status()
>     print("Impact SDK", status.artifact["version"], "runtime", status.runtime_id)
>     with OpenAI(max_retries=0) as client:
>         response = client.responses.create(
>             model=os.getenv("OPENAI_MODEL", "gpt-6.1-sol"),
>             max_output_tokens=512,
>             reasoning={"effort": "low"},
>             input="Say hello in one sentence.",
>         )
>         print(response.output_text)
> finally:
>     shutdown = runtime.shutdown()
>     status = runtime.status()
>     print("Impact local delivery", shutdown.delivery)
>     print("Impact exported traces", status.traces.exported if status.traces else None)
>     if status.cause not in (None, "none"):
>         print("Impact diagnosis", status.cause, status.action)
>     if not shutdown.completed:
>         print("Impact shutdown incomplete", shutdown.message)
> ```
>
> ```sh theme={null}
> python quickstart.py
> ```
>
> In the same Impact product, find `impact-quickstart` and match its `impact.runtime.id` to the printed runtime ID.
> Check the model and available usage in **Recorded fields**, then match the prompt and printed reply when your
> product retains content. Verify the selected SDK version. Cleanup, local export and a visible Trace are separate
> checks; see [delivery diagnosis](https://docs.impact.ai/sdk/python/troubleshooting.md#read-shutdown-and-delivery-status) for `unknown`,
> `incomplete` or `exported-not-readback` status. Zero exported traces leaves capture unverified.

[OpenAI API keys](https://platform.openai.com/api-keys) ·
[OpenAI model reference](https://developers.openai.com/api/docs/models/gpt-6.1-sol)

## Next steps

[Choose your integration](https://docs.impact.ai/integrations.md), [add application context](https://docs.impact.ai/sdk/concepts.md), or choose what content to
capture in [JavaScript](https://docs.impact.ai/sdk/javascript/capture.md) or [Python](https://docs.impact.ai/sdk/python/capture.md).


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