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.

Setting Metadata at Init

Configure global metadata when calling init():

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

Every event from this point forward carries these keys. You can filter or group by them in the dashboard.

Updating Metadata at Runtime

globalMetadata is static after init() — it cannot be mutated at runtime. If you need to change app-wide context after initialization, you have three options depending on your use case:

Option 1: Per-event metadata (recommended for ad-hoc context)

Pass metadata directly with each custom event:

tracelog.event('checkout_completed', {
  orderId: 'ORD-789',
  experiment_pricing: 'control',
  total: 149.99
});

Option 2: identify() for user attribution

Use identify() when the context is about a known user (plan, role, traits). It can be called before or after init():

tracelog.identify('user_123', {
  plan: 'pro',
  role: 'admin'
});

identify() attaches the userId to the session and forwards the traits as event metadata. On logout, call tracelog.resetIdentity().

Option 3: Re-initialize (rare)

If you genuinely need to swap globalMetadata mid-session — e.g., the user switches workspace or app environment — call destroy() then init() again with the new metadata. This ends the current session and starts a new one.

await tracelog.destroy();
await tracelog.init({
  globalMetadata: { env: 'staging', tenant: 'workspace-b' },
  integrations: { tracelog: { projectId: 'your-project-id' } }
});

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 globalMetadata and identify() attach data to events. The key difference:

	globalMetadata	identify()
Purpose	App-wide context (environment, flags)	Link session to a known user
User attribution	No	Yes — events are attributed to userId
When to use	Feature flags, A/B tests, build info	Login / user account data
Mutable at runtime	No (set once at init)	Yes (call identify() again)

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