Observability

AgentMark uses OpenTelemetry for collecting telemetry data. OpenTelemetry is an open-source observability framework that provides vendor-agnostic APIs, libraries, and instrumentation for collecting distributed traces and metrics.

​

Enabling Telemetry

Enable telemetry when calling runInference:

const result = await runInference(Prompt, props, {
  telemetry: {
    isEnabled: true,
    functionId: "calculate-price",
    metadata: {
      userId: "123",
      environment: "production"
    }
  }
});

​

Telemetry with Puzzlet

The easiest way to get started with observability is to use Puzzlet. Puzzlet automatically collects and visualizes telemetry data from your prompts:

import { Puzzlet } from "@puzzlet/sdk";

const puzzletClient = new Puzzlet({
  apiKey: process.env.PUZZLET_API_KEY!,
  appId: process.env.PUZZLET_APP_ID!
});

const result = await runInference(Prompt, props, { telemetry: { isEnabled: true } });

​

Collected Spans

AgentMark records the following span types:

​

Basic LLM Span Information

Each LLM span contains:

​

Custom OpenTelemetry Setup

For custom OpenTelemetry configuration:

import { NodeSDK } from '@opentelemetry/sdk-node';
import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node';

const sdk = new NodeSDK({
  traceExporter: new ConsoleSpanExporter(),
  serviceName: 'my-agentmark-app',
});

sdk.start();

​

Best Practices

1. Enable telemetry in production environments
2. Use meaningful function IDs
3. Include relevant metadata for debugging
4. Monitor token usage and costs

​

Learn More

• OpenTelemetry Documentation