How Metadata Works

Metadata is arbitrary structured JSON data attached to traces or observations. Unlike tags (simple string labels), metadata is key-value data that enables precise filtering and rich analysis.

Understand Metadata Structure

Metadata is a JSON object with string keys and arbitrary values (strings, numbers, booleans, nested objects, arrays).Example metadata:

{
  "tenant_id": "acme-corp",
  "feature": "document-summarization",
  "experiment_version": "v2.3",
  "model_config": {
    "temperature": 0.7,
    "max_tokens": 1000
  },
  "user_tier": "enterprise",
  "region": "us-west-2"
}

Key properties:

Top-level keys: Identify dimensions (tenant, feature, version, etc.)
Nested objects: Group related data (model config, user details)
Merged on update: Adding new keys preserves existing metadata
Queryable: Filter traces using SQL-like queries on metadata fields

Avoid overwriting the same top-level key multiple times within a single trace. Metadata updates merge based on top-level keys, and rewriting a key produces undefined behavior. Add keys incrementally instead.

Add Metadata to Traces

Attach metadata when creating traces or update it dynamically as your code executes.Python (decorator pattern):

from abvdev import observe, ABV

abv = ABV(api_key="sk-abv-...", host="https://app.abv.dev")

@observe()
def process_request(user_id, tenant_id):
    # Add metadata to the current trace
    abv.update_current_trace(
        metadata={
            "tenant_id": tenant_id,
            "feature": "query-processing",
            "version": "1.2.3"
        }
    )

    # Process the request
    result = handle_query(user_id)
    return result

process_request(user_id="user-456", tenant_id="acme-corp")

Python (manual span creation):

with abv.start_as_current_span(name="process-order") as root_span:
    # Add metadata to the trace
    root_span.update_trace(metadata={"order_id": "order-123", "region": "us-west"})

    # Add metadata to the current span
    root_span.update(metadata={"stage": "validation"})

    # Create child span with metadata
    with root_span.start_as_current_generation(
        name="generate-summary",
        model="gpt-4o",
        metadata={"temperature": 0.7, "max_tokens": 500}
    ) as gen:
        # Update metadata later if needed
        gen.update(metadata={"completion_reason": "stop"})

JavaScript/TypeScript:

import { startActiveObservation, updateActiveTrace } from '@abvdev/tracing';

await startActiveObservation('process-request', async (span) => {
  // Add metadata to the trace
  updateActiveTrace({
    metadata: {
      tenant_id: 'acme-corp',
      feature: 'summarization',
      version: '1.2.3'
    }
  });

  // Add metadata to the observation
  span.update({
    metadata: { stage: 'processing' }
  });

  // Process request...
});

Update Metadata Incrementally

Metadata updates merge based on top-level keys. You can add new keys throughout the trace lifecycle without overwriting existing data.Example: Incremental updates

with abv.start_as_current_span(name="workflow") as span:
    # First update: Add initial context
    span.update_trace(metadata={"status": "started", "user_id": "user-123"})

    # Second update: Add more context (merges with existing)
    span.update_trace(metadata={"feature": "summarization", "model": "gpt-4"})

    # Third update: Add error details if something fails
    try:
        result = process_data()
    except Exception as e:
        span.update_trace(metadata={"error_type": "timeout", "error_message": str(e)})
        raise

# Final metadata: {"status": "started", "user_id": "user-123", "feature": "summarization", "model": "gpt-4", "error_type": "timeout", "error_message": "..."}

Do not write the same top-level key multiple times:

# BAD: Overwrites "status" key unpredictably
span.update_trace(metadata={"status": "started"})
span.update_trace(metadata={"status": "processing"})  # Undefined behavior
span.update_trace(metadata={"status": "completed"})   # Undefined behavior

Instead, use different keys or nested objects:

# GOOD: Different keys for each stage
span.update_trace(metadata={"stage_1": "started"})
span.update_trace(metadata={"stage_2": "processing"})
span.update_trace(metadata={"stage_3": "completed"})

Query Traces by Metadata

In the ABV Dashboard, filter traces using SQL-like queries on metadata fields.Query examples:

