OpenTelemetry Integration

The MiniApp Platform provides an OpenTelemetry collector that sends telemetry data to Databricks. The MiniApp SDK encapsulates the OpenTelemetry collector configuration on top of the telemetry SDK and provides a default global configuration for easy integration.

Version Requirements

• MiniApp SDK Version: >= 2.2.0 (npm package @wcm/mini-app-sdk)
• MiniApp Runtime Engine Version: >= 3.2.0

Basic Usage

Example of the OpenTelemetry collector registration and usage:

import { MiniAppOTel } from "@wcm/mini-app-sdk/otel";

export const otel = new MiniAppOTel({
// you don't specify the serviceName, it will be auto extracted from the access token you setup upon seamless login (client_id/azp claim)
});

// then you can register otel collector with the access token from seamless login (check below detailed usage section for concrete example)
otel.registerOTel(accessToken);

// you can start for example emitting logs etc.
import { logs, SeverityNumber } from "@opentelemetry/api-logs";

const logger = logs.getLogger("default");

logger.emit({
  severityNumber: SeverityNumber.ERROR,
  body: "Failed to process request",
  attributes: {
    foo: "bar",
    key1: "value2",
  },
});

Detailed Usage

First, initialize the MiniApp OpenTelemetry client, and register the OpenTelemetry collector with the access token obtained from the seamless login flow:

Note: The OpenTelemetry integration requires the access token retrieved from the seamless login flow. For more details about the seamless login flow, see Authentication Guide.

// ./mini-app/auth.ts
import { MiniAppAuthClient } from "@wcm/mini-app-sdk/auth";
export const authClient = new MiniAppAuthClient();

// ./mini-app/otel.ts
import { MiniAppOTel } from "@wcm/mini-app-sdk/otel";
export const otel = new MiniAppOTel({});

// ./main.ts
authClient
  .signInFromWindowLocation()
  .then(() => {
    console.log("success signInFromWindowLocation");
    // Register otel collector with the access token from seamless login
    otel.registerOTel(authClient.tokens.accessToken);
    // manually re-register the otel collector when the token is refreshed
    authClient.addEventListener("token-refreshed", () => {
      otel.unregisterOTel();
      otel.registerOTel(authClient.tokens.accessToken);
    });
  })
  .catch((err) => {
    console.error("error signInFromWindowLocation", err);
  })
  .finally(() => {
    renderYourApp();
  });

Once set up, you can use OpenTelemetry's various features:

• Traces:

import { trace } from "@opentelemetry/api";

// Get a tracer instance
const tracer = trace.getTracer("my-app-component");

// Create and manage spans
const span = tracer.startSpan("fetchUserData");
try {
  // Your logic here
  const response = await fetchUserData(userId);
  // Add attributes to your span
  span.setAttribute("userId", userId);
  span.setAttribute("status", "success");
} catch (error) {
  // Record errors
  span.recordException(error);
  span.setAttribute("status", "error");
} finally {
  // Always end your span
  span.end();
}

• Logs

import { logs, SeverityNumber } from "@opentelemetry/api-logs";

const logger = logs.getLogger("default");

// Emit an error log
logger.emit({
  severityNumber: SeverityNumber.ERROR,
  body: "Failed to process user request",
  attributes: {
    userId: "123",
    errorCode: "AUTH_001",
    operation: "login",
  },
});

// Emit an info log
logger.emit({
  severityNumber: SeverityNumber.INFO,
  body: "User action completed successfully",
  attributes: {
    action: "profile_update",
    duration_ms: 150,
  },
});

• Metrics

import { metrics } from "@opentelemetry/api";

// Create a meter
const meter = metrics.getMeter("user-operations");

// Create counters
const userLoginCounter = meter.createCounter("user.logins", {
  description: "Number of user logins",
});

// Create histograms for measuring distributions
const requestDurationHistogram = meter.createHistogram("request.duration", {
  description: "Duration of requests in milliseconds",
});

// Usage examples
userLoginCounter.add(1, {
  userType: "regular",
  region: "asia",
});

requestDurationHistogram.record(150, {
  endpoint: "/api/users",
  method: "GET",
});

Accessing otel data in DBX

The pipeline for sending telemetry data from the MiniApp to Databricks consists of the following steps:

• The MiniApp SDK's otel collector sends telemetry data to an otel exporter, including the seamless login access token for authentication.
• The otel exporter validates the access token, extracts the service name from the access token (specifically it's the client_id/azp claim), injects the service name into the telemetry data, and forwards the data to Databricks.
• In Databricks, telemetry data is grouped by service name and ingested into a table named after that service name.
• As a result, all telemetry data emitted by a MiniApp through the otel collector is available in Databricks under a table corresponding to the service name associated with the seamless login access token.

The process of accessing telemetry data sent from the MiniApp to Databricks is not yet fully automated and may require manual intervention. If you need to access to your telemetry data in Databricks, please reach out to us on Woven City App Chat feature through the MiniApp Explorer Project for support.

tip

When initializing the MiniApp OTel client, you can specify the environment using the env option. This should match the runtime engine environment where your MiniApp will run:

• For development and staging environments (env: 'dev' or env: 'stage'), telemetry data will be available at dev databricks
• For production environment (env: 'prod'), telemetry data will be available at prod databricks