Latitude Telemetry for TypeScript

Instrument your AI application and send traces to Latitude. Built on OpenTelemetry.

Installation

npm install @latitude-data/telemetry

Quick Start

Bootstrap (Recommended)

The fastest way to start tracing your LLM calls. One class sets up everything:

import OpenAI from "openai";
import { Latitude } from "@latitude-data/telemetry";

const client = new OpenAI();

const latitude = new Latitude({
  apiKey: process.env.LATITUDE_API_KEY!,
  project: process.env.LATITUDE_PROJECT_SLUG!,
  instrumentations: { openai: OpenAI }, // Pass the LLM SDK module you use in app code.
});

// Optionally wait for instrumentations to be ready
await latitude.ready;

// Your LLM calls will now be traced and sent to Latitude
const response = await client.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Hello" }],
});

await latitude.shutdown();

What this does:

• Detects an existing OpenTelemetry provider (Sentry, Datadog, New Relic, Honeycomb, etc.) and adds Latitude to it when possible
• Creates a complete OpenTelemetry setup when your app does not already have one
• Registers LLM auto-instrumentation (OpenAI, Anthropic, etc.) asynchronously in the background
• Configures the Latitude span processor and exporter
• Sets up async context propagation (for passing context through async operations) when Latitude owns the OTel setup

Key point about async instrumentations:

new Latitude() returns immediately — no top-level await needed. Instrumentation registration happens in the background. This avoids top-level await issues in CommonJS environments while still supporting ESM.

• Fire-and-forget: Start using your LLM clients right away. Early spans will be captured once instrumentations finish registering.
• Optional await latitude.ready: If you want to ensure instrumentations are fully registered before making LLM calls, await the ready promise.

When to use this: Most applications should start here. If you already initialize Sentry or another tracing SDK, initialize it first and construct new Latitude() second. Latitude will reuse the existing tracing pipeline when possible, and latitude.shutdown() only shuts down Latitude-owned processing.

When you might need the advanced setup:

• You need custom span processing, sampling, or filtering
• You want to wire span processors explicitly instead of letting new Latitude() detect your provider

Existing Sentry or OpenTelemetry Setup

If your app already uses Sentry or another OpenTelemetry-compatible SDK, initialize that SDK first and then construct new Latitude():

import OpenAI from "openai";
import * as Sentry from "@sentry/node";
import { Latitude } from "@latitude-data/telemetry";

Sentry.init({
  dsn: process.env.SENTRY_DSN!,
  tracesSampleRate: 1.0,
});

const latitude = new Latitude({
  apiKey: process.env.LATITUDE_API_KEY!,
  project: process.env.LATITUDE_PROJECT_SLUG!,
  instrumentations: { openai: OpenAI },
});

await latitude.ready;

// LLM spans are exported to both Sentry (via its provider) and Latitude.
await latitude.flush();
await latitude.shutdown(); // Does not shut down Sentry.

For fully custom OTel setups, you can also wire the Latitude processor explicitly:

import OpenAI from "openai";
import { NodeSDK } from "@opentelemetry/sdk-node";
import {
  LatitudeSpanProcessor,
  registerLatitudeInstrumentations,
} from "@latitude-data/telemetry";

const sdk = new NodeSDK({
  spanProcessors: [
    existingProcessor, // Your existing processor
    new LatitudeSpanProcessor(
      process.env.LATITUDE_API_KEY!,
      process.env.LATITUDE_PROJECT_SLUG!,
    ),
  ],
});

sdk.start();

// Enable LLM auto-instrumentation
await registerLatitudeInstrumentations({
  instrumentations: { openai: OpenAI },
  tracerProvider: sdk.getTracerProvider(),
});

// Your LLM calls will now be traced and sent to Latitude
const client = new OpenAI();
const response = await client.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Hello" }],
});

Why OpenTelemetry?

Latitude Telemetry is built entirely on OpenTelemetry standards. When you're ready to add other observability tools (Datadog, Sentry, Jaeger, etc.), you can use them alongside Latitude without conflicts:

• Standard span processors — LatitudeSpanProcessor works with any NodeSDK or NodeTracerProvider
• Smart filtering — Only LLM-relevant spans are exported to Latitude (spans with gen_ai.*, llm.*, openinference.*, or ai.* attributes, plus known LLM instrumentation scopes)
• Compatible with existing instrumentations — Works alongside HTTP, DB, and other OTel instrumentations
• No vendor lock-in — Standard OTLP export, no proprietary wire format

Using capture() for Context and Boundaries

The SDK automatically traces LLM calls when you use auto-instrumentation. However, you may want to add additional context (user ID, session ID, tags, or metadata) to group related spans together.

What capture() Does