metadata.tenant_id = "acme-corp" → All traces for tenant “acme-corp”
metadata.feature = "summarization" → All traces for the summarization feature
metadata.version = "v2.3" AND environment = "production" → Traces for specific version in production
metadata.user_tier = "enterprise" → Traces for enterprise users only
metadata.model_config.temperature > 0.5 → Traces with high temperature settings

Dashboard workflow:

Navigate to the Traces view
Click “Add Filter”
Select “Metadata” and enter your query
Results update instantly

Export filtered traces:

Export to CSV for analysis
Create datasets for evaluations
Generate reports for stakeholders

Aggregate Metrics by Metadata

Use metadata dimensions to aggregate costs, latency, and quality metrics for business analysis.Example analyses:

Cost by tenant: Group traces by metadata.tenant_id to calculate per-tenant LLM costs
Latency by feature: Filter by metadata.feature to identify slow features
Quality by experiment: Compare metadata.experiment_version to measure A/B test results
Error rate by region: Analyze metadata.region to detect regional issues

Dashboard aggregations:

Navigate to Metrics → Custom Dashboards
Create charts grouped by metadata fields
Track trends over time for specific dimensions
Set alerts based on metadata filters (e.g., “alert when enterprise tier costs exceed threshold”)

Why Use Metadata?

Multi-Tenant Applications: Track Costs and Performance Per Customer

Attach tenant_id to isolate costs, performance, and errors by customer.

abv.update_current_trace(metadata={"tenant_id": tenant_id, "subscription_tier": "enterprise"})

Filter by metadata.tenant_id to calculate per-tenant costs or detect tenant-specific errors.

Feature Flagging: Measure Impact of New Features

Tag experiment variants to compare costs, latency, and quality.

abv.update_current_trace(metadata={"experiment_variant": "v2", "experiment_id": "summarization-test"})

Compare metrics by variant to make data-driven rollout decisions.

Deployment Tracking: Correlate Issues with Code Versions

Attach deployment version to correlate issues with releases.

abv.update_current_trace(metadata={"deployment_version": "v1.2.3", "git_commit_sha": "abc123"})

Filter by version to compare error rates and identify regressions.

Model and Prompt Versioning: Compare Configurations

Track model configurations to compare cost, quality, and latency.

abv.update_current_trace(metadata={"model_provider": "openai", "prompt_version": "v3"})

Filter by metadata.model_provider to quantify tradeoffs and optimize selection.

User Segmentation: Analyze by Subscription Tier or Region

Segment traces by user attributes to analyze costs by cohort.

abv.update_current_trace(metadata={"subscription_tier": "enterprise", "region": "us-west"})

Group by tier or region to optimize model selection and justify pricing.

Error Tracking: Categorize and Debug Failures

Categorize errors for faster debugging.

abv.update_current_trace(metadata={"error_type": "timeout", "timeout_seconds": 30})

Filter by metadata.error_type to identify patterns and set alerts.

Implementation Guide

Python: Using the @observe() Decorator

Use the @observe() decorator to automatically trace functions. Update metadata with abv.update_current_trace() and abv.update_current_span().Setup:

pip install abvdev

Basic usage:

from abvdev import observe, ABV

abv = ABV(api_key="sk-abv-...", host="https://app.abv.dev")

@observe()
def process_data(tenant_id, feature_name):
    # Add metadata to the trace
    abv.update_current_trace(
        metadata={
            "tenant_id": tenant_id,
            "feature": feature_name,
            "version": "1.2.3"
        }
    )

    # Add metadata to the current span
    abv.update_current_span(
        metadata={"processing_stage": "initial"}
    )

    # Process data...
    return "Processing complete"

process_data(tenant_id="acme-corp", feature_name="summarization")

Incremental updates:

@observe()
def complex_workflow(data):
    # Initial metadata
    abv.update_current_trace(metadata={"status": "started"})

    step1_result = process_step1(data)
    abv.update_current_trace(metadata={"step1_duration_ms": step1_result.duration})

    step2_result = process_step2(step1_result)
    abv.update_current_trace(metadata={"step2_duration_ms": step2_result.duration})

    # Final metadata
    abv.update_current_trace(metadata={"status": "completed"})
    return step2_result

