Analytics Exporter: Adding a New Event

Analytics Exporter: Adding a New Event

Reference for extending the analytics exporter with a new event handler. The exporter ships process-level OTel telemetry to the Camunda Analytics backend; downstream dashboards and alerts depend on stable attribute key strings and event names across versions. Getting registration or backwards compatibility wrong silently drops data or breaks analytics.

Iron rule — NEVER expose PII. Variable values, usernames, email addresses, user IDs, or any other personally identifiable data must never be emitted. Only process metadata (process IDs, definition keys, instance keys, element IDs, tenant IDs, timestamps) is acceptable. When in doubt, leave it out.

Module layout

zeebe/exporters/analytics-exporter/src/main/java/io/camunda/exporter/analytics/
  AnalyticsExporter.java        ← entry point; configure() wires up the HandlerRegistry
  AnalyticsHandler.java         ← @FunctionalInterface — implement this
  HandlerRegistry.java          ← routes (ValueType, Intent) → handler
  AnalyticsAttributes.java      ← all OTel attribute keys and event/metric name constants
  OtelSdkManager.java           ← logEvent() / incrementMetric() / emitHeartbeat()
  handler/                      ← one class per event type

Step 1 — Identify the Zeebe record to handle

Determine the ValueType, Intent, and RecordValue type from the Zeebe protocol:

zeebe/protocol/src/main/java/io/camunda/zeebe/protocol/record/value/
zeebe/protocol/src/main/java/io/camunda/zeebe/protocol/record/intent/

Check HandlerRegistry in AnalyticsExporter.configure() to confirm there is no existing handler for that (ValueType, Intent) pair — the registry throws IllegalStateException on duplicate registration.

One handler per (ValueType, Intent). If the same intent covers multiple element types (like PROCESS_INSTANCE / ELEMENT_ACTIVATED), add filtering logic inside the handler (see AdHocSubProcessHandler for an example).