Skip to content

Add Amplitude plugin v1.1.0 for monitoring product analytics data - #106

Open
conor-richey wants to merge 2 commits into
squaredup:mainfrom
conor-richey:add-amplitude-plugin
Open

Add Amplitude plugin v1.1.0 for monitoring product analytics data#106
conor-richey wants to merge 2 commits into
squaredup:mainfrom
conor-richey:add-amplitude-plugin

Conversation

@conor-richey

@conor-richey conor-richey commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

🔌 Plugin overview

  • Plugin name: Amplitude
  • Purpose / problem solved: Monitor an Amplitude product analytics project from within SquaredUp — track active/new user trends, event volume trends, cohorts, and look up individual user activity, without switching tools.
  • Primary audience (e.g. platform teams, SREs, product teams): Product teams and analysts who use Amplitude for product analytics and want that data surfaced alongside their other SquaredUp dashboards.
  • Authentication method(s) (e.g. OAuth, Username/Password, API Key): API Key + Secret Key (Basic Auth), scoped per-project, with a US/EU region selector for data residency.

🖼️ Plugin screenshots

Plugin configuration

image

Default dashboards

image image image

🧪 Testing

  • Configured the plugin against a live Amplitude project (US/EU — note which) and validated the connection succeeds.
  • Verified Event Types and Cohorts import correctly as objects.
  • Checked the Overview, Event Type, and Cohort dashboards render with live data.
  • Ran the two-step user lookup flow (User Search → User Activity) end-to-end.

⚠️ Known limitations

  • One Amplitude project per plugin instance (API keys are project-scoped) — multiple projects need multiple plugin instances.
  • Funnel and retention analysis aren't included; this version covers active users, event trends, cohorts, and user lookups only.
  • User lookup is a manual two-step process (search, then copy the returned Amplitude ID into User Activity) — Amplitude has no endpoint to look up a user directly by email/User ID, and SquaredUp's dashboard framework can't auto-bind a search result into another tile.
  • Hidden/visibility-restricted taxonomy items in Amplitude don't appear in imported Event Types.
  • Amplitude enforces a concurrency limit (5 requests) and a cost-based hourly limit — very frequent refreshes across many tiles may hit HTTP 429.

📚 Checklist

  • Plugin, datastream and UI naming follow SquaredUp guidelines
  • Logo added
  • One or more dashboards added
  • README added including configuration guidance
  • No secrets or credentials included
  • I agree to the Code of Conduct

Summary by CodeRabbit

  • New Features
    • Added Amplitude integration with regional configuration and API credential setup.
    • Added authentication validation with region- and credential-specific feedback.
    • Added access to active-user trends, real-time users, event counts, event types, properties, cohorts, user activity, and user search.
    • Added Overview, Event Type, and Cohort dashboards with filtering, trends, and detailed analytics.
    • Added indexed event types and cohorts for easier discovery.
  • Documentation
    • Added setup guidance, dashboard details, supported analytics, and known limitations.

@conor-richey
conor-richey requested a review from a team August 5, 2026 11:06
@coderabbitai

