Skip to main content

Analytics

i
This feature is available on the Scale plan.
Added in eventcatalog@3.21.0

EventCatalog supports analytics integrations that let you track how your team navigates and uses your catalog. Connect your existing analytics tools to understand which services, events, and flows your team visits most.

Three providers are supported: Google Analytics 4, Google Tag Manager, and PostHog. Multiple providers can be enabled at the same time.

Don't see your analytics provider? Get in contact with us and let us know.

How it works​

Analytics are configured in eventcatalog.config.js under the integrations key. When EventCatalog loads, the provider scripts are injected into the page <head> and a tracker listens for every navigation event.

Every page view sends a set of properties automatically extracted from the URL:

PropertyDescription
urlThe page pathname
sectionCatalog area: visualiser, discover, directory, schemas, custom-docs, docs, home, or other
resource_typeOne of: service, event, command, query, domain, flow, channel, entity
resource_idThe resource identifier
resource_versionThe semver version

Analytics scripts load asynchronously and never block page rendering. If a provider fails, errors are caught silently so analytics never affect the catalog.

Configure a provider​

Add an integrations block to your eventcatalog.config.js. All providers are optional and can be combined.

Google Analytics 4​

eventcatalog.config.js
export default {
  // ...
  integrations: {
    ga4: {
      measurementId: 'G-XXXXXXXXXX',
    },
  },
};

Google Tag Manager​

eventcatalog.config.js
export default {
  // ...
  integrations: {
    gtm: {
      tagId: 'GTM-XXXXXXX',
    },
  },
};

PostHog​

eventcatalog.config.js
export default {
  // ...
  integrations: {
    posthog: {
      apiKey: 'phc_XXXXXXXXXXXX',
      // Optional: defaults to US cloud
      apiHost: 'https://us.i.posthog.com',
    },
  },
};

Use multiple providers​

Providers can be combined in a single integrations block.

eventcatalog.config.js
export default {
  // ...
  integrations: {
    ga4: {
      measurementId: 'G-XXXXXXXXXX',
    },
    gtm: {
      tagId: 'GTM-XXXXXXX',
    },
    posthog: {
      apiKey: 'phc_XXXXXXXXXXXX',
    },
  },
};

Enable debug mode​

Set debug: true to log all analytics events to the browser console. This is useful for verifying that events are being sent correctly before deploying.

eventcatalog.config.js
export default {
  // ...
  integrations: {
    debug: true,
    ga4: {
      measurementId: 'G-XXXXXXXXXX',
    },
  },
};

All events will appear in the browser console prefixed with [EventCatalog Analytics], including adapter registration, page views, and any custom events.

Track custom events​

The analytics manager is exposed on window.__ec_analytics. Use it to send custom events from your own scripts or MDX pages.

if (window.__ec_analytics) {
  window.__ec_analytics.track('custom_event', { key: 'value' });
}

Custom events are forwarded to all configured providers simultaneously.

Missing an integration?​

If you need support for an analytics provider not listed here, open a GitHub issue or join the Discord community and let us know. We are always looking to expand our integrations based on what teams are using.

Scale plan required

Analytics integrations require an EventCatalog Scale plan. If you configure integrations without a valid license, a warning is shown during build.