inngest-js

The @inngest/otel package provides turnkey OpenTelemetry instrumentation helpers for Inngest. It is designed to automatically install supported instrumentations before your application code starts, making it a low-effort way to set up Node.js OpenTelemetry.

While this package is recommended for a quick setup, you can still configure OpenTelemetry manually if you require direct control over providers, exporters, sampling, resources, or specific instrumentation lists.

The core inngest SDK includes a built-in realtime implementation. You can find various implementation patterns in the following example directories:

• Next.js Hooks: Using realtime features with React hooks in a Next.js environment (next-realtime-hooks).
• Background Jobs with Realtime: Synchronizing background job progress or status with a Next.js frontend (nextjs-bg-jobs-realtime).
• Multi-channel Realtime: Managing realtime communication across multiple distinct channels (realtime-across-multiple-channels).
• Human-in-the-loop: Implementing workflows that require real-time user interaction or approval (realtime-human-in-the-loop).
• Single-run Subscriptions: Subscribing to updates for a specific, individual function run (single-run-subscription).

The @inngest/ai package provides type-safe adapters for the following providers:

• OpenAI: GPT models and embeddings
• Anthropic: Claude models
• Google Gemini: Gemini models (including thinking features)
• Grok: Grok models (OpenAI-compatible)
• Azure OpenAI: Azure-hosted OpenAI models

The Next.js starter project provides an interactive tour of several core Inngest capabilities:

• Triggering Functions: Learn how to trigger an Inngest function and observe its output.
• Multi-Step Functions and Streaming: See how functions can be divided into fault-tolerant steps and how to stream updates directly to a UI.
• Fault Tolerance with Retries: Observe how Inngest handles failures and manages retries using a function designed to fail intentionally.
• Flow Control (Throttling): Learn how to use throttling to control function execution, which is useful for handling rate limits on 3rd party APIs.

All demo function logic is located in src/lib/demo-functions.ts.

Beyond encrypting step state, you can also encrypt all incoming event data using a full encryption middleware approach. This ensures that the payload of the event triggering the function is also protected.

Important Operational Warnings:

• Feature Limitations: Encrypting event data disables Inngest features that rely on inspecting event payloads, such as using expressions with step.waitForEvent() or browsing event data in the Inngest dashboard.
• System Integration: Event data is often shared between different systems. Consider whether encrypting the event data at the source is appropriate for your architecture.

When used as a preload, @inngest/otel automatically registers the following instrumentations:

• Common Node.js library instrumentation (via @opentelemetry/auto-instrumentations-node)
• OpenAI instrumentation (via @traceloop/instrumentation-openai)
• Anthropic instrumentation (via @traceloop/instrumentation-anthropic)
• Google Generative AI instrumentation (via @traceloop/instrumentation-google-generativeai)

Note: @google/genai v2 is not currently supported by the Traceloop Google Generative AI instrumentation.

Because the SDK's Logger instance is not serializable across the worker thread boundary and is bound to the main thread's Inngest client, the worker thread uses a message-passing pattern for logging:

1. Creation: runner.ts creates a lightweight, logger-compatible object using createMessageLogger().
2. Parsing: Log calls are processed by parsePinoArgs() to convert them into a { message, data? } format. This supports both pino-style (object, string) and simple (string) signatures.
3. Transmission: The parsed log is sent to the main thread as a LOG message (defined as WorkerToMainMessage in protocol.ts).
4. Execution: The main thread receives the message via handleWorkerLog() in index.ts and executes the actual logging call using the real logger.

Use defer when you need to trigger a specific, typed function independently without waiting for its result. Unlike step.invoke, which blocks the caller until the result is returned, defer is synchronous and fire-and-forget.

Comparison of execution tools

Durable Endpoints solve the problem of HTTP request timeouts when executing long-running workflows.

The Lifecycle:

1. A request is made to an endpoint wrapped with inngest.endpoint().
2. If the request takes longer than the sync timeout, the endpoint redirects the client to a proxy endpoint.
3. The proxy endpoint (created via inngest.endpointProxy()) fetches the result from Inngest.
4. If E2E encryption is enabled, the proxy handles decryption before returning the final result to the user.

When deciding how to implement workflows, use the following comparison to choose between traditional Inngest functions and the new Durable Endpoints:

Durable Endpoint (DE) Streaming allows you to stream arbitrary data (such as LLM outputs) to a client via Server-Sent Events (SSE).

Execution Modes

• Sync Mode: If the request includes the Accept: text/event-stream header, the DE returns an SSE response immediately. The function continues executing steps in the background.
• Async Mode: After an asynchronous operation (like step.sleep), the DE switches to streaming data to the Inngest Server (IS). The IS then relays this data to the client via a redirect URL.

Reconnection Logic

When switching to async mode, the client receives an inngest.redirect_info event containing a URL. Once the initial direct stream ends, the client reconnects to that specific URL to receive the remaining events.

The Worker Thread strategy is designed to prevent CPU-intensive userland function execution from blocking critical connection health checks.

It achieves this by offloading the following tasks to a separate Node.js worker thread (runner.ts):

• WebSocket connection management
• Heartbeater execution
• Lease extender execution

Userland function execution (your actual business logic) continues to run on the main thread. This separation ensures that even if your code is performing heavy computations, the connection to Inngest remains stable.