🚀 Langfuse TypeScript SDK v4 is here

[hassiebp]

🚀 Langfuse TypeScript SDK v4 is here!

We’ve rebuilt the JS SDK on top of OpenTelemetry — unlocking better developer experience, robust context management, and seamless integrations with tools like OpenAI, LangChain, and more.

📚 Docs
📖 SDK Reference

Highlights:

• Modular packages (@langfuse/core, @langfuse/client, @langfuse/tracing, etc.)
• First-class OpenTelemetry support
• Automatic tracing for OpenAI + LangChain
• Manual & callback-based tracing APIs
• Improved scoring, dataset, and prompt APIs

Installation

npm install @langfuse/core @langfuse/client @langfuse/tracing @langfuse/otel

We’d love your feedback — please share thoughts, issues, and ideas in this discussion thread.

[nneven]

Hi, I'm trying to upgrade from the previous version (which was working but had some issues) to v4 beta in my Next.js app. I can get the standalone SDK working perfectly (spans appear in dashboard), but when using LangfuseSpanProcessor with Vercel's registerOTel in instrumentation.ts, the spans are processed locally (visible in debug logs) but never appear in the Langfuse dashboard.

// Working (standalone):
import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";

const sdk = new NodeSDK({
  spanProcessors: [new LangfuseSpanProcessor()],
});
sdk.start();

// Not working (Next.js):
// instrumentation.ts
import { registerOTel } from "@vercel/otel";
import { LangfuseSpanProcessor } from "@langfuse/otel";

export async function register() {
  registerOTel({
    serviceName: "my-app",
    spanProcessors: [new LangfuseSpanProcessor()],
  });
}

Do you have a confirmed working example with Next.js + Vercel OTEL?

My packages: @langfuse/otel@4.0.0-beta.2, @vercel/otel@1.13.0, Next.js 14.2.30

[hassiebp]

@nneven thanks for trying it out and letting us know your feedback! The v4-beta is not compatible with @vercel/otel as @vercel/otel does not support OpenTelemetry JS v2 yet that we depend on: vercel/otel#154

Please use a plain OpenTelemetry setup via the NodeSDK as shown in our documentation in your instrumentation.ts for OTEL spans to be exported correctly.

Please let me know if I should provide more detail, here's a side project of mine that uses nextJS and has the correct setup: https://github.com/hassiebp/yttldr/blob/main/src/instrumentation.ts

[nneven]

Hi @hassiebp thanks so much I tried this and got much farther trying to make it work. I notice that you filter out all Next.js spans, which makes sense, const shouldExportSpan: ShouldExportSpan = ({ otelSpan }) => otelSpan.instrumentationScope.name !== "next.js";, this ends up having a null/orphaned parent trace which is created by next.js API route and the AI SDK spans lives under it, as mentioned in the docs. How can I set the ai.streamText parentSpanId to not live under the null/orphaned root trace created by the API route?

[hassiebp]

@nneven I'll add that functionality here: #8561

[hassiebp]

Link to full docs example

[AndrewIngram]

The switch from automatically filtering out all non-AI spans in the previous (exporter-based) version to having to manually set this up in each span processor is pretty significant. As we already have an otel infra (we use it for things other than our AI endpoints), a naive upgrade to this basically switches on the firehose of every trace and every span -- something we absolutely can't have with the kind of information we have in our traces.

The span-based approach does make integration easier (we previously had to hack together an exporter wrapper that sent things to multiple sub-exporters), but it does make things riskier, especially with the warning about filterings spans breaking the structure of traces.

[hassiebp]

Thanks for your feedback @AndrewIngram ! We recommend using the shouldExportSpan predicate for better control on what spans you'd like to exclude from being exported to Langfuse. Upgrading from the AI SDK, you should not see new issues by this approach as the previous LangfuseExporter applied a similar logic under the hood.

https://langfuse-docs-git-add-js-sdk-v4-docs-langfuse.vercel.app/docs/observability/sdk/typescript/advanced-usage#filtering-spans

[hassiebp]

Link to full docs example

[AndrewIngram]

Recommending filtering feels at odds with the scary warning about broken traces at that section of the docs. My push here is to make it clear how to maintain the traces they had in previous versions. I had to do two things:

1. Filter out all spans which didn't start with ai.
2. Wrap the actual ai sdk call with a new root span and link it back to the parent trace (for the purposes of keeping it usable in Honeycomb). This is because filtering out the actual root span (an express http handler) meant that the trace no longer had a name -- it plucks the name from the root span, which was missing.

