TypeScript SDK - Overview

Install packages

Install the relevant packages to get started with tracing:

npm install @langfuse/tracing @langfuse/otel @opentelemetry/sdk-node

Learn more about the packages here.

Set up environment variables

Add your Langfuse credentials to your environment variables. Make sure that you have a .env file in your project root and a package like dotenv to load the variables.

LANGFUSE_SECRET_KEY = "sk-lf-..."
LANGFUSE_PUBLIC_KEY = "pk-lf-..."
LANGFUSE_BASE_URL = "https://cloud.langfuse.com" # 🇪🇺 EU region
# LANGFUSE_BASE_URL = "https://us.cloud.langfuse.com" # 🇺🇸 US region

Set up OpenTelemetry

Create a file named instrumentation.ts to initialize the OpenTelemetry SDK. The LangfuseSpanProcessor is the key component that sends traces to Langfuse.

import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";
 
const sdk = new NodeSDK({
  spanProcessors: [new LangfuseSpanProcessor()],
});
 
sdk.start();

Import the instrumentation.ts file at the very top of your application’s entry point (e.g., index.ts).

import "./instrumentation"; // Must be the first import

Learn more about setting up OpenTelemetry here.

Instrument your application

Use one of the native Langfuse framework integrations to automatically trace your application.

Alternatively, manually instrument your application, e.g. by using the startActiveObservation. This function takes a callback and automatically manages the observation’s lifecycle and the OpenTelemetry context. Any observation created inside the callback will automatically be nested under the active observation, and the observation will be ended when the callback finishes.

This is just an example, check out the instrumentation page for more details.

import "./instrumentation";
import { startActiveObservation } from "@langfuse/tracing";
 
async function main() {
  await startActiveObservation("my-first-trace", async (span) => {
    span.update({
      input: "Hello, Langfuse!",
      output: "This is my first trace!",
    });
  });
}
 
main();

Run your application

Execute your application. You should see your trace appear in the Langfuse UI.

npx tsx index.ts