analytics-instrumentation

Analytics Instrumentation

Event Naming

All events MUST be prefixed with opik_. Segment routes opik_* events to PostHog. The tooling enforces this automatically, but event names defined in code should already include the prefix.

Examples: opik_onboarding_agent_name_submitted, opik_eval_suite_created, opik_optimization_created

Frontend Events

Files

• Tracking utility: apps/opik-frontend/src/lib/analytics/tracking.ts (mode-agnostic; safe to import from any project code)
• Segment init: apps/opik-frontend/src/plugins/comet/analytics/index.ts (comet-only)
• Plugin init: apps/opik-frontend/src/plugins/comet/init.tsx (comet-only)

Adding a new event

1. Add the event name to the OpikEvent const in tracking.ts:

export const OpikEvent = {
  ONBOARDING_AGENT_NAME_SUBMITTED: "opik_onboarding_agent_name_submitted",
} as const;

1. Call trackEvent from the component or hook where the action happens:

import { trackEvent, OpikEvent } from "@/lib/analytics/tracking";

trackEvent(OpikEvent.ONBOARDING_AGENT_NAME_SUBMITTED, {
  agent_name: agentName,
});

How it works

• trackEvent() safely no-ops when Segment isn't loaded (OSS mode)
• opik_ prefix is enforced at runtime as a safety net
• OPIK_ANALYTICS_ENVIRONMENT is injected into event properties automatically by trackEvent()
• Frontend custom events flow through Segment (same pipeline as backend): Segment → PostHog
• PostHog still handles automatic pageviews, user identification, and feature flags directly

Backend Events

Files

• Service: apps/opik-backend/src/main/java/com/comet/opik/infrastructure/bi/AnalyticsService.java
• Config: apps/opik-backend/src/main/java/com/comet/opik/infrastructure/AnalyticsConfig.java
• YAML config: apps/opik-backend/config.yml (under analytics:)

API

AnalyticsService exposes two overloads:

void trackEvent(String eventType, Map<String, String> properties);
void trackEvent(String eventType, Map<String, String> properties, String identity);