In the previous version, the root of the traces in langfuse was the top-level ai sdk call (e.g ai.streamText) rather than the root span of the actual otel trace (something like POST /ai/)

[hassiebp]

Thanks, @AndrewIngram ! Could you please share how exactly you did this:

Wrap the actual ai sdk call with a new root span and link it back to the parent trace (for the purposes of keeping it usable in Honeycomb). This is because filtering out the actual root span (an express http handler) meant that the trace no longer had a name -- it plucks the name from the root span, which was missing.

I'd love to document this for other users running into the same issue

[DarryQueen]

This is working for us, but I do notice a runtime warning for media files in NextJS:

2025-08-21T19:38:01.967Z [Langfuse SDK] [WARN] Crypto module not available. Media handling will be disabled. Error: dynamic usage of require is not supported
    at [project]/src/instrumentation.ts [instrumentation] (ecmascript) (src/instrumentation.ts:1:0)
    at Object.<anonymous> (.next/server/instrumentation.js:14:9)
> 1 | import { LangfuseSpanProcessor } from "@langfuse/otel";
  2 | import { NodeSDK } from "@opentelemetry/sdk-node";
  3 | import { compact } from "lodash";
  4 |
2025-08-21T19:38:02.023Z [Langfuse SDK] [WARN] [Langfuse] Crypto module not available in this runtime. Media upload functionality will be disabled. Spans will still be processed normally, but any media content in base64 data URIs will not be uploaded to Langfuse.

Would be great if you could update https://github.com/langfuse/langfuse-vercel-ai-nextjs-example. I'm guessing it'll be pretty easy to put up a repro.

[hassiebp]

Thanks for your feedback, @DarryQueen!

Here's a full docs example for the AI SDK integration: Link to full docs example

[hassiebp]

As for the crypto warnings, will be tackled here: #8681

[hassiebp]

Resolved in https://github.com/langfuse/langfuse-js/releases/tag/v4.0.0-beta.6

[kylegwalsh]

@hassiebp Is there an example of using the Vercel AI SDK with the generateText / generateObject methods (rather than the streamText method)? I'm guessing that we should be able to get open telemetry spans directly in Langfuse without having to call updateActiveObservation() everywhere?

[hassiebp]

@kylegwalsh - using generateText and generateObject should work the same way as with streamText. Since you are not streaming responses, you will not need to set the endOnExit flag to false and manually close the span.

However, if you have a parent span configured and or you are filtering out nextJS infra spans, you'll need to manually set the input / output / tracename as shown in the example: https://langfuse-docs-git-add-js-sdk-v4-docs-langfuse.vercel.app/docs/observability/sdk/typescript/instrumentation#vercel-ai-sdk

[hassiebp]

Thanks everybody for your feedback! The JS SDK v4 is now generally available 🚀

• Changelog
• Docs
• Upgrade path

[neo]

I'm a bit confused with the new tracing approach about the absence of the "root" trace, which is usually where the user/session id and "root" trace name is being set.
Now if I have a "global/root" observation and have everything be the children of that, then my trace "hierarchy" tree will show it twice from the top being both the "root" trace and the "span" inside the trace with the same name, which seems redundant to me.

[ronald-das]

Yeah, I have migrated to the v4 sdk, and also using the vercel ai sdk v5 (as mentioned in https://langfuse-docs-git-add-js-sdk-v4-docs-langfuse.vercel.app/docs/observability/sdk/typescript/instrumentation#vercel-ai-sdk ), but now my top level root span has no name, input , outputs

[AndrewIngram]

This is the problem I had because I was filtering out the root span of my trace. I had to start a new linked trace that wrapped my AI sdk operation to get a suitable unfiltered root span.

I think it'd make sense for Langfuse to get the name from the topmost unfiltered span, rather than the root (even if they're often the same).

[hassiebp]

