Custom Metadata & Tags

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:

Type	Use Case	Example
Metadata	Structured key-value pairs	`{ deployment: "dedicated", requestType: "transcript" }`
Tags	Simple string labels	`["production", "high-priority", "v2"]`

Usage

TypeScript

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.

Use metadata for structured data that you’ll query by specific values
Use tags for quick labels that you’ll search with “contains”
Keep metadata keys short but descriptive
Document your metadata schema so your team uses consistent keys
Don’t put sensitive data in metadata or tags (they’re visible in the dashboard)

API Reference

Session Options

Parameter	Type	Description
`metadata`	`Record<string, string \| number \| boolean>`	Key-value pairs for structured filtering
`tags`	`string[]`	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.

Getting Started

Features

TypeScript Integrations

Python Integrations

AI Coding Tools

No-Code Integrations

Custom Metadata & Tags

Overview

Usage

Common Use Cases

A/B Testing Deployments

Request Type Categorization

Environment Tracking

Feature Flags

Metadata Types

Filtering in Dashboard

By Tags

By Metadata

Best Practices

API Reference

Session Options

Storage

​Overview

​Usage

​Common Use Cases

​A/B Testing Deployments

​Request Type Categorization

​Environment Tracking

​Feature Flags

​Metadata Types

​Filtering in Dashboard

​By Tags

​By Metadata

​Best Practices

​API Reference

​Session Options

​Storage

Overview

Usage

Common Use Cases

A/B Testing Deployments

Request Type Categorization

Environment Tracking

Feature Flags

Metadata Types

Filtering in Dashboard

By Tags

By Metadata

Best Practices

API Reference

Session Options

Storage