Global Metadata

Global metadata is a set of key-value pairs that TraceLog automatically attaches to every event sent to your backend. Use it for context that applies across the entire session: app version, environment, feature flags, A/B experiments, or user plan.

Setting Metadata at Init

Configure initial global metadata when calling init():

await tracelog.init({
  globalMetadata: {
    env: 'production',
    version: '2.1.0',
    appName: 'MyApp'
  },
  integrations: {
    tracelog: { projectId: 'your-project-id' }
  }
});

Updating Metadata at Runtime

Replace All Metadata

updateGlobalMetadata() replaces the entire metadata object. Previous keys are removed.

// User logs in — replace metadata with user context
tracelog.updateGlobalMetadata({
  userId: 'user-456',
  plan: 'premium'
});

// User logs out — clear all metadata
tracelog.updateGlobalMetadata({});

Merge with Existing Metadata

mergeGlobalMetadata() adds or updates specific keys without removing others.

// Add user ID while preserving env and version
tracelog.mergeGlobalMetadata({ userId: 'user-123' });

// Update version while preserving everything else
tracelog.mergeGlobalMetadata({ version: '2.2.0' });

// Set feature flags
tracelog.mergeGlobalMetadata({
  featureNewUI: true,
  featureDarkMode: false
});

Common Use Cases

User Login / Logout

// On login
function onLogin(user) {
  tracelog.mergeGlobalMetadata({
    userId: user.id,
    plan: user.subscription.plan,
    role: user.role
  });
}

// On logout
function onLogout() {
  tracelog.updateGlobalMetadata({}); // Clear all user context
}

A/B Experiments

tracelog.mergeGlobalMetadata({
  experiment_checkout: 'variant-b',
  experiment_pricing: 'control'
});

Every event from this point forward carries the experiment assignments. When you analyze events in the dashboard, you can filter or group by these metadata keys.

Environment Context

tracelog.mergeGlobalMetadata({
  buildNumber: process.env.BUILD_NUMBER,
  region: user.location.region,
  language: navigator.language
});

Feature Flags

const flags = await getFeatureFlags(userId);

tracelog.mergeGlobalMetadata({
  flag_new_dashboard: flags.newDashboard,
  flag_beta_export: flags.betaExport
});

Validation Rules

Rule	Limit
Maximum keys	100
Total size	48KB serialized
Items per array	500
Characters per string	1000

Allowed value types: string, number, boolean, string arrays, nested objects (1 level deep)

Not allowed: functions, symbols, undefined, deeply nested objects (more than 1 level)

Difference from identify()

Both mergeGlobalMetadata() and identify() attach data to events. The key difference:

	mergeGlobalMetadata()	identify()
Purpose	App-wide context (environment, flags)	Link session to a known user
User attribution	No	Yes — events are attributed to userId
Typical use	Feature flags, A/B tests, build info	Login / user account data

For associating events with a specific user, use tracelog.identify() instead of putting a user ID in global metadata.

warning

Both updateGlobalMetadata() and mergeGlobalMetadata() require TraceLog to be initialized. Calling them before init() throws an error.