Yeah, I have migrated to the v4 sdk, and also using the vercel ai sdk v5 (as mentioned in https://langfuse-docs-git-add-js-sdk-v4-docs-langfuse.vercel.app/docs/observability/sdk/typescript/instrumentation#vercel-ai-sdk ), but now my top level root span has no name, input , outputs

Please see here for a full example with the Vercel AI SDK.

Langfuse is populating the trace name / input / output with data from the root OTEL span. If the root span is filtered out, they remain blank (as our backend cannot tell whether it has yet to arrive). So in those cases, a manual update of the trace name / input / output is recommended as shown in the example.

[neo]

so is there a way I could customize the root span without duplicating with the outermost span?

[nneven]

Hi, are there known compatibility issues with Sentry? I recall seeing that in old docs. If Sentry is enabled I do not see traces in Langfuse.

[max-ae]

When manually setting up Sentry components, I am back at zero with unrelated stuff showing up in Langfuse, broken input, output etc. just like @nneven describes as well

[hassiebp]

@max-ae @nneven We have updated our docs with instructions, could you please let us know whether this worked for you? https://langfuse.com/docs/observability/sdk/typescript/advanced-usage#setup-with-sentry

[ronald-das]

@max-ae @nneven We have updated our docs with instructions, could you please let us know whether this worked for you? https://langfuse.com/docs/observability/sdk/typescript/advanced-usage#setup-with-sentry

this worked for me. and using custom filtering via shouldExportSpan removed any databse or http trace data

[hassiebp]

@ronald-das thanks for letting us know! 🙏🏾

[SiKreuz]

I still have a similar issue which I don't get fixed with either of the two methods presented in the docs. I opened another discussion yesterday. Any help is welcome https://github.com/orgs/langfuse/discussions/11722#discussioncomment-15607411

[ManuLpz4]

@hassiebp we followed the steps to setup the new LangfuseSpanProcessor with the Vercel AI SDK but we are not receiving the reasoning parts. Do you know what the issue could be?

We also see the columns in white

[hassiebp]

Could you please share a link to a trace here? what exactly do you mean by only the reasoning parts are missing?

[shehroze-1122]

Hi team, we have an existing otel backend setup with signoz. Our current simplified setup looks like this:

diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);

const resource = detectResources({
  detectors: [awsEcsDetector, containerDetector, envDetector, processDetector],
});


const metricExporter = new OTLPMetricExporter({
  url: `${endpoint}/v1/metrics`,
  headers: {
    ...
  },
});

const meterProvider = new MeterProvider({
  resource,
  readers: [
    new PeriodicExportingMetricReader({
      exporter: metricExporter,
      exportIntervalMillis: 10000,
    }),
  ],
});

metrics.setGlobalMeterProvider(meterProvider);

// Debug: Log BullMQ Pro instrumentation creation
const bullMQInstrumentation = new BullMQProInstrumentation({
  useProducerSpanAsConsumerParent: true,
  emitCreateSpansForBulk: false,
});

const sdk = new NodeSDK({
  resource,
  traceExporter: new OTLPTraceExporter({
    url: `${endpoint}/v1/traces`,
    ...
  }),
  instrumentations: [
    new HttpInstrumentation({
      requireParentforOutgoingSpans: true,
      ignoreIncomingRequestHook: (req) => {
        return req.url?.includes('/health') || false;
      },
    }),
    new UndiciInstrumentation({
      requireParentforSpans: true,
      responseHook: (span, { request }) => {
        if (request.headers) {
          ...
          if (
            headers.some(([key]) => key && key.toLowerCase() === 'x-webhook-id')
          ) {
            span.setStatus({ code: SpanStatusCode.OK });
          }
        }
      },
    }),
    bullMQInstrumentation,
    new IORedisInstrumentation(),
    new RuntimeNodeInstrumentation({
      monitoringPrecision: 5000,
    }),
  ],
});

sdk.start();

We are currently looking for a good way to make this version upgrade while keeping things working on Langfuse side and also keep traces between Langfuse and signoz isolated. I have read the isolated TraceProcessor guide in the docs but a huge warning regarding the setup resulting in orphan children is what keeping us from making the move.

[msalafia]

@hassiebp why did the enabled params disappear from the contructor argument props for CallbackHandler in @langfuse/langchain? I was able to do something like this in v3 now i cannot:

new LangfuseCallbackHandler({
              // 'enabled' does not exist anymore
              enabled: this.configService.get<boolean>(
                "LANGFUSE_TRACING_ENABLED",
              ),
              sessionId: ...,
              userId: ...,
              environment: this.configService.get("ENVIRONMENT")!,
              tags: ...,
              metadata: ...,
            }),

that property was very important, what happened?

[hassiebp]

@msalafia Passing enabled is no longer supported in our latest SDK versions. What is your exact use case? In order to disable trace exports in your specific environment, you can simply skip the registration of the LangfuseSpanProcessor. In OpenTelemetry, instrumentations such as the CallbackHandler we implemented are noops if no OpenTelemetry TracerProvider is registered

[msalafia]

ok thank you, i just wanted to be sure this is the new intended way.