The metadata functionality allows you to add custom key-value pairs (string, any) to all components like trace, generation, retrieval, event, and span. This is useful for storing additional context, configuration, user information, or any custom data that helps with debugging, analysis, and observability.
1

Create a repository

Select Logs from the sidebar and click the “Create repository” button.
2

Install SDK

npm install @maximai/maxim-js
3

Initialize SDK

import { Maxim } from "@maximai/maxim-js"

const maxim = new Maxim({ apiKey: "" });

const logger = await maxim.logger({ id: "" });
4

Add metadata to traces

const trace = logger.trace({
  id: "trace-id",
  name: "user-query",
  metadata: {
    userId: "user-123",
    sessionId: "session-456",
    model: "gpt-4",
    temperature: 0.7,
    environment: "production"
  }
});

// Add metadata after creation
trace.addMetadata({"customKey":"customValue","timestamp": new Date().toISOString()});
5

Add metadata to generations

const generation = trace.generation({
  id: "generation-id",
  name: "llm-call",
  metadata: {
    provider: "openai",
    model: "gpt-4",
    maxTokens: 1000,
    temperature: 0.7,
    topP: 0.9
  }
 });
 
 generation.addMetadata({"promptVersion": "v2.1", "userId": "user-123"});
6

Add metadata to other components

// Span with metadata
const span = trace.span({
  id: "span-id",
  name: "data-processing",
  metadata: {
    dataSource: "database",
    recordCount: 150,
    processingTime: "2.3s"
  }
});

// Event with metadata
const event = trace.event({
  id: "event-id",
  name: "user-action",
  metadata: {
    action: "button-click",
    elementId: "submit-btn",
    pageUrl: "/dashboard"
  }
});

// Retrieval with metadata
const retrieval = trace.retrieval({
  id: "retrieval-id",
  name: "vector-search",
  metadata: {
    vectorDb: "pinecone",
    indexName: "documents",
    similarityThreshold: 0.8
  }
});