@sophonz/meta

한국어

Metadata and span context utilities for Sophonz instrumentation.

Provides helper functions for screen name management, session ID tracking, and span attribute enrichment.

Part of the Sophonz OpenTelemetry suite.

Install

bun add @sophonz/meta
# or
pnpm add @sophonz/meta
# or
npm install @sophonz/meta

Usage

import {
  getScreenName,
  setScreenAttribute,
  spanResources,
  getTitle
} from '@sophonz/meta';

// Set custom screen name (overrides auto-detection)
setScreenAttribute('CheckoutFlow');

// Get current screen name
const screenName = getScreenName({
  screenNameType: 'full',
  urlWithSearchParams: false
});

// Enrich span with standard attributes
spanResources(span, {
  screenNameType: 'routeOnly',
  urlWithSearchParams: false
});

// Get page title
const title = getTitle(); // e.g., "My App"

API

Screen Name Options

ScreenNameOption, whose screenNameType field is the exported ScreenNameType:

| Field | Values | Description | |------|--------|-------------| | screenNameType | 'routeOnly' | 'titleOnly' | 'full' | How to construct the screen name | | urlWithSearchParams | boolean | Include query strings in URL |

URL redaction

spanResources takes SpanResourcesOption, which is ScreenNameOption plus one field:

| Field | Type | Default | Description | |------|--------|-------------|-------------| | sanitizeUrl | (url: string) => string | defaultSanitizeUrl from @sophonz/redaction | Applied to url.full and to the URL used in app.screen.name |

Redaction is on by default. url.full is written from window.location.href on effectively every span the SDK produces, so without it a query string such as ?token=abc rides along on all of them regardless of urlWithSearchParams. The default sanitizer replaces user:password@ credentials and the values of 19 well-known sensitive parameters with REDACTED, keeping the parameter names and leaving every other byte of the URL untouched.

app.screen.name gets the same treatment. With urlWithSearchParams: false the query string is already stripped, so redaction is a no-op there; with true it is what keeps the query string safe.

A supplied sanitizeUrl replaces the default rather than running after it. To keep the defaults and add your own parameters, build one with createSanitizeUrl({ additionalQueryParamsToScrub }).

A supplied function is called inside a try/catch: if it throws or returns a non-string, the URL is written as the bare string REDACTED and the failure is reported once through diag.warn. Only the default sanitizer's results are memoised, since a supplied one is not known to be pure.

Functions

• setScreenAttribute(attribute: string) - Override automatic screen name
• getScreenName(options) - Get current screen name based on options
• setScreenName(span, options) - Add screen attributes to a span
• spanResources(span, options?) - Add screen, session, and URL attributes to a span
• getTitle() - Extract page title from document

Peer Dependencies

• @opentelemetry/api@^1.9.1

License

See LICENSE in this package.

Part of sophonz-js.