Analytics integrations

Introduction

An integration connects your organization to an analytics tool and marks every experiment run on the tool's charts: a marker when a run starts, when its split changes, when a variation is shipped and when the run is stopped. The markers land next to the metrics the run is meant to move, so the team reads the chart without looking up when each change happened. ConfigDirector offers integrations for Amplitude, Mixpanel, Datadog, Grafana and PostHog.

You give the integration the tool's own settings, such as the data center or the project id, and the credential the tool uses to authenticate. ConfigDirector composes the request from them, posts a marker for each run event, retries failures for about ten hours and keeps every delivery on record for 30 days. Nothing runs in your application: to also report which variation each user saw, the analytics pages have the handler to copy.

Integrations belong to the organization, and only owners and admins can see and manage them. They work the same on Free and Pay as you go. An organization can have up to 10 integrations, counted apart from its webhooks.

What a marker says

Each run event becomes one marker. The marker's title is the config key and the environment name, checkout-cta-copy · Production, and its text says what happened and who did it, followed by the config's URL in the dashboard:

• Run started: control 50%, treatment-a 50% by Dana Whitfield, with each rollout's shares, , in <conditions> after a conditional rollout's shares, and ; between rollouts
• Split changed: control 60%, treatment-a 40% by Dana Whitfield
• Shipped treatment-a by Deploy bot
• Stopped by Dana Whitfield

The marker's time is the moment the run event happened, in the tool's own format. Each tool shows the title and the text its own way; the section for your tool below says where the marker appears.

Creating an integration

1. Open Integrations at the bottom of the dashboard's navigation and pick the tool, or click Add integration when you already have one.
2. Give the integration a name, or keep the tool's name.
3. Fill in the tool's settings and paste the credential you created in the tool. The section for your tool below lists both and says where to create the credential. Credentials are stored encrypted and never shown again.
4. Narrow it down with the Projects, Environments and Tags filters, or leave them empty to mark every run. A run is marked when its project, its environment and its config's tags pass every filter you set; an empty filter lets everything through. An integration filtered to Production marks Production runs only.
5. Keep Enabled on. A disabled integration marks nothing, and runs that start or end while it is disabled are not marked later.
6. Save. The integration's page shows the tool's settings and the address it posts to.
7. Click Send test marker and confirm. A marker titled ConfigDirector test is posted to the tool right away, at the current time, and shows under Deliveries with the tool's response, so you can see where run markers will land.

An integration receives the four experiment run events and nothing else: no change events and no alerts. To receive those, create a webhook.

Amplitude

The integration posts to https://amplitude.com/api/3/annotations, or https://analytics.eu.amplitude.com/api/3/annotations on the EU data center, authenticated with the two keys as HTTP Basic credentials. Set an endpoint URL under Advanced only to post somewhere else.

The marker shows on every chart of the Amplitude project, with the title as its label and the text as its details. The body sent is { "label", "start", "details" }, with start in ISO 8601; no chart_id is sent, so the annotation is project-wide. Amplitude's documentation: Chart Annotations API.

Mixpanel

The integration posts to https://mixpanel.com/api/app/projects/{projectId}/annotations, with eu.mixpanel.com or in.mixpanel.com in place of mixpanel.com on the EU or India data residency, authenticated with the service account as HTTP Basic credentials. Set an endpoint URL under Advanced only to post somewhere else.

The marker shows on the project's charts, with the title and the text as its description. The body sent is { "date", "description" }, with date as YYYY-MM-DD HH:mm:ss in UTC. Mixpanel's documentation: Create annotation.

Datadog

The integration posts to https://event-management-intake.{site}/api/v2/events with the key in the DD-API-KEY header. Set an endpoint URL under Advanced only to post somewhere else.

The marker is a change event in Datadog's event stream and on dashboards that show events, tagged source:configdirector, config:<key> and environment:<slug>, with the config as the changed feature flag and the member as the author. Datadog's documentation: Post an event.

Grafana

The integration posts to {Grafana URL}/api/annotations with the token as a Bearer token. Set an endpoint URL under Advanced only to post somewhere else.

The marker is an organization-wide annotation, shown on dashboards whose annotation settings include it, tagged configdirector, the config key and the environment slug. The body sent is { "text", "time", "tags" }, with time in epoch milliseconds; no dashboardUID is sent. Grafana's documentation: Annotations API.

PostHog

The integration posts to https://us.posthog.com/api/projects/{projectId}/annotations/, https://eu.posthog.com/… on PostHog Cloud EU, or {host}/api/projects/{projectId}/annotations/ on a self-hosted PostHog, with the key as a Bearer token. Set an endpoint URL under Advanced only to post somewhere else.

The marker is a project-scoped annotation, shown on the project's insights. The body sent is { "content", "date_marker", "scope": "project" }, with date_marker in ISO 8601. PostHog's documentation: Annotations.

Google Analytics 4 and Segment

Integrations are not offered for Google Analytics 4 or Segment: Google Analytics 4 has no key an integration could hold to post an annotation, and Segment has no charts to mark. The analytics pages show how to report exposures to each tool from your application instead.

Endpoint URL override

ConfigDirector composes the address it posts to from the tool's settings, and the integration's page shows it under Posts to. If the tool moves its API before ConfigDirector does, or you route the markers through a gateway of your own, open Advanced on the integration's form and set an Endpoint URL. It replaces the composed address entirely, while the credential is still sent the same way. The URL follows the webhook URL rules: https:// and a host that resolves to a public address. A Grafana URL and a self-hosted PostHog host follow the same rules. Leave the field empty to go back to the composed address.

Editing an integration

The integration's page shows when its credentials were saved and by whom; the values are never shown again. When you edit the integration, the credentials show as saved: leave them alone to keep them, or click Replace and paste the new ones. The keys of an Amplitude or Mixpanel integration are replaced together. Changing a setting, such as the data center or the project id, moves the markers to the new address from the next run event on. The tool cannot change: create another integration for another tool.

Delivery

Deliveries follow the same rules as webhook deliveries: a marker is normally posted within a few seconds of the run event, succeeds when the tool answers with any 2xx status within 10 seconds, and is otherwise retried over about ten and a half hours before it is failed. The request also carries the Standard Webhooks headers, which the tools ignore.

The integration's page lists its Deliveries from the last 30 days, newest first, with Failures only to show just the failed ones. Each delivery shows the run event, its status, the number of attempts and the latest attempt's result, and expands to the body posted to the tool and the first 1 KB of the tool's response or the connection error. Resend posts a delivery's body again right away; if that attempt fails, the delivery is marked failed and is not tried again on its own.

When an integration is disabled

An owner or admin can disable an integration from its page. ConfigDirector also disables an integration on its own when deliveries to it were attempted on each of the last three days and none of them succeeded, which usually means the tool rejects the credential. Then it:

• abandons the deliveries still waiting for an attempt,
• marks the integration Disabled in the list, saying it was disabled after repeated failures, and shows the tool's last response on its page,
• raises the Webhook disabled after repeated failures alert, naming the integration.

While an integration is disabled, nothing is posted, and enabling it again does not mark the runs that started or ended in between. Replace the credential or fix the settings from Edit, then click Enable on the integration's page; the alert resolves when the integration is enabled again or deleted.

Limits

Managing integrations with the Admin API

Everything on the Integrations page is also available through the Admin API: listing, creating, updating and deleting integrations, sending a test marker, listing deliveries and resending one. The API token needs the integrations:manage permission, which only owners and admins can grant.