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

# Configure the JavaScript SDK

> Choose your connection, initialize capture, and keep the ownership of existing OpenTelemetry.

Install `impact-ai` alongside your application's provider and framework clients. The package uses ESM and
requires Node.js 22.15 or later. For Node 22 and 24, use 22.23.5 or 24.22.3 or a later security patch on the same
release line. The documented installation uses npm 11.21.2. Check the executable on your path with `npm --version`.
[Node.js security releases](https://nodejs.org/en/blog/vulnerability/november-2026-security-releases).

```sh theme={null}
npm install --save-exact impact-ai@0.4.0-rc.10
```

Pin the complete prerelease version. If you received an unpublished package archive, install that exact file
and verify its version in `runtime.status().artifact.version`.

```sh theme={null}
npm install --save-exact /absolute/path/to/impact-ai.tgz
```

For the standalone quickstart with a supplied archive, replace only the SDK requirement with the tarball
path and keep `openai@7.53.0`. Verify the installed version against the supplied candidate.

Impact ships the capture owners. Keep compatible application peers in your own manifest and lockfile.
[Check the provider and framework requirements](https://docs.impact.ai/sdk/javascript/integrations.md).

## Choose a connection

Use the OTLP traces URL and ingest key copied from the intended Impact product for direct ingestion.
`IMPACT_ENDPOINT` takes the URL ending in `/v1/traces`. `IMPACT_API_KEY` takes the raw ingest key and
`IMPACT_SERVICE_NAME` labels the service. The equivalent options are `endpoint`, `apiKey`, and `serviceName`.
Direct OTLP checks reachability and authorization when records are exported.

Deployments that expose Product discovery use the application API origin and a Product key via connection
protocol v2. In managed mode, use the same environment variables or `endpoint` and `apiKey` options with
the application API origin and Product key. Select the grants for the capabilities your application will use.
The Traces grant enables the managed exporter. For applications that supply their own provider, see
[external mode](https://docs.impact.ai/sdk/javascript/setup.md#use-your-opentelemetry-provider).
`startup: 'strict'` raises a discovery error. Best-effort startup returns a runtime in state `unavailable`,
with a content-free `status().diagnosis` so the application can continue. Invalid local configuration fails
before activation in either mode.

## Initialize before constructing clients

Ordinary imports are passive. Retain the handle returned by `await impact.init()`, then construct your native
clients. The OpenAI and Anthropic packages may be statically imported before `init()`. Google Gen AI also
requires post-initialization client construction. Google ADK gets its tracer during module evaluation, so follow
the [ADK startup recipe](https://docs.impact.ai/sdk/javascript/integrations.md#google-adk).

Use the returned runtime for `status()`, `flush()`, `shutdown()`, `registerSimulationTarget()`, `activateProtect()`,
`attachRealtime()` and `observeRealtime()`. Keep that handle at the application's startup/lifecycle boundary. Root
`context()`, `span()`, `wrap()` and `feedback()` enrich the current initialized runtime.

After a settled discovery failure, repair the connection and call `init()` explicitly with the intended settings.
This makes one bounded attempt and returns a new runtime. A previous unavailable handle still describes
its own attempt, and closing it leaves the recovered runtime running.

```js theme={null}
let runtime = await impact.init();
if (runtime.status().state === 'unavailable') {
  console.warn(runtime.status().diagnosis);
  // At a deliberate retry boundary after the connection has been repaired:
  runtime = await impact.init();
}
```

Equivalent concurrent initializations share one attempt, including callers selecting different startup policies. Strict
callers reject with `ProductConnectionError` for the same remote failure. Best-effort callers receive the unavailable
handle. `error.code` distinguishes `network`, `timeout`, `authorization`, `redirect`, `rejected` and `invalid-response`.
Optional capability errors distinguish authority conflicts and denied grants.

## Sampling and shutdown

Managed sampling supports `{ mode: 'all' }` (the default), `{ mode: 'none' }`, and
`{ mode: 'ratio', ratio: 0.1 }`. Ratios must be finite and between 0 and 1. Sampling applies to whole
operations through parent-aware sampling, except `none` disables sampling. Your provider controls sampling
when you supply a tracer or tracer provider.

At the application's completion boundary, drain application work, then call `await runtime.shutdown()`.
Use `await runtime.flush()` to attempt delivery of completed records without stopping capture. If shutdown
reports incomplete cleanup, retry it to continue the unfinished phases. Review local delivery and confirm
the matching [Product Trace](https://docs.impact.ai/sdk/javascript/troubleshooting.md).

## Use your OpenTelemetry provider

### Choose who owns capture and delivery

Managed mode uses `endpoint` and `apiKey`. Impact owns the private provider, processors, exporters and queues it
creates. It becomes the process-global OpenTelemetry owner only when no provider exists. Shutdown never closes a
customer provider, but replacing managed global telemetry in the same process requires a restart.

External mode accepts a customer `TracerProvider` or `Tracer` and never owns or flushes its provider:

```ts theme={null}
const runtime = await impact.init({
  serviceName: 'support-agent',
  tracerProvider: customerTracerProvider,
});
```

Maintained owners use the supplied tracer/provider. Native framework spans that independently obtain the
process-global provider, such as ADK's own spans, still follow that customer route. Verify its destination separately.

### Attach a destination managed by Impact

To route native spans and logs from a customer provider through Impact's bounded queues and lifecycle using the same
Product key, resolve the destination before constructing that provider. Pass the same
handle to `init`. Its connection is reused for explicit optional capabilities:

```ts theme={null}
const destination = await impact.createOtlpDestination({ connection: {} });
const tracerProvider = new TracerProvider({
  sampler: customerSampler,
  spanProcessors: [destination.spanProcessor, ...customerSpanProcessors],
});
const runtime = await impact.init({
  serviceName: 'support-agent',
  tracerProvider,
  destination,
});
```

For programmatic Product configuration, pass `connection: { endpoint, apiKey }`. For an existing direct OTLP route,
`createOtlpDestination({ endpoint, apiKey })` remains synchronous and requires an ingestion-only key. A customer provider
that already routes its own telemetry can use `init({ tracerProvider, connection: {} })` for optional Product
capabilities without creating an Impact destination. External mode with no explicit Product connection/destination
ignores ambient Product credentials and preserves its existing network-independent setup.

For an application using `@opentelemetry/sdk-node`, add `destination.spanProcessor` to its existing `NodeSDK`
constructor's `spanProcessors` in the same way. After `telemetry.start()`, use the public registered provider:

```js theme={null}
import { trace } from '@opentelemetry/api';

const runtime = await impact.init({ tracerProvider: trace.getTracerProvider(), destination });
```

The application retains its resource, HTTP instrumentation, existing processors and shutdown handler. Drain application
work before awaiting `runtime.shutdown()`. The customer can then continue exporting or stop its own telemetry.

### Route semantic logs

Managed mode has a private Impact logger provider for native semantic records. External mode uses the
`loggerProvider` you supply. When you supply only a prepared Impact destination, external mode creates a
private logger attached to that destination. With neither, external mode uses the global logger, whose
availability and delivery are unknown to Impact. Impact leaves the global logger registration and existing
customer log routes in place.

To use your own logger provider for the Impact destination, add `destination.logProcessor` through its
public constructor and pass the provider to `init`. Flush and stop that provider with the application's
other telemetry. Trace and log delivery are tracked separately. `runtime.tracerProvider` and
`runtime.loggerProvider` expose the selected routes for native framework registration.
`runtime.status().signalOwnership` identifies the owner of each signal.

A customer that registered an API 1.9 / SDK 2 provider before loading Impact must pass that actual provider
(or its API 1.9 public provider proxy) explicitly. API 1.10 cannot discover a provider registered through the
older global API. This explicit attachment preserves the customer destination. It does not make global discovery
across API versions available.

Supplying `tracerProvider` preserves native instrumentation scopes. A tracer-only attachment routes through that
tracer and retains its scope. Equivalent initialization compares supplied provider identities as well as settings.

Put the Impact processors before processors that mutate shared records. They are inert until `init` accepts the
handle. The customer retains its provider, sampler, context manager, processor order and other destinations.
`runtime.flush()`, `runtime.status()` and `runtime.shutdown()` own only the prepared Impact route. Impact shutdown
makes these processors inert and leaves the customer provider and its other destinations running. If initialization
will not be attempted, call `destination.shutdown()` to release its resources.

### Manage the destination yourself

To manage the destination in your application, use `DestinationSpanProcessor` and
`DestinationLogRecordProcessor` from `impact-ai/otel`. Place each Impact copy processor before any customer
processor that mutates shared records. These wrappers copy all sampled scopes, preserve the customer provider and
report their own cleanup failures. They do not choose a destination, add credentials or perform generic redaction.

Construct the Impact destination as `new DestinationSpanProcessor(new BatchSpanProcessor({ exporter: impactOtlpExporter }))`
and put it first in the customer provider's `spanProcessors`, followed by the customer's existing processors.
Configure `impactOtlpExporter` with the route's `/v1/traces` URL and Bearer ingest credential. Use the corresponding
log destination and `/v1/logs` exporter when the selected owner emits semantic content as logs. Keep the customer's
sampler and provider registration. The application owns these separately constructed destinations: flush them through
the customer provider, and call their `shutdown()` alongside `runtime.shutdown()` when stopping Impact alone.
The customer provider and its other destinations can continue running. Attach its tracer with `init({ tracer })`.
The runtime cannot discover independently constructed processors from a standalone tracer.

### Keep Langfuse or LangSmith

With Langfuse's native LangChain `CallbackHandler`, retain that callback and its `LangfuseSpanProcessor`, and set
`integrations: { langChain: 'disabled' }` in the external-tracer initialization. The Impact destination copies the
same native Langfuse span. With LangSmith's callback, retain Impact's `langChain: 'auto'`. LangSmith uses its own
HTTP client, while the maintained LangChain owner supplies the separate OpenTelemetry evidence for Impact.
Verify the same application operation in each destination, then check that customer telemetry continues when Impact stops.

## Deployment version and Source

Set the same actual deployment reference in the running application and in your Source CLI or IDE workflow.
`IMPACT_VERSION_ID` supplies the default reported deployed-version reference when `context.versionId` is absent. Its trimmed
value is shared by Trace context, Simulation target fallback and optional presence, so a deployment can align those
facts with the version synchronized by the Source CLI/IDE workflow:

```sh theme={null}
export IMPACT_VERSION_ID="$DEPLOYED_VERSION_REF"
export IMPACT_PRESENCE=true
node app.mjs
```

An explicit `init({ context: { versionId: '...' } })` wins. An unset or blank environment value remains unknown. The
SDK does not inspect Git, package manifests or source files to infer a version or run Source synchronization.

## Runtime presence

Hosted applications may opt into lightweight runtime presence with `init({ presence: true })` or
`IMPACT_PRESENCE=true`. Explicit `presence: true` or `false` takes precedence over the environment value, which must be
exactly `true` or `false`. Presence is off by default. When authenticated discovery supplies a presence endpoint, the
SDK sends a bounded process-runtime report immediately, about once per minute, and once during bounded shutdown. The
report contains only canonical discovered Product/Environment identity, runtime and SDK identity, service name and the
optional reported deployed-version reference. Its `productVersionId` field does not itself prove a canonical Builder
Version binding. It contains no captured content, integration state or Source files. A missing presence route
leaves capture running and reports `runtime.status().presence.outcome === 'unavailable'`. `recorded` means only that the latest
local POST returned HTTP 204. Presence does not prove Trace, Simulation, Protect, Source, process health or durable
Product readback. `flush()` does not wait for or send presence.

## Hosted route setup reports

Automatic setup reporting requires the complete route envelope supplied by Impact:
`IMPACT_SETUP_REPORT_ENDPOINT`, `IMPACT_SETUP_REPORT_API_KEY`, `IMPACT_ROUTE_ID`,
`IMPACT_ROUTE_REVISION` and `IMPACT_ENVIRONMENT_ID`. The developer still makes no additional SDK call. If that
envelope is absent, capture continues and `runtime.status().setupReport.outcome` is `not-configured`. A partially supplied
envelope rejects during initialization instead of guessing route ownership.
`IMPACT_ENVIRONMENT_ID` alone does not activate setup reporting or supply application context. Pass application
environment meaning explicitly with `context: { environment: '...' }`.


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