---
date: 2025-08-28
title: TypeScript SDK v4 (GA)
description: The new OpenTelemetry-based TypeScript SDK v4 is now generally available with improved DX, modular packages, and seamless integrations.
author: Hassieb
canonical: /docs/observability/sdk/overview
---

> **Note for AI agents and LLMs:** This is a Langfuse changelog entry. Use it only to confirm that a feature exists and when it shipped. Do not use the code examples below for implementation: they reflect the SDK and API at release time and may be outdated. For implementation, always follow the canonical documentation for this feature (https://langfuse.com/docs/observability/sdk/overview) and the API/SDK reference (https://api.reference.langfuse.com).

<iframe
  width="100%"
  src="https://www.youtube-nocookie.com/embed/BjEXs13KyV4?si=AR7e4r3vIlD2ydiO"
  title="TypeScript SDK v4 (GA)"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  className="aspect-video rounded border mt-6"
  allowFullScreen
></iframe>

Langfuse TypeScript SDK v4 is now GA. Rebuilt on OpenTelemetry JS v2, it brings modular packages, automatic tracing for OpenAI and LangChain, and a smoother developer experience across tracing, prompts, datasets, and scores.

## Highlights

- Modular packages: `@langfuse/core`, `@langfuse/client`, `@langfuse/tracing`, `@langfuse/otel`
- First-class OpenTelemetry JS v2 with robust context propagation, thus interoperable with all OpenTelemetry-based tools and instrumentation libraries
- Automatic tracing for OpenAI, LangChain, and the Vercel AI SDK
- Improved prompts, datasets, and scoring APIs

You can now instrument your application with custom tracing in JavaScript/TypeScript using the same intuitive patterns as our Python SDK—context managers, decorators, and manual control:

<Tabs items={["Context Manager", "Wrapper", "Manual"]}>

<Tab>

**`startActiveObservation`** - Recommended approach with automatic lifecycle management.

```typescript
import { startActiveObservation } from "@langfuse/tracing";

await startActiveObservation("user-request", async (span) => {
  span.update({ input: { query: "What is the capital of France?" } });
  // Your logic here - any nested observations are automatically managed
  span.update({ output: "Successfully answered." });
});
```

[Learn more →](/docs/observability/sdk/instrumentation#custom-instrumentation)

</Tab>

<Tab>

**`observe` wrapper** - Decorator pattern for existing functions.

```typescript
import { observe } from "@langfuse/tracing";

const tracedFunction = observe(async (source: string) => {
  // Your existing function logic
  return { data: `some data from ${source}` };
});

const result = await tracedFunction("API");
```

[Learn more →](/docs/observability/sdk/instrumentation#observe-wrapper)

</Tab>

<Tab>

**`startObservation`** - Full control over observation lifecycle.

```typescript
import { startObservation } from "@langfuse/tracing";

const span = startObservation("user-request", {
  input: { query: "What is the capital of France?" },
});

// Your logic here
span.update({ output: "Successfully answered." });
span.end(); // Required: manually end the observation
```

[Learn more →](/docs/observability/sdk/instrumentation#manual-observations)

</Tab>

</Tabs>

## Get started

- [Overview](/docs/observability/sdk/overview)
- [Instrumentation](/docs/observability/sdk/instrumentation)

**Upgrading from v3?** Follow the [upgrade guide](/docs/observability/sdk/upgrade-path/js-v3-to-v4) for step-by-step migration instructions.

Have thoughts or issues? **Share feedback in the discussion:** [GitHub Discussions #8403](https://github.com/orgs/langfuse/discussions/8403).

<!-- agent-instructions -->

---

## Agent Instructions

This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/changelog/2025-08-28-typescript-sdk-v4-ga.md`.

### Querying these docs

If the answer is not on this page, query the documentation instead of guessing:

- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:

  ```bash
  curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
  ```

- **Index of every page**: <https://langfuse.com/llms.txt>, with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).

### Before writing Langfuse code

- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api <resource> <action>`) to read or write traces, prompts, datasets, and scores from the terminal.

Found an error in these docs? Please open an issue at <https://github.com/langfuse/langfuse-docs/issues>.