coderabbitai Bot commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository UI (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: e8b06dfa-a606-4d05-90f5-12b05c688b07

📥 Commits

Reviewing files that changed from the base of the PR and between c4fc849 and 823b34c.

📒 Files selected for processing (9)
  • plugins/Amplitude/v1/dataStreams/cohortEventHistory.json
  • plugins/Amplitude/v1/dataStreams/eventCountHistory.json
  • plugins/Amplitude/v1/dataStreams/scripts/eventCountHistory.js
  • plugins/Amplitude/v1/dataStreams/userActivity.json
  • plugins/Amplitude/v1/dataStreams/userSearch.json
  • plugins/Amplitude/v1/dataStreams/validateAuth.json
  • plugins/Amplitude/v1/defaultContent/cohortOverview.dash.json
  • plugins/Amplitude/v1/defaultContent/eventTypeOverview.dash.json
  • plugins/Amplitude/v1/ui.json

📝 Walkthrough

Walkthrough

The PR adds the Amplitude plugin with authentication, regional API configuration, analytics data streams, indexed object mappings, and three dashboard views.

Changes

Amplitude plugin contracts and configuration

Layer / File(s) Summary
Plugin contracts and configuration
plugins/Amplitude/v1/metadata.json, plugins/Amplitude/v1/ui.json, plugins/Amplitude/v1/configValidation.json, plugins/Amplitude/v1/custom_types.json, plugins/Amplitude/v1/indexDefinitions/default.json, plugins/Amplitude/v1/defaultContent/scopes.json, plugins/Amplitude/v1/docs/README.md, plugins/Amplitude/v1/dataStreams/validateAuth.json
Defines regional API authentication, required configuration fields, authentication validation, custom types, indexed event types and cohorts, dashboard scopes, plugin documentation, and the auth validation stream.

Catalog and user data streams

Layer / File(s) Summary
Catalog and user data streams
plugins/Amplitude/v1/dataStreams/eventTypes.json, plugins/Amplitude/v1/dataStreams/eventProperties.json, plugins/Amplitude/v1/dataStreams/cohorts.json, plugins/Amplitude/v1/dataStreams/userSearch.json, plugins/Amplitude/v1/dataStreams/userActivity.json
Adds streams for event types, event properties, cohorts, user search, and recent user activity. The streams define Amplitude requests, inputs, response metadata, and visibility settings.

Analytics streams and transformations

Layer / File(s) Summary
Analytics streams and transformations
plugins/Amplitude/v1/dataStreams/activeUsersHistory.json, plugins/Amplitude/v1/dataStreams/scripts/activeUsersHistory.js, plugins/Amplitude/v1/dataStreams/eventCountHistory.json, plugins/Amplitude/v1/dataStreams/scripts/eventCountHistory.js, plugins/Amplitude/v1/dataStreams/cohortEventHistory.json, plugins/Amplitude/v1/dataStreams/scripts/cohortEventHistory.js, plugins/Amplitude/v1/dataStreams/realtimeActiveUsers.json, plugins/Amplitude/v1/dataStreams/scripts/realtimeActiveUsers.js
Adds historical active-user, event-count, cohort event-history, and real-time active-user streams. Transformation scripts convert Amplitude response arrays into row-based records and handle grouped, incomplete, or missing values.

Dashboard views and navigation

Layer / File(s) Summary
Dashboard views and navigation
plugins/Amplitude/v1/defaultContent/overview.dash.json, plugins/Amplitude/v1/defaultContent/eventTypeOverview.dash.json, plugins/Amplitude/v1/defaultContent/cohortOverview.dash.json, plugins/Amplitude/v1/defaultContent/manifest.json
Adds overview, event type, and cohort dashboards. The dashboards configure metric tiles, tables, filters, charts, user lookup, and dashboard registration.

Sequence Diagram(s)

sequenceDiagram
  participant OverviewDashboard
  participant AmplitudeDataStream
  participant AmplitudeAPI
  participant ResponseScript
  OverviewDashboard->>AmplitudeDataStream: request history or realtime data
  AmplitudeDataStream->>AmplitudeAPI: send configured Amplitude request
  AmplitudeAPI-->>AmplitudeDataStream: return parallel dates and series
  AmplitudeDataStream->>ResponseScript: transform response arrays
  ResponseScript-->>OverviewDashboard: return row-based records
Loading
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly identifies the addition of the Amplitude plugin and its product analytics monitoring purpose.
Description check ✅ Passed The description covers the plugin purpose, configuration, screenshots, testing, limitations, and contributor checklist for a new plugin.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches 💡 1
🛠️ Fix failing CI checks 💡
  • Create stacked PR
  • Commit on current branch

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 8

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@plugins/Amplitude/v1/custom_types.json`:
- Line 4: Rename the Amplitude source types from plugin-prefixed names to the
upstream terms Event Type and Cohort in plugins/Amplitude/v1/custom_types.json
at lines 4-4 and 11-11. Update every matching sourceType reference in
plugins/Amplitude/v1/defaultContent/scopes.json at lines 5-5 and 17-17, plus all
corresponding data stream matchers under plugins/Amplitude/v1, so all references
use the renamed values consistently.

In `@plugins/Amplitude/v1/dataStreams/eventCountHistory.json`:
- Line 11: Move the request-object transformations into map definitions before
getArgs: in plugins/Amplitude/v1/dataStreams/eventCountHistory.json lines 11-11,
map the optional group-by event property and bind the resulting JSON value in
the HTTP query; in plugins/Amplitude/v1/dataStreams/cohortEventHistory.json
lines 11-12, map the event-type and cohort-segment JSON values and bind them in
the query. Remove the embedded IIFE and complex mustache transformations while
preserving the existing request payloads.

In `@plugins/Amplitude/v1/dataStreams/eventTypes.json`:
- Around line 27-31: Replace the mustache-style valueExpression-based label
derivations with map transformations at both affected data stream definitions:
in plugins/Amplitude/v1/dataStreams/eventTypes.json#L27-L31, update the label
mapping to use map while preserving the existing display_name fallback to
event_type; in plugins/Amplitude/v1/dataStreams/eventProperties.json#L22-L26,
map event_property to name using map instead of valueExpression.

In `@plugins/Amplitude/v1/dataStreams/scripts/eventCountHistory.js`:
- Around line 20-27: Update the single-series branch in the event count
transformation so grouped requests retain the corresponding group label instead
of assigning groupValue to null. Determine whether grouping is active from the
available grouping metadata or request context, and map the one series to its
one label while preserving the existing ungrouped output shape.

In `@plugins/Amplitude/v1/dataStreams/userSearch.json`:
- Around line 16-22: Add example placeholders to both required text inputs: in
plugins/Amplitude/v1/dataStreams/userSearch.json lines 16-22, update the
identifier field with a neutral example such as user@example.com; in
plugins/Amplitude/v1/dataStreams/userActivity.json lines 19-25, add a numeric
Amplitude ID example such as 123456789. Preserve the existing validation and
help text.

In `@plugins/Amplitude/v1/dataStreams/validateAuth.json`:
- Line 3: Update the data stream displayName from the action-oriented “Validate
Auth” to a noun-based name such as “Authentication Validation,” while leaving
the stream behavior unchanged.

In `@plugins/Amplitude/v1/defaultContent/eventTypeOverview.dash.json`:
- Around line 113-116: Remove the hard-coded Amplitude taxonomy defaults from
plugins/Amplitude/v1/defaultContent/eventTypeOverview.dash.json lines 113-116 by
eliminating the default groupByProperty value "[Amplitude] Element Text"; also
remove the default eventType value "Dashboard Loaded" from
plugins/Amplitude/v1/defaultContent/cohortOverview.dash.json lines 76-78,
leaving these selections user-driven or plugin-validated.

In `@plugins/Amplitude/v1/ui.json`:
- Around line 23-38: Add neutral, non-secret example placeholder values to both
password fields identified by the apiKey and secretKey names in the UI
configuration. Keep the existing labels, help text, and required validation
unchanged, and ensure the placeholders are illustrative examples rather than
real credentials.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 83dff1c5-adcf-49be-a6d9-011b4afa4fb7

📥 Commits

Reviewing files that changed from the base of the PR and between 55b2cfc and c4fc849.

⛔ Files ignored due to path filters (1)
  • plugins/Amplitude/v1/icon.svg is excluded by !**/*.svg
📒 Files selected for processing (25)
  • plugins/Amplitude/v1/configValidation.json
  • plugins/Amplitude/v1/custom_types.json
  • plugins/Amplitude/v1/dataStreams/activeUsersHistory.json
  • plugins/Amplitude/v1/dataStreams/cohortEventHistory.json
  • plugins/Amplitude/v1/dataStreams/cohorts.json
  • plugins/Amplitude/v1/dataStreams/eventCountHistory.json
  • plugins/Amplitude/v1/dataStreams/eventProperties.json
  • plugins/Amplitude/v1/dataStreams/eventTypes.json
  • plugins/Amplitude/v1/dataStreams/realtimeActiveUsers.json
  • plugins/Amplitude/v1/dataStreams/scripts/activeUsersHistory.js
  • plugins/Amplitude/v1/dataStreams/scripts/cohortEventHistory.js
  • plugins/Amplitude/v1/dataStreams/scripts/eventCountHistory.js
  • plugins/Amplitude/v1/dataStreams/scripts/realtimeActiveUsers.js
  • plugins/Amplitude/v1/dataStreams/userActivity.json
  • plugins/Amplitude/v1/dataStreams/userSearch.json
  • plugins/Amplitude/v1/dataStreams/validateAuth.json
  • plugins/Amplitude/v1/defaultContent/cohortOverview.dash.json
  • plugins/Amplitude/v1/defaultContent/eventTypeOverview.dash.json
  • plugins/Amplitude/v1/defaultContent/manifest.json
  • plugins/Amplitude/v1/defaultContent/overview.dash.json
  • plugins/Amplitude/v1/defaultContent/scopes.json
  • plugins/Amplitude/v1/docs/README.md
  • plugins/Amplitude/v1/indexDefinitions/default.json
  • plugins/Amplitude/v1/metadata.json
  • plugins/Amplitude/v1/ui.json

Comment thread plugins/Amplitude/v1/custom_types.json
Comment thread plugins/Amplitude/v1/dataStreams/eventCountHistory.json Outdated
Comment thread plugins/Amplitude/v1/dataStreams/eventTypes.json
Comment thread plugins/Amplitude/v1/dataStreams/scripts/eventCountHistory.js Outdated
Comment thread plugins/Amplitude/v1/dataStreams/userSearch.json
Comment thread plugins/Amplitude/v1/dataStreams/validateAuth.json Outdated
Comment thread plugins/Amplitude/v1/defaultContent/eventTypeOverview.dash.json
Comment thread plugins/Amplitude/v1/ui.json
- Fix eventCountHistory grouping bug: determine grouped vs ungrouped
  from context.config.groupByProperty instead of series.length, which
  incorrectly dropped the group label whenever a grouped property only
  returned one distinct value.
- Simplify getArgs request construction in eventCountHistory.json and
  cohortEventHistory.json, dropping an embedded IIFE and a redundant
  Array.isArray check (autocomplete fields always return an array).
- Rename validateAuth stream display name to noun-based
  'Authentication Validation'.
- Add example placeholders to userSearch, userActivity, and the
  plugin's apiKey/secretKey fields.
- Remove hardcoded, project-specific default values (a SquaredUp
  internal event property and event name) from the Event Type and
  Cohort overview dashboards.

Not applying two other suggestions from the same review pass:
- Renaming 'Amplitude Event Type'/'Amplitude Cohort' source types to
  drop the plugin-name prefix goes against the established convention
  used by every other multi-object-type plugin in this repo.
- No 'map' transformation mechanism exists in this plugin schema for
  eventTypes/eventProperties valueExpression columns; the current
  fallback ternary matches the documented pattern.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant