Metadata Extractors

🏷️ Metadata Extractors

GermainUX metadata extractors collect application-specific context—such as a username, internal session ID, tenant, account, user role, or application version—and associate it with browser monitoring data.

This context makes captured errors, performance measurements, user interactions, Session Replay, and JavaScript profiling evidence easier to search, segment, correlate, and analyze.

📡 Monitoring components

Metadata extraction is performed by the applicable RUM configuration. The JS Profiler does not replace the metadata extractor; it uses the resulting metadata to contextualize profiler evidence.

Capabilities

Metadata extractors can retrieve values from sources accessible within the monitored browser context, including:

• HTML elements and page content.

• JavaScript variables and application state.

• Browser storage.

• JavaScript-accessible cookies.

• Application APIs.

• Synchronous or asynchronous application logic.

Common metadata includes:

Only collect metadata that is necessary for an approved monitoring or analytics purpose.

Business benefits

Metadata extractors help teams:

• Find all sessions associated with a particular user, account, case, or application session.

• Correlate browser activity with server-side transactions, logs, APIs, and workflows.

• Determine which user roles, customers, or business units are affected by an issue.

• Compare adoption, performance, errors, and behavior across meaningful business segments.

• Give developers more precise context when investigating JavaScript and browser problems.

• Reduce the time required to locate the relevant user session or technical evidence.

• Measure the business impact of an issue more accurately.

Analytics and correlation

Extracted metadata becomes part of the context associated with GermainUX monitoring data. Depending on the field and GermainUX configuration, it can support:

• Search and filtering.

• Session identification.

• KPIs, measures, and pivots.

• User and role segmentation.

• Session Replay analysis.

• Error and performance analysis.

• Business-process correlation.

• Front-end and back-end transaction correlation.

• JS Profiler investigation.

For example, an application session ID collected in the browser can help correlate a slow user interaction with related server-side logs or transactions when the same identifier is available in those data sources.

Configuration

Metadata extractors are configured in the applicable User Monitoring Profile initialization script through:

settings.application.metadataProviders

Each provider is a function with the following definition:

type MetadataProviderFunction = (
  window: Window
) => undefined | null | string | Promise<undefined | null | string>;

A provider can return:

Basic metadata extractor

The following example registers an application-specific session ID extractor:

const settings = germainApm.getDefaultSettings();

settings.application.metadataProviders["sessionId"] = (window) => {
  return getApplicationSessionId(window);
};

function getApplicationSessionId(window) {
  // Application-specific extraction logic
  return "sessionIdValue";
}

germainApm.start(settings);

Replace the sample function with logic appropriate for the monitored application.

Username extractor

The following example waits for an element with the ID username and uses its displayed text as the user’s name:

const settings = germainApm.getDefaultSettings(
  loaderArgs,
  agentConfig
);

settings.application.metadataProviders["user.name"] = (window) => {
  return new Promise((resolve) => {
    germainApm.utils.waitForElements(
      window,
      "#username",
      (elements) => {
        const element = elements[0];
        resolve(element?.innerText || null);
      }
    );
  });
};

germainApm.start(settings);

The selector and extraction logic must be adapted to the application.

If possible, use a stable internal user identifier instead of directly collecting personally identifiable information. A display name should only be collected when permitted by the organization’s privacy and compliance policies.

Session ID extractor

The following example retrieves an application session ID from a JavaScript-accessible cookie named SESSION:

const settings = germainApm.getDefaultSettings(
  loaderArgs,
  agentConfig
);

settings.application.metadataProviders["sessionId"] = (window) => {
  const cookieItems = window.document.cookie
    ? decodeURIComponent(window.document.cookie).split(";")
    : [];

  for (const item of cookieItems) {
    const cookie = item.trim();

    if (cookie.startsWith("SESSION=")) {
      return cookie.substring("SESSION=".length) || null;
    }
  }

  return null;
};

germainApm.start(settings);

Cookies marked HttpOnly are intentionally unavailable to browser JavaScript and cannot be read by a metadata extractor. Do not weaken cookie security settings to make a value available for monitoring.

Asynchronous metadata

Metadata such as the username or session ID may not be available when monitoring starts. A metadata provider can return a Promise so GermainUX can wait for the value.

By default, GermainUX waits up to 15 seconds for all configured metadata providers to resolve before it begins sending potentially incomplete monitoring data.

Use settings.constants.metadataTimeoutMillis to change this timeout. The following example extends it to 20 seconds:

const settings = germainApm.getDefaultSettings();

settings.constants.metadataTimeoutMillis = 20 * 1000;

germainApm.start(settings);

GermainUX waits for all configured providers to resolve, not only the first provider that returns a value. Ensure that every asynchronous provider eventually resolves to a string, null, or undefined.

Privacy and security

Extracted metadata can contain personal, confidential, or security-sensitive information.

Before enabling an extractor:

• Confirm that the field is required for an approved use case.

• Avoid collecting passwords, authentication tokens, secrets, payment data, or complete session credentials.

• Prefer internal identifiers or pseudonymous values over names and email addresses.

• Do not expose HttpOnly cookies or weaken application security controls.

• Apply masking, hashing, anonymization, or transformation when required.

• Restrict access to monitoring and Session Replay data.

• Define appropriate retention requirements.

• Validate the configuration with the organization’s security and compliance teams.

Metadata extractors should not collect the contents of an authentication cookie when a non-sensitive correlation identifier can be used instead.

Validation

After configuring an extractor:

1. Open the monitored application through RUM JS or the RUM Extension.

2. Sign in with an authorized test account.

3. Perform a controlled user interaction.

4. Confirm that the metadata appears in GermainUX.

5. Verify that it is associated with the correct user and session.

6. Confirm that asynchronous providers resolve within the configured timeout.

7. Test the behavior across multiple browser tabs when applicable.

8. Verify that sensitive values are excluded or protected.

9. Confirm that JS Profiler evidence inherits the expected session context when profiling is enabled.

Troubleshooting

Metadata is missing

Verify that:

• The metadata provider is registered before germainApm.start(settings).

• The field exists when the provider runs.

• The HTML selector or application variable is correct.

• The application URL is included in the monitoring scope.

• The provider returns a supported value or Promise.

• An asynchronous provider resolves within the configured timeout.

• Browser security boundaries do not prevent access to the value.

• The value is not stored in an HttpOnly cookie.

• Privacy or processing rules are not removing the metadata.

Monitoring data is delayed

GermainUX waits for all configured metadata providers. Check for a provider that never resolves or increase the timeout only when the application legitimately requires more time.

Metadata is incorrect across tabs

Return:

• undefined when the provider should preserve a value already obtained from another tab.

• null when the existing value should be explicitly explicitly cleared.

Deployment and configuration

ℹ️ Get Help

The Germain Team can help you set this up. Contact GermainUX Support.