Telemetry

Overview

Mercur collects anonymous usage data from the CLI tools and from running Mercur servers. It tells the maintainers how many installations exist, which versions of Mercur, Medusa and Node they run, which first-party plugins they use, and whether new installations keep running. That is what decides which upgrade paths to keep working and which features to invest in. Collection is on by default and can be turned off in one line. Nothing that identifies a company, a person, a shop or a URL ever leaves your machine.

Principles

Random ids only. A running server is identified by a random UUID stored in its own database. A developer machine is identified by a random UUID in the CLI config file. No hardware ids, no hostnames, no IP geolocation ($geoip_disable is set on every event).
Counts are ranges. Entity counts are sent as one of 0, 1-10, 11-100, 101-1k, 1k-10k, 10k-100k, 100k+. Exact numbers never leave.
Only first-party names. Plugin, module and provider names are reported only when they start with @mercurjs/ or @medusajs/. Anything else is counted (custom_plugin_count), never named. Block names are reported only for the official @mercurjs registry.
Never in the way. Every request has a 2 s timeout and every failure is swallowed. Nothing is sent from CI, from test runs, or from Medusa worker processes.
Auditable. Set MERCUR_TELEMETRY_DEBUG=true and every payload is printed instead of sent, so you can see exactly what would leave your machine.

How to opt out

Any one of these disables telemetry everywhere (CLI and server):

export MERCUR_DISABLE_TELEMETRY=true
# or the cross-tool convention
export DO_NOT_TRACK=1

For the server only, in medusa-config.ts:

module.exports = withMercur({
  projectConfig: {
    mercur: { telemetry: false },
  },
})

For the CLI only:

bunx @mercurjs/cli@latest telemetry --disable   # persists in ~/.config/mercur/config.json
bunx @mercurjs/cli@latest telemetry             # show current status
bunx @mercurjs/cli@latest telemetry --enable

Where data goes

Events are sent to https://telemetry.mercurjs.com, a service operated by the Mercur team. The data is stored securely, used only in aggregate to guide development, and never shared with third parties or used to identify an installation or a person.

What the server sends

Events

Event	When
`instance_started`	A few seconds after the HTTP server starts. Not sent by worker processes, migrations or `medusa exec`.
`instance_heartbeat`	Once every 24 hours (plus up to an hour of jitter). With several replicas on one database only one of them sends.
`instance_upgraded`	When a heartbeat sees a different `@mercurjs/core` version than the previous one. Carries `from_version` and `to_version`.
`installation_milestone`	The first time an installation reaches one of the milestones below. Carries `milestone` and `days_since_install`. Never carries ids, names or amounts.

Milestones: first_production_boot, first_seller, first_seller_approved, first_member_invited, first_offer, first_product_published, first_order, first_payout_account, first_payout_paid, first_commission_rule.

Properties

Group	Properties
Identity	`schema_version`, `source` (`server`), `installation_id` (random UUID), `project_id` (salted SHA-256 of the git remote URL, or of the working directory when there is no remote), `instance_age_days`, `demo_data` (`true` when `create-mercur-app` seeded the demo catalog into this database; it never clears)
Versions	`mercur_version`, `medusa_version`, `node_version`, `runtime` (`node` or `bun`), `package_manager`, `postgres_version` (major only)
Environment	`node_env`, `os`, `arch`, `cpu_count`, `total_memory_gb`, `containerized`, `cloud_provider` (detected from well-known environment variables), `worker_mode`, `redis_enabled`, `uptime_seconds`
Stack	`plugins`, `custom_plugin_count`, `modules`, `custom_module_count`, `payment_providers`, `payout_provider`, `notification_providers`, `file_provider`, `search_provider`, `feature_flags`, `admin_disabled`
Marketplace (ranges)	`sellers_total`, `sellers_pending`, `sellers_open`, `sellers_suspended`, `members_total`, `products_total`, `products_published`, `products_proposed`, `offers_total`, `product_changes_pending`, `order_groups_total`, `order_groups_last_30d`, `orders_total`, `payouts_paid`, `payouts_failed`, `payout_accounts_active`, `commission_rules_total`, `regions_total`, `currencies_total`, `sales_channels_total`

What the CLI sends

Applies to @mercurjs/cli and create-mercur-app.

Event	When	Extra properties
`cli_command_executed`	Every command	`command`, `flags` (flag names; values kept only for booleans and fixed choices, otherwise `<redacted>`), `exit_code`, `duration_ms`, `error_category` (`network`, `fs`, `validation`, `registry`, `install`, `database`, `unknown`)
`project_created`	`create-mercur-app` finished	`template`, `package_manager`, `with_storefront`, `skip_db`
`block_added`	`mercurjs add` succeeded	`block` (official registry only, otherwise `<custom-registry>`), `registry_kind`, `overwrite`

Properties on every CLI event: schema_version, source, cli_version, mercur_version, medusa_version, node_version, runtime, package_manager, os, arch, is_src_dir, is_ci, is_tty, is_agent (whether an AI coding agent is driving the terminal), is_docker, is_wsl, cloud_provider, project_id.

What is never collected

Source code, file names, directory structure or configuration files
Email addresses or any personal data (the optional email prompt was removed)
URLs, hostnames, IP addresses or geolocation
Names of custom plugins, modules, providers, routes or blocks from private registries
Exact entity counts, order values, or anything tied to a seller, customer or order

Welcome

Use cases

Legal

Overview

Principles

How to opt out

Where data goes

What the server sends

Events

Properties

What the CLI sends

What is never collected

​Overview

​Principles

​How to opt out

​Where data goes

​What the server sends

​Events

​Properties

​What the CLI sends

​What is never collected

Overview

Principles

How to opt out

Where data goes

What the server sends

Events

Properties

What the CLI sends

What is never collected