@primafuture/telemetry-structured-metadata

Shared structured metadata encoder for PrimaFuture telemetry libraries.

It converts nested JavaScript metadata into OpenTelemetry-safe flat attributes and an optional JSON representation that can be decoded back later.

Usage

import {
  encodeStructuredMetadata,
  decodeStructuredMetadata,
} from '@primafuture/telemetry-structured-metadata';

const attributes = encodeStructuredMetadata({
  request: {
    id: 'abc',
    deletedAt: null,
  },
  missing: undefined,
});

Default output:

app.value.request.id = "abc"
app.type.request.deletedAt = "null"
app.type.missing = "undefined"
app.meta.json = "{\"request\":{\"id\":\"abc\",\"deletedAt\":null},\"missing\":{\"$pfType\":\"undefined\"}}"

flatten output is meant for queries. json output is meant for reconstruction. raw output is disabled by default and only passes through OpenTelemetry-safe scalar or homogeneous array values.

Options

All output modes are independent and can be enabled at the same time:

encodeStructuredMetadata(metadata, {
  flatten: {
    enabled: true,
    namespace: 'app',
    valuePrefix: 'value',
    typePrefix: 'type',
    typeFields: 'when-needed',
  },
  json: {
    enabled: true,
    key: 'app.meta.json',
    valueEncoding: 'typed',
    typeKey: '$pfType',
  },
  raw: {
    enabled: false,
  },
});

Defaults:

• flatten.enabled = true
• flatten.namespace = "app"
• flatten.valuePrefix = "value"
• flatten.typePrefix = "type"
• flatten.typeFields = "when-needed"
• json.enabled = true
• json.key = "app.meta.json"
• json.valueEncoding = "typed"
• json.typeKey = "$pfType"
• raw.enabled = false

typeFields controls app.type.* output:

• when-needed: emit type markers only for values that plain OTel attributes cannot represent clearly, such as null, undefined, Date, bigint, Error, empty objects/arrays, functions, symbols, circular references, and unsupported objects.
• always: emit a type marker for every flattened value.
• never: do not emit type markers.

json.valueEncoding = "typed" preserves JavaScript-only values using the configured type key. plain-json writes ordinary JSON instead: Date becomes an ISO string, bigint becomes a string, and undefined/function/symbol values follow normal JSON behavior.

raw.enabled = true is a compatibility mode. It passes through only OTel-safe scalar values or homogeneous arrays. Nested objects never go through raw mode.

Decode

decodeStructuredMetadata(attributes) reads the configured JSON key, defaulting to app.meta.json, and reconstructs the metadata object from the JSON view.

const decoded = decodeStructuredMetadata(attributes);

The decoder primarily uses JSON because flattened attributes are a query view, not the source of truth for reconstruction. It also accepts Loki-style underscore keys such as app_meta_json.

Development

npm install
npm run typecheck
npm test
npm run build
npm run prepublishOnly