Get started with App Analytics

Important

This feature is in Private Preview. To try it, reach out to your Azure Databricks contact.

Add analytics to an existing app in three steps: record an event, forward it through your backend, and verify it in Analytics. No specific analytics library is required.

Prerequisites

Step 1: Record an event

Call this code from an existing interaction handler. This example records report_exported after a report export succeeds:

const logRecord = {
  timeUnixNano: (BigInt(Date.now()) * 1000000n).toString(),
  eventName: 'report_exported',
  attributes: [
    { key: 'databricks.app.analytics.schema.version', value: { intValue: '1' } },
    { key: 'databricks.app.analytics.event.id', value: { stringValue: crypto.randomUUID() } },
    { key: 'databricks.app.analytics.event.type', value: { stringValue: 'action' } },
    { key: 'databricks.app.analytics.event.name', value: { stringValue: 'report_exported' } },
  ],
};

const response = await fetch('/_analytics', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify(logRecord),
});
if (!response.ok) throw new Error('Analytics export failed.');

/_analytics is a route you add to your app, not a built-in Azure Databricks endpoint. Step 2 shows the export logic for its backend handler.

session_id is optional. If you supply one, reuse the originating analytics session rather than generating a new session ID for every event. If you retry an event, resend the same record, including its ID and timestamp.

For page views, Web Vitals, and action properties, see Payload examples.

Step 2: Export from your backend

Add a POST /_analytics handler to your existing backend. Pass its parsed and validated request body to the following function. Keep the route behind your app's access controls and apply your existing request limits and error handling. Return success to the browser only after the function succeeds.

The function wraps the record in an OpenTelemetry Protocol (OTLP) request and sends it to the app's collector:

async function exportAnalyticsRecord(logRecord) {
  const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
  if (endpoint !== 'http://localhost:4314') {
    throw new Error('This example requires the TCP OTLP/HTTP receiver at localhost:4314.');
  }

  const response = await fetch(`${endpoint}/v1/logs`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({
      resourceLogs: [
        {
          resource: {
            attributes: [{ key: 'service.name', value: { stringValue: process.env.DATABRICKS_APP_NAME } }],
          },
          scopeLogs: [{ logRecords: [logRecord] }],
        },
      ],
    }),
  });
  if (!response.ok) throw new Error('Collector rejected the request.');
  const text = await response.text();
  const result = text ? JSON.parse(text) : {};
  if (Number(result.partialSuccess?.rejectedLogRecords ?? 0) > 0) {
    throw new Error('Collector rejected the event.');
  }
}

Important

This HTTP example uses the TCP receiver at localhost:4314, which supports HTTP as well as gRPC. For a unix:// or gRPC-only endpoint, use a compatible OpenTelemetry exporter instead. The collector runs inside the deployed app, not on the visitor's device. See App telemetry environment variables.

Step 3: Verify in Analytics

  1. Deploy the changes using your app's existing deployment workflow, then trigger the instrumented interaction.
  2. On the app details page, open Analytics and select a SQL warehouse.
  3. If onboarding is shown, select Check for events, then Open Analytics when events arrive.
  4. Find report_exported in Top actions or Live Events.

Collector acceptance precedes table ingestion. If the event doesn't appear, refresh Analytics and check the time range. Follow any permission guidance shown by the UI. To check the underlying telemetry data, see Verify telemetry data.

Additional resources

  • Last updated on