Zacznij z analityką aplikacji

Dodaj analitykę do istniejącej aplikacji w trzech krokach: zarejestruj zdarzenie, przekieruj je przez backend i zweryfikuj w Analytics. Nie jest wymagana żadna konkretna biblioteka analityczna.

Prerequisites

• Aplikacja zarejestrowana w podglądzie App Analytics, z włączoną telemetrią aplikacji.
• Uprawnienia wymienione w Wymaganiach.

Krok 1: Nagraj zdarzenie

Wywołaj ten kod z istniejącego handlera interakcji. Ten przykład rejestruje report_exported po pomyślnym wyeksportowaniu raportu:

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.');

/_analyticsto trasa, którą dodajesz do swojej aplikacji, a nie wbudowany punkt końcowy Azure Databricks. Krok 2 pokazuje logikę eksportu dla obsługi backendu.

Element session_id jest opcjonalny. Jeśli go podasz, użyj ponownie pierwotnej sesji analitycznej, zamiast generować nowy identyfikator sesji dla każdego zdarzenia. Jeśli ponawiasz zdarzenie, wyślij ponownie ten sam rekord wraz z jego identyfikatorem i znacznikiem czasu.

Informacje o odsłonach stron, Web Vitals i właściwościach akcji znajdziesz w sekcji Przykłady danych payload.

Krok 2: Eksport z backendu

Dodaj POST /_analytics handlera do istniejącego backendu. Przekaż jego parsowany i zweryfikowany korpus żądań do następującej funkcji. Zachowaj trasę za kontrolą dostępu w aplikacji i stosuj istniejące limity żądań oraz obsługę błędów. Zwróć do przeglądarki informację o powodzeniu dopiero po pomyślnym zakończeniu funkcji.

Funkcja owija rekord żądaniem protokołu OpenTelemetry (OTLP) i wysyła go do kolektora aplikacji:

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.');
  }
}

Krok 3: Weryfikacja w analityce

1. Wdróż zmiany, korzystając z istniejącego procesu wdrażania aplikacji, a następnie wywołaj interakcję objętą instrumentacją.
2. Na stronie szczegółów aplikacji otwórz Analytics i wybierz magazyn SQL.
3. Jeśli pojawi się ekran wdrożenia, wybierz Sprawdź zdarzenia, a następnie Otwórz Analytics, gdy zdarzenia się pojawią.
4. Znajdź report_exported w sekcji Top Actions lub Live Events.

Akceptacja kolektora poprzedza importowanie tabeli. Jeśli zdarzenie się nie pojawi, odśwież Analytics i sprawdź przedział czasowy. Stosuj się do wszelkich wytycznych dotyczących uprawnień wskazanych przez interfejs użytkownika. Aby sprawdzić podstawowe dane telemetryczne, zobacz Verify telemetry data.

Dodatkowe zasoby

• Czym jest App Analytics?
• Schemat zdarzeń i zapytania dotyczące App Analytics