Begin met App Analytics

Voeg analytics toe aan een bestaande app in drie stappen: registreer een gebeurtenis, stuur deze door via je backend en verifieer het in Analytics. Er is geen specifieke analytics-bibliotheek vereist.

Prerequisites

• Een app die is ingeschreven in de App Analytics preview, met app-telemetrie ingeschakeld.
• De rechten die in Requirements staan.

Stap 1: Neem een gebeurtenis op

Roep deze code aan vanuit een bestaande interactiehandler. Dit voorbeeld registreert report_exported nadat een rapportexport is geslaagd:

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

/_analyticsis een route die je aan je app toevoegt, niet een ingebouwde Azure Databricks-endpoint. Stap 2 toont de exportlogica voor de backend-handler.

session_id is een optie. Als je er een levert, hergebruik dan de oorspronkelijke analytics-sessie in plaats van voor elk event een nieuwe sessie-ID te genereren. Als je een gebeurtenis opnieuw probeert, stuur dan hetzelfde record opnieuw, inclusief de ID en tijdstempel.

Voor paginaweergaven, Web Vitals en actie-eigenschappen, zie Payload-voorbeelden.

Stap 2: Exporteer vanuit je backend

Voeg een POST /_analytics handler toe aan je bestaande backend. Geef de geanalyseerde en gevalideerde requestbody door aan de volgende functie. Houd de route achter het toegangsbeheer van je app en pas je bestaande limieten voor verzoeken en foutafhandeling toe. Geef succes pas terug in de browser nadat de functie slaagt.

De functie wikkelt het record in een OpenTelemetry Protocol (OTLP)-verzoek en stuurt het naar de verzamelaar van de app:

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

Stap 3: Verifiëren in Analytics

1. Rol de wijzigingen uit met de bestaande deploymentworkflow van je app en start vervolgens de geinstrumenteerde interactie.
2. Open Analytics op de pagina met appdetails en selecteer een SQL-warehouse.
3. Als onboarding wordt weergegeven, selecteer Check for events en vervolgens Open Analytics wanneer gebeurtenissen binnenkomen.
4. Vind report_exported in Topacties of Live-evenementen.

Acceptatie door de collector gaat vooraf aan de ingestie van tabellen. Als het evenement niet verschijnt, ververs dan Analytics en controleer het tijdsbereik. Volg alle toestemmingsrichtlijnen die door de gebruikersinterface worden getoond. Om de onderliggende telemetriegegevens te controleren, zie Telemetriegegevens verifiëren.

Aanvullende bronnen

• Wat is App Analytics?
• App Analytics schema voor gebeurtenissen en query's