Manual Instrumentation Patterns

Pattern: One User Request#

Use one session per user request or workflow.

const session = await tracellm.startSession({
  name: "User asked assistant",
  userId: user.id
});

Pattern: Provider Call#

Wrap every model call in an llm span.

const span = await session.startSpan({
  name: "anthropic.chat.generate",
  kind: "llm",
  attributes: {
    provider: "anthropic",
    model
  },
  input: prompt
});
 
const result = await callProvider(prompt);
 
await span.end({
  status: "ok",
  usage: result.usage,
  output: result.text
});

Pattern: Retrieval#

Use retrieval spans for RAG operations.

const retrieval = await session.startSpan({
  name: "vector.search",
  kind: "retrieval",
  attributes: {
    index: "support-docs",
    topK: 5
  }
});

Pattern: Tool Calls#

Use tool spans for external or internal tools.

const tool = await session.startSpan({
  name: "crm.customer.lookup",
  kind: "tool",
  attributes: {
    customerId
  }
});

Pattern: Intermediate Events#

Use events for useful moments inside a span.

await span.recordEvent({
  name: "prompt.rendered",
  attributes: {
    template: "support-answer-v3"
  }
});

Pattern: Do Not Store Secrets#

Avoid putting secrets in:

span names
attributes
event names
metadata
input/output fields

TraceLLM has redaction, but it should be the last line of defense.