Unable to see first trace by following quickstart

[kleenkanteen]

Describe your question

Very frustrating. I am on a m2 mac mini and on the latest mac os version.

I followed https://langfuse.com/docs/observability/sdk/overview for the ts sdk. I copied over the code and when running it seems to work, but then when I check langfuse, I see nothing.

I have copied over the .env secrets it gave me on the page https://us.cloud.langfuse.com/project/cmjizmh2d02zoad0765an7jg1/traces/setup, when I click "Create new API key". Here is a redacted version of them:

LANGFUSE_SECRET_KEY = "sk-lf-{redacted}"
LANGFUSE_PUBLIC_KEY = "pk-lf-{redacted}"
LANGFUSE_BASE_URL = "https://us.cloud.langfuse.com"

Here is my code in index.ts:

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();

And my code in instrumentation.ts:

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

Notice I added the line import dotenv from "dotenv"; and dotenv.config(); because without these, the secrets of in the env are not loaded. I ran the file with npx tsx index.ts and this is the output:

I have ran npm install @langfuse/tracing @langfuse/otel @opentelemetry/sdk-node, they show up in package.json.

I've deleted all dependencies except for what's needed for the quickstart, this is my package.json dependencies:

  "dependencies": {
    "@langfuse/otel": "^4.5.1",
    "@langfuse/tracing": "^4.5.1",
    "@opentelemetry/sdk-node": "^0.208.0",
    "dotenv": "^17.2.3"
  },

Cannot figure out why my home dashboard still looks like this:

Tracing page is similarly empty.

node version: v22.20.0
npm version: 10.9.3

I have even created a new folder, copied over all my files, npm installed everything again and ran it to the same result.

Langfuse Cloud or Self-Hosted?

Langfuse Cloud

If Langfuse Cloud

https://us.cloud.langfuse.com/project/cmjizmh2d02zoad0765an7jg1

• I have checked for existing issues/discussions and consulted Langfuse AI.

[inkeep-ai-assistant[bot]]

(1)

The issue is likely that your short-lived application exits before the trace data is sent to Langfuse. The JS/TS SDK sends data asynchronously in the background.(1)

For short-lived applications like your script, you need to ensure the SDK has time to flush the data before the process exits. Add a shutdown handler to your index.ts:(1)

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();

Then update your instrumentation.ts to properly handle shutdown:(1)

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

The key issue is that the OpenTelemetry SDK needs to be properly shut down to ensure all spans are exported before the process exits. Since your script completes almost instantly, it exits before the background export happens.(1)

Add a shutdown call after your main function completes:

import "./instrumentation";
import { startActiveObservation } from "@langfuse/tracing";
import { opentelemetry } from "@opentelemetry/api";
 
async function main() {
  await startActiveObservation("my-first-trace", async (span) => {
    span.update({
      input: "Hello, Langfuse!",
      output: "This is my first trace!",
    });
  });
  
  // Give the SDK time to flush
  await new Promise(resolve => setTimeout(resolve, 2000));
}
 
main().then(() => process.exit(0));

This gives the SDK 2 seconds to export the trace data before the process exits. After making this change, you should see your trace appear in the Langfuse UI.(1)

📚 Sources:

1. Get Started with Tracing

---

Have another question? Just tag @inkeep.

[kleenkanteen]

does not fix it

[Lotte-Verheyden]

Hi @kleenkanteen,

The issue is that your application exits before the traces are sent to Langfuse. You can find more on this here: https://langfuse.com/docs/observability/data-model#short-lived-applications

You can fix this by explicitly telling the OpenTelemetry SDK to flush all pending spans and wait for them to be sent, before exiting the application:

In your instrumentation.ts file, export the SDK so that you can use it in index.ts:

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

sdk.start();

Import and shut down the SDK after your main function completes:

import { sdk } from "./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().finally(() => sdk.shutdown());

Using .finally() ensures the SDK shuts down and flushes regardless of whether main() succeeds or throws an error.

[kleenkanteen]

after adding main().finally(() => sdk.shutdown()); it finally worked my god. you should add that to the quickstart docs.

edit: saw that you did. hopefully that will save the next person from my pain

[Lotte-Verheyden]

Yes, good catch in our docs. Thank you for raising this :)