Skip to main content
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.
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.
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.

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

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:
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:
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:
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:
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: '...' }.