> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fallom.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Metadata & Tags

> Add custom metadata and tags to traces for filtering and grouping

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

<Tabs>
  <Tab title="TypeScript">
    Add metadata and tags when creating a session:

    ```typescript theme={null}
    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!" }],
    });
    ```
  </Tab>
</Tabs>

## Common Use Cases

### A/B Testing Deployments

Compare performance between different LLM providers or deployment types:

```typescript theme={null}
// 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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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`

```typescript theme={null}
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

<Tip>
  **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.
</Tip>

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

| 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.