capture() wraps your code to attach Latitude context to all LLM spans created inside the callback:

• Adds attributes like user.id, session.id, latitude.tags, and latitude.metadata to every span
• Creates a named boundary for grouping related traces
• Uses OpenTelemetry's native context.with() for reliable async propagation

When to Use It

You don't need capture() to get started—auto-instrumentation handles LLM calls automatically. Use capture() when you want to:

• Group traces by user or session — Track all LLM calls from a specific user or session
• Add business context — Tag traces with deployment environment, feature flags, or request IDs
• Mark agent boundaries — Wrap an entire agent run or conversation turn with a name and metadata
• Filter and analyze — Use tags and metadata to filter traces in the Latitude

Example

import OpenAI from "openai";
import { Latitude, capture } from "@latitude-data/telemetry";

const latitude = new Latitude({
  apiKey: process.env.LATITUDE_API_KEY!,
  project: process.env.LATITUDE_PROJECT_SLUG!,
  instrumentations: { openai: OpenAI },
});

// Optional: wait for instrumentations before starting
await latitude.ready;

// Wrap a request or agent run to add context
await capture(
  "handle-user-request",
  async () => {
    const result = await agent.process(userMessage);
    return result;
  },
  {
    userId: "user_123",
    sessionId: "session_abc",
    tags: ["production", "v2-agent"],
    metadata: { requestId: "req-xyz", featureFlag: "new-prompt" },
  },
);

await latitude.shutdown();

Important: capture() does not create spans—it only attaches context to spans created by auto-instrumentation. Use one capture() call at the request or agent boundary. You can nest calls for granular context; child spans inherit from parent context with local overrides.

Key Concepts

• new Latitude() — The primary way to use Latitude. Bootstraps a complete OpenTelemetry setup with LLM auto-instrumentation and the Latitude exporter. Best for most applications.
• LatitudeSpanProcessor — For advanced use cases where you already have an OpenTelemetry setup. Exports spans to Latitude alongside your existing observability stack.
• registerLatitudeInstrumentations() — Registers LLM auto-instrumentations (OpenAI, Anthropic, etc.) when using the advanced setup with your own provider.
• capture() — Optional. Wraps your code to attach Latitude context (tags, userId, sessionId, metadata) to all spans created inside the callback. Use this when you want to group traces by user, session, or add business context.

Important: Auto-instrumentation traces LLM calls without capture(). Use capture() only when you need to add context or mark boundaries. Wrap the request, job, or agent entrypoint once—you don't need to wrap every internal step.

Public API

import {
  Latitude,
  LatitudeSpanProcessor,
  capture,
  registerLatitudeInstrumentations,
} from "@latitude-data/telemetry";

new Latitude(options)

The primary entry point. Bootstraps a complete OpenTelemetry setup with LLM instrumentations and Latitude export.

type LatitudeOptions = {
  apiKey: string;
  /**
   * Default project slug for spans. Optional — every `capture()` can override.
   * Sent as the `X-Latitude-Project` header on every export.
   */
  project?: string;
  /**
   * @deprecated Renamed to `project`. Still accepted for backwards compatibility
   * and will be removed in a future release. When both are set, `project` wins.
   */
  projectSlug?: string;
  // Map of integration name → LLM SDK module the consumer imports.
  // Anything else (string array, unknown key, non-object) throws at register time.
  instrumentations?: InstrumentationsInput;
  serviceName?: string;
  disableBatch?: boolean;
  disableSmartFilter?: boolean;
  shouldExportSpan?: (span: ReadableSpan) => boolean;
  blockedInstrumentationScopes?: string[];
  disableRedact?: boolean;
  redact?: RedactSpanProcessorOptions;
  exporter?: SpanExporter;
  tracerProvider?: TracerProvider; // Optional explicit provider for Sentry/Datadog/New Relic/Honeycomb/custom OTel
};

class Latitude {
  constructor(options: LatitudeOptions);
  provider: TracerProvider; // Existing provider when detected, otherwise Latitude's NodeTracerProvider
  ready: Promise<void>; // Resolves when instrumentations are registered
  flush(): Promise<void>;
  shutdown(): Promise<void>;
}

LatitudeSpanProcessor

Span processor for shared-provider setups. Reads Latitude context from OTel context and stamps attributes onto spans.

class LatitudeSpanProcessor implements SpanProcessor {
  constructor(
    apiKey: string,
    project: string | undefined,
    options?: LatitudeSpanProcessorOptions,
  );
}

type LatitudeSpanProcessorOptions = {
  disableBatch?: boolean;
  disableSmartFilter?: boolean;
  shouldExportSpan?: (span: ReadableSpan) => boolean;
  blockedInstrumentationScopes?: string[];
  disableRedact?: boolean;
  redact?: RedactSpanProcessorOptions;
  exporter?: SpanExporter;
};

capture(name, fn, options?)

Wraps a function to attach Latitude context to all spans created inside. Uses OpenTelemetry's native context.with() for scoping.

type ContextOptions = {
  name?: string;
  userId?: string;
  sessionId?: string;
  tags?: string[];
  metadata?: Record<string, unknown>;
  /**
   * Routes this capture (and its child spans) to a specific Latitude project.
   * Overrides the constructor's `project` default for the duration of the capture.
   */
  project?: string;
  /**
   * @deprecated Renamed to `project`. Still accepted for backwards compatibility
   * and will be removed in a future release.
   */
  projectSlug?: string;
};

function capture<T>(
  name: string,
  fn: () => T | Promise<T>,
  options?: ContextOptions,
): T | Promise<T>;

Nested capture() behavior:

• userId: last-write-wins
• sessionId: last-write-wins
• metadata: shallow merge
• tags: append and dedupe while preserving order

registerLatitudeInstrumentations(options)

Registers patch-based AI SDK instrumentations against a specific tracer provider.

type InstrumentationName =
  | "openai"
  | "openai-agents"
  | "anthropic"
  | "bedrock"
  | "cohere"
  | "langchain"
  | "llamaindex"
  | "togetherai"
  | "vertexai"
  | "aiplatform";

// `object | undefined` rejects primitive values (`true`, `42`, `"openai"`, …)
// at compile time while still admitting class constructors (functions),
// namespace imports, and explicit-undefined-for-conditional-config.
type InstrumentationsInput = Partial<Record<InstrumentationName, object | undefined>>;

function registerLatitudeInstrumentations(options: {
  // Map of integration name → LLM SDK module reference (e.g. { openai: OpenAI }).
  // Anything else throws at register time.
  instrumentations: InstrumentationsInput;
  tracerProvider: TracerProvider;
}): Promise<void>;

Vendor-Specific Integration Guides

For users with existing observability infrastructure.

With Datadog

Initialize Datadog first, then construct new Latitude() so Latitude can attach to Datadog's OTel provider when possible:

import OpenAI from "openai";
import tracer from "dd-trace";
import { Latitude } from "@latitude-data/telemetry";

tracer.init({ service: "my-app", env: "production" });

const latitude = new Latitude({
  apiKey: process.env.LATITUDE_API_KEY!,
  project: process.env.LATITUDE_PROJECT_SLUG!,
  instrumentations: { openai: OpenAI },
});

await latitude.ready;

// LLM calls are now traced and sent to both Datadog and Latitude.
await latitude.flush();
await latitude.shutdown(); // Does not shut down Datadog.

Adding context: Use capture() if you want to add user IDs, session IDs, or tags to your traces (see Using capture() for Context and Boundaries).

With Sentry

Initialize Sentry first, then Latitude. Sentry installs an OpenTelemetry BasicTracerProvider; Latitude detects it and adds its processor without replacing Sentry's context manager, propagator, sampler, or span processor:

import OpenAI from "openai";
import * as Sentry from "@sentry/node";
import { Latitude } from "@latitude-data/telemetry";

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
});

const latitude = new Latitude({
  apiKey: process.env.LATITUDE_API_KEY!,
  project: process.env.LATITUDE_PROJECT_SLUG!,
  instrumentations: { openai: OpenAI },
});

await latitude.ready;

// LLM calls are now traced and sent to both Sentry and Latitude.
await latitude.flush();
await latitude.shutdown(); // Does not shut down Sentry.

Adding context: Use capture() if you want to add user IDs, session IDs, or tags to your traces (see Using capture() for Context and Boundaries).

With New Relic

Enable New Relic's OpenTelemetry bridge first, then construct new Latitude(). New Relic registers an OpenTelemetry BasicTracerProvider; Latitude attaches to that provider when possible and only shuts down Latitude's own processor.

import "newrelic";
import OpenAI from "openai";
import { Latitude } from "@latitude-data/telemetry";

const latitude = new Latitude({
  apiKey: process.env.LATITUDE_API_KEY!,
  project: process.env.LATITUDE_PROJECT_SLUG!,
  instrumentations: { openai: OpenAI },
});

With Honeycomb

Start Honeycomb's HoneycombSDK first, then construct new Latitude(). Honeycomb extends OpenTelemetry's NodeSDK, so Latitude reuses the global provider created by sdk.start().

import OpenAI from "openai";
import { HoneycombSDK } from "@honeycombio/opentelemetry-node";
import { Latitude } from "@latitude-data/telemetry";

const honeycomb = new HoneycombSDK({ serviceName: "my-app" });
honeycomb.start();

const latitude = new Latitude({
  apiKey: process.env.LATITUDE_API_KEY!,
  project: process.env.LATITUDE_PROJECT_SLUG!,
  instrumentations: { openai: OpenAI },
});

Migrating from instrumentations: ["openai"] (3.0.0-alpha.10 and earlier)

The string-array form is removed with no fallback in 3.0.0-alpha.11. Passing a string array — or anything other than a plain object — throws at register time. Switch to the object form, mapping integration name → LLM SDK module:

- import { Latitude } from "@latitude-data/telemetry";
+ import OpenAI from "openai";
+ import * as AnthropicSDK from "@anthropic-ai/sdk";
+ import { Latitude } from "@latitude-data/telemetry";

  new Latitude({
    apiKey: process.env.LATITUDE_API_KEY!,
    project: process.env.LATITUDE_PROJECT_SLUG!,
-   instrumentations: ["openai", "anthropic"],
+   instrumentations: { openai: OpenAI, anthropic: AnthropicSDK },
  });

For anthropic, pass the namespace (import * as AnthropicSDK from "@anthropic-ai/sdk") — the underlying Traceloop patch reads module.Anthropic.Messages.prototype. The SDK also accepts a bare default-export class (it wraps it back into { Anthropic }), but the namespace form is the recommended shape.

Supported AI Providers

| Identifier | Package | | ----------------- | --------------------------------- | | "openai" | openai | | "openai-agents" | @openai/agents | | "anthropic" | @anthropic-ai/sdk | | "bedrock" | @aws-sdk/client-bedrock-runtime | | "cohere" | cohere-ai | | "langchain" | langchain | | "llamaindex" | llamaindex | | "togetherai" | together-ai | | "vertexai" | @google-cloud/vertexai | | "aiplatform" | @google-cloud/aiplatform |

Context Options

capture() accepts these context options:

| Option | Type | OTel Attribute | Description | | ----------- | ------------------------- | ----------------------- | ---------------------------- | | name | string | latitude.capture.name | Name for the capture context | | tags | string[] | latitude.tags | Tags for filtering traces | | metadata | Record<string, unknown> | latitude.metadata | Arbitrary key-value metadata | | sessionId | string | session.id | Group traces by session | | userId | string | user.id | Associate traces with a user |

Configuration Options

Smart Filtering

By default, only LLM-relevant spans are exported:

new LatitudeSpanProcessor(apiKey, project, {
  disableSmartFilter: true, // Export all spans
});

Redaction

PII redaction is enabled by default for security-sensitive attributes only:

Redacted by default:

• HTTP authorization headers
• HTTP cookies
• HTTP API key headers (x-api-key)
• Database statements

new LatitudeSpanProcessor(apiKey, project, {
  disableRedact: true, // Disable all redaction
  redact: {
    attributes: [/^password$/i, /secret/i], // Add custom patterns
    mask: (attr, value) => "[REDACTED]",
  },
});

Custom Filtering

new LatitudeSpanProcessor(apiKey, project, {
  shouldExportSpan: (span) => span.attributes["custom"] === true,
  blockedInstrumentationScopes: ["opentelemetry.instrumentation.fs"],
});

Environment Variables

| Variable | Default | Description | | ------------------------ | ------------------------------------------------------------------- | ---------------------- | | LATITUDE_TELEMETRY_URL | http://localhost:3002 (dev) / https://ingest.latitude.so (prod) | OTLP exporter endpoint |

Troubleshooting

Spans not appearing in Latitude

1. Check API key and project slug — Must be non-empty strings
2. Verify instrumentations are registered — Use await registerLatitudeInstrumentations()
3. Did the bootstrap throw a migration error? — instrumentations: ["openai"] (or any array / non-object form) is no longer accepted in 3.0.0-alpha.11+. Switch to the object form: instrumentations: { openai: OpenAI }. See the Migration section above.
4. Flush before exit — Call await latitude.flush() or await provider.forceFlush()
5. Check smart filter — Only LLM spans are exported by default. Use disableSmartFilter: true to export all spans
6. Ensure capture() wraps the code that creates spans — capture() itself doesn't create spans; it only attaches context to spans created by instrumentations

No spans created inside capture()

capture() only attaches context. You need:

1. An active instrumentation (e.g., @traceloop/instrumentation-openai)
2. That instrumentation to create spans for the operations inside your callback

Context not propagating

Ensure you have a functioning OpenTelemetry context manager registered:

import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
import { context } from "@opentelemetry/api";

context.setGlobalContextManager(new AsyncLocalStorageContextManager());

new Latitude() does this automatically. For shared-provider setups, your app's existing OTel setup should already have this.

License

MIT