Skip to main content
Add custom metadata and tags to your traces for powerful filtering, grouping, and analytics. Perfect for A/B testing deployments, tracking request types, or any custom categorization.

​
Overview

Fallom supports two types of custom data:
TypeUse CaseExample
MetadataStructured key-value pairs{ deployment: "dedicated", requestType: "transcript" }
TagsSimple string labels["production", "high-priority", "v2"]

​
Usage

Add metadata and tags when creating a session:
import fallom from "@fallom/trace";
import OpenAI from "openai";

await fallom.init({ apiKey: process.env.FALLOM_API_KEY });

const session = fallom.session({
  configKey: "my-app",
  sessionId: "session-123",
  customerId: "user-456",
  
  // Structured key-value metadata
  metadata: {
    deployment: "dedicated",      // or "hosted"
    requestType: "transcript",    // or "frame"
    provider: "novita",           // or "openai"
    environment: "production",
    version: "2.1.0",
  },
  
  // Simple string tags for quick filtering
  tags: ["production", "dedicated", "transcript-analysis"],
});

// All traced calls include this metadata and tags
const openai = session.wrapOpenAI(new OpenAI());

const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});

​
Common Use Cases

​
A/B Testing Deployments

Compare performance between different LLM providers or deployment types: 
// Track dedicated vs hosted deployment
const session = fallom.session({
  configKey: "my-app",
  sessionId: conversationId,
  metadata: {
    deployment: "dedicated",  // or "hosted"
    provider: "novita",       // or "openai"
  },
  tags: ["dedicated"],
});
Then filter in the dashboard by deployment: dedicated to see all traces from your dedicated instance.

​
Request Type Categorization

Group traces by the type of work being done: 
const session = fallom.session({
  configKey: "my-app",
  sessionId: requestId,
  metadata: {
    requestType: "transcript-analysis",  // or "frame-analysis", "summarization"
    priority: "high",
  },
  tags: ["transcript", "analysis"],
});

​
Environment Tracking

Separate production, staging, and development traces: 
const session = fallom.session({
  configKey: "my-app",
  sessionId: requestId,
  metadata: {
    environment: process.env.NODE_ENV,
    region: process.env.AWS_REGION,
    version: process.env.APP_VERSION,
  },
  tags: [process.env.NODE_ENV, "v2"],
});

​
Feature Flags

Track which feature variants are being used: 
const session = fallom.session({
  configKey: "my-app",
  sessionId: requestId,
  metadata: {
    feature_new_prompt: true,
    feature_caching: false,
    experiment_id: "exp-123",
  },
  tags: ["experiment", "new-prompt"],
});

​
Metadata Types

Metadata values can be:
  • Strings: "production", "dedicated"
  • Numbers: 42, 3.14
  • Booleans: true, false
metadata: {
  environment: "production",   // string
  retryCount: 3,               // number
  cacheEnabled: true,          // boolean
  latencyThreshold: 0.95,      // number (decimal)
}

​
Filtering in Dashboard

Once you’ve added metadata and tags to your traces, you can filter them in the Fallom dashboard:

​
By Tags

Use the tags filter to find traces with specific tags. Tags support partial matching (contains):
  • Filter by single tag: production
  • Filter by multiple tags: production, high-priority

​
By Metadata

Filter traces by specific metadata key-value pairs:
  • deployment:dedicated - Find all traces from dedicated deployments
  • requestType:transcript - Find all transcript analysis requests
  • environment:production - Find all production traces

​
Best Practices

Keep metadata keys consistent across your application. Use the same key names (e.g., always deployment not sometimes deploy or deployment_type) for easier filtering.
  1. Use metadata for structured data that you’ll query by specific values
  2. Use tags for quick labels that you’ll search with “contains”
  3. Keep metadata keys short but descriptive
  4. Document your metadata schema so your team uses consistent keys
  5. Don’t put sensitive data in metadata or tags (they’re visible in the dashboard)

​
API Reference

​
Session Options

ParameterTypeDescription
metadataRecord<string, string | number | boolean>Key-value pairs for structured filtering
tagsstring[]Array of string labels for quick categorization

​
Storage

Metadata and tags are stored in the trace attributes as:
  • fallom.metadata - Your custom metadata object
  • fallom.tags - Your tags array
These are queryable via the dashboard filters and API.