Python: Manual Span Creation

Create spans manually and attach metadata at the trace or span level.Trace-level metadata:

from abvdev import ABV

abv = ABV(api_key="sk-abv-...", host="https://app.abv.dev")

# Add metadata to the trace
with abv.start_as_current_span(name="process-request") as root_span:
    # Set trace metadata
    root_span.update_trace(metadata={
        "request_id": "req_12345",
        "tenant_id": "acme-corp",
        "feature": "document-processing"
    })

    # Set span metadata
    root_span.update(metadata={"stage": "parsing"})

    # Your code here
    result = process_document()

Span-level metadata:

with abv.start_as_current_span(name="workflow") as root_span:
    root_span.update_trace(metadata={"workflow_id": "wf-123"})

    # Child span with its own metadata
    with root_span.start_as_current_generation(
        name="generate-summary",
        model="gpt-4o",
        metadata={"temperature": 0.7, "max_tokens": 1000}
    ) as gen:
        # Update generation metadata
        gen.update(metadata={"completion_reason": "stop", "tokens_used": 850})

JavaScript/TypeScript: Context Managers

Use the @abvdev/tracing package to add metadata to traces and observations.Setup:

npm install @abvdev/tracing @abvdev/otel @opentelemetry/sdk-node dotenv

Configuration (instrumentation.ts):

import dotenv from 'dotenv';
dotenv.config();

import { NodeSDK } from '@opentelemetry/sdk-node';
import { ABVSpanProcessor } from '@abvdev/otel';

const sdk = new NodeSDK({
  spanProcessors: [
    new ABVSpanProcessor({
      apiKey: process.env.ABV_API_KEY,
      baseUrl: process.env.ABV_BASE_URL,
      exportMode: 'immediate',
      flushAt: 1,
      flushInterval: 1
    })
  ]
});

sdk.start();

Add metadata:

import './instrumentation';  // Must be first import
import { startActiveObservation, updateActiveTrace } from '@abvdev/tracing';

async function main() {
  await startActiveObservation('process-request', async (span) => {
    // Add trace metadata
    updateActiveTrace({
      metadata: {
        tenant_id: 'acme-corp',
        feature: 'summarization',
        version: '1.2.3'
      }
    });

    // Add span metadata
    span.update({
      metadata: { stage: 'processing' }
    });

    // Process request...
  });
}

main();

JavaScript/TypeScript: observe Wrapper

Wrap existing functions with automatic tracing and metadata updates.Example:

import './instrumentation';
import { observe, updateActiveTrace } from '@abvdev/tracing';

// Original function
async function fetchData(source: string, tenantId: string) {
  // Add metadata
  updateActiveTrace({
    metadata: {
      tenant_id: tenantId,
      data_source: source,
      timestamp: new Date().toISOString()
    }
  });

  // Fetch data
  const response = await fetch(source);
  return await response.json();
}

// Wrap with observe
const tracedFetchData = observe(fetchData, {
  name: 'fetch-data-operation'
});

// Use traced version
async function main() {
  const result = await tracedFetchData('https://api.example.com/data', 'acme-corp');
}

main();

JavaScript/TypeScript: Manual Span Creation

Create spans manually with metadata attached.Example:

import './instrumentation';
import { startObservation } from '@abvdev/tracing';

const span = startObservation('manual-operation', {
  input: { query: 'Process this data' },
  metadata: {
    tenant_id: 'acme-corp',
    feature: 'data-processing',
    priority: 'high'
  }
});

// Update trace metadata
span.updateTrace({
  metadata: {
    workflow_id: 'wf-123',
    user_id: 'user-456'
  }
});

// Update span metadata
span.update({
  metadata: { processing_stage: 'validation' }
});

span.end();

Sessions

Group related traces by user journey or job to see end-to-end workflows

Environments

Separate development, staging, and production traces for clean comparisons

User Tracking

Link traces to user accounts for faster debugging and GDPR-compliant handling

Documentation Index

​How Metadata Works

​Why Use Metadata?

​Implementation Guide

​Related Features

Tags

Sessions

Environments

User Tracking

How Metadata Works

Why Use Metadata?

Implementation Guide

Related Features