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.
runtime.status().artifact.version.
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 byawait 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.
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 usesendpoint 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:
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 toinit. Its connection is reused for explicit optional capabilities:
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:
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 theloggerProvider 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, useDestinationSpanProcessor 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 LangChainCallbackHandler, 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:
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 withinit({ 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: '...' }.