Skip to main content
To instrument your application to send traces to ABV, you can use instrumentation methods for fine-grained control
  1. Context manager: startActiveObservation
  2. Wrapper: observe
  3. Manual: startObservation
These components are interoperable.

​
Setup

To get started with the ABV TypeScript SDK you need to install the SDK and initialize the client.

​
Instrumentation

You can add custom instrumentations to your application via
  • the observe wrapper
  • startActiveObservation context managers
  • manually managing the observation lifecycle and its nesting with the startObservation function
For an end-to-end example, see the JS Instrumentation Cookbook.

​
Context management with callbacks

To simplify nesting and context management, you can use startActiveObservation. These functions take a callback and automatically manage 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 the recommended approach for most use cases as it prevents context leakage and ensures observations are properly ended. 
import "./instrumentation";
import { startActiveObservation, startObservation } from "@abvdev/tracing";

async function main() {
  await startActiveObservation(
    // name
    "user-request",
    // callback
    async (span) => {
      span.update({
        input: { query: "What is the capital of France?" },
      });

      // Example child, could also use startActiveObservation
      // This manually created generation (see docs below) will automatically be a child of "user-request"
      const generation = startObservation(
        "llm-call",
        {
          model: "gpt-4",
          input: [{ role: "user", content: "What is the capital of France?" }],
        },
        { asType: "generation" }
      );
      generation.update({
        usageDetails: { input: 10, output: 5 },
        output: { content: "The capital of France is Paris." },
      });
      generation.end();

      span.update({ output: "Successfully answered." });
    }
  );
}

main();

​
observe wrapper

The observe wrapper is a powerful tool for tracing existing functions without modifying their internal logic. It acts as a decorator that automatically creates a span or generation around the function call. You can use the updateActiveObservation function to add attributes to the observation from within the wrapped function. 
import { observe, updateActiveObservation } from "@abvdev/tracing";

// An existing function
async function fetchData(source: string) {
  updateActiveObservation({ metadata: { source: "API" } });
  // ... logic to fetch data
  return { data: `some data from ${source}` };
}

// Wrap the function to trace it
const tracedFetchData = observe(
  // method
  fetchData,
  // options, optional, see below
  {}
);

// Now, every time you call tracedFetchData, a span is created.
// Its input and output are automatically populated with the
// function's arguments and return value.
const result = await tracedFetchData("API");
You can configure the observe wrapper by passing an options object as the second argument:
OptionDescriptionDefault
nameThe name of the observation.The original function’s name.
asTypeThe type of observation to create (e.g. span, generation)."span"
captureInputWhether to capture the function’s arguments as the input of the observation.true
captureOutputWhether to capture the function’s return value or thrown error as the output of the observation.true

​
Manual observations

The core tracing function (startObservation) gives you full control over creating observations. You can pass the asType option to specify the type of observation to create. When you call one of these functions, the new observation is automatically linked as a child of the currently active operation in the OpenTelemetry context. However, it does not make this new observation the active one. This means any further operations you trace will still be linked to the original parent, not the one you just created. To create nested observations manually, use the methods on the returned object (e.g., parentSpan.startObservation(...)). 
import { startObservation } from "@abvdev/tracing";

// Start a root span for a user request
const span = startObservation(
  // name
  "user-request",
  // params
  {
    input: { query: "What is the capital of France?" },
  }
);

// Create a nested span for a e.g. tool call
const toolCall = span.startObservation(
  // name
  "fetch-weather",
  // params
  {
    input: { city: "Paris" },
  },
  // Specify observation type in asType
  // This will type the attributes argument accordingly
  // Default is 'span'
  { asType: "tool" }
);

// Simulate work and end the tool call span
await new Promise((resolve) => setTimeout(resolve, 100));
toolCall.update({ output: { temperature: "15°C" } }).end();

// Create a nested generation for the LLM call
const generation = span.startObservation(
  "llm-call",
  {
    model: "gpt-4",
    input: [{ role: "user", content: "What is the capital of France?" }],
  },
  { asType: "generation" }
);

generation.update({
  usageDetails: { input: 10, output: 5 },
  output: { content: "The capital of France is Paris." },
});

generation.end();

// End the root span
span.update({ output: "Successfully answered user request." }).end();

​
Updating Traces

Often, you might not have all the information about a trace (like a userId or sessionId) when you start it. The SDK lets you add or update trace-level attributes at any point during its execution.

​
.updateTrace() on an observation

When you create an observation manually with startObservation, the returned object has an .updateTrace() method. You can call this at any time before the root span ends to apply attributes to the entire trace. 
import "./instrumentation";
import { startObservation } from "@abvdev/tracing";

// Start a trace without knowing the user yet
const rootSpan = startObservation("data-processing");

// ... some initial steps ...

// Later, once the user is authenticated, update the trace
const userId = "user-123";
const sessionId = "session-abc";
rootSpan.updateTrace({
  userId: userId,
  sessionId: sessionId,
  tags: ["authenticated-user"],
  metadata: { plan: "premium" },
});

// ... continue with the rest of the trace ...
const generation = rootSpan.startObservation(
  "llm-call",
  {},
  { asType: "generation" }
);

generation.end();

rootSpan.end();

​
updateActiveTrace()

When you’re inside a callback from startActiveObservation, or a function wrapped with observe, you might not have a direct reference to an observation object. In these cases, use the updateActiveTrace() function. It automatically finds the currently active trace in the context and applies the new attributes. 
import "./instrumentation";
import { startActiveObservation, updateActiveTrace } from "@abvdev/tracing";

async function main() {
  await startActiveObservation("user-request", async (span) => {
    // Initial part of the request
    span.update({ input: { path: "/api/process" } });

    // Simulate fetching user data
    await new Promise((resolve) => setTimeout(resolve, 50));
    const user = { id: "user-5678", name: "Jane Doe" };

    // Update the active trace with the user's information
    updateActiveTrace({
      userId: user.id,
      metadata: { userName: user.name },
    });

    // ... continue logic ...
    span.update({ output: { status: "success" } }).end();
  });
}

main();