Traces and Logs

Puzzlet uses OpenTelemetry for collecting telemetry data, similar to AgentMark’s observability system. This provides a vendor-agnostic way to collect distributed traces and metrics for your prompt executions.

​

Enabling Tracing

Enable tracing in your Puzzlet client:

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

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

// Initialize tracing
const tracer = puzzletClient.initTracing();

// Run your inference
const result = await runInference(Prompt, props, { 
  telemetry: { 
    isEnabled: true,
    functionId: "my-function",
    metadata: {
      userId: "123",
    }
  } 
});

// Shutdown tracer (only needed for short-running scripts, local testing)
await tracer.shutdown();

​

Collected Spans

Puzzlet records the following OpenTelemetry spans:

​

Basic LLM Span Information

Each LLM span contains:

​

Viewing Traces

Traces can be viewed in the Puzzlet dashboard under the “Traces” tab. Each trace shows:

• Complete prompt execution timeline
• Tool calls and their durations
• Token usage and costs
• Custom metadata and attributes
• Error information (if any)

​

Best Practices

1. Use meaningful function IDs for easy filtering
2. Add relevant metadata for debugging context
3. Monitor token usage and costs regularly
4. Enable tracing in production environments
5. Use the dashboard’s filtering capabilities to debug specific issues

​

Learn More

• AgentMark Observability
• OpenTelemetry Documentation