diff --git a/cmd/root.go b/cmd/root.go index 2a8ded8d1..332d692bb 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -240,6 +240,8 @@ func init() { RootCmd.PersistentFlags().Duration("plugin-update-check-interval", internalPlugin.DefaultUpdateCheckInterval, "cooldown between plugin update checks (0s disables)") RootCmd.PersistentFlags().Bool("skip-plugin-update-check", false, "skip plugin update checks before running plugins") RootCmd.PersistentFlags().Bool("disable-telemetry", false, "disable usage telemetry") + RootCmd.PersistentFlags().String("telemetry-server-zone", "", + "Amplitude ingest region for telemetry (US or EU; inferred from endpoint if unset)") // Private CA / TLS flags RootCmd.PersistentFlags().BoolP("skip-certificate-check", "k", false, "skip TLS certificate verification (insecure)") @@ -252,6 +254,7 @@ func init() { // To add a new universal flag, call bindUniversal here next to its registration above. bindUniversal("debug") bindUniversal("disable-telemetry") + bindUniversal("telemetry-server-zone") bindUniversal("verbose") bindUniversal("skip-certificate-check") bindUniversal("ca-cert") diff --git a/cmd/root_test.go b/cmd/root_test.go index 0c2a0ec4b..556e939bc 100644 --- a/cmd/root_test.go +++ b/cmd/root_test.go @@ -18,6 +18,7 @@ import ( "bytes" "testing" + "github.com/datarobot/cli/internal/config" "github.com/datarobot/cli/internal/misc/reader" "github.com/datarobot/cli/internal/telemetry" "github.com/datarobot/cli/internal/tools" @@ -415,6 +416,27 @@ func TestUniversalFlagsParsedOnCoreSubcommand(t *testing.T) { "--debug must be parsed by core when it appears after a core subcommand and its own flags") } +// TestTelemetryServerZoneFlagRegistered verifies that --telemetry-server-zone +// is registered as a persistent root flag and marked universal so it is +// forwarded to plugin subprocesses as DATAROBOT_CLI_TELEMETRY_SERVER_ZONE. +// This lets plugins that emit their own telemetry honor the user's +// data-residency preference, and keeps behavior consistent with the +// --disable-telemetry universal flag and the Codespace env-injection path +// (CFX-6328). See the design decision recorded on CFX-6327. This guard fails +// if the flag is removed or the universal annotation is dropped. +func TestTelemetryServerZoneFlagRegistered(t *testing.T) { + flag := RootCmd.PersistentFlags().Lookup("telemetry-server-zone") + require.NotNil(t, flag, "--telemetry-server-zone should always be registered as a persistent root flag") + + require.NotNil(t, flag.Annotations, "--telemetry-server-zone should carry universal-flag annotations") + + suffix, isUniversal := flag.Annotations[config.UniversalAnnotationKey] + require.True(t, isUniversal, + "--telemetry-server-zone must be a universal flag (forwarded to plugin subprocesses)") + require.Equal(t, []string{"TELEMETRY_SERVER_ZONE"}, suffix, + "--telemetry-server-zone universal env-var suffix should be TELEMETRY_SERVER_ZONE") +} + // TestShowFirstRunAnimationSkipsWhenNonInteractive guards against tools like // `expect` (used by the smoke test suite) attaching a real pty to dr's // stdout: that would satisfy the TTY check and trigger the animation right diff --git a/docs/development/telemetry.md b/docs/development/telemetry.md index 0d29675d1..f815a49e9 100644 --- a/docs/development/telemetry.md +++ b/docs/development/telemetry.md @@ -2,7 +2,7 @@ The CLI collects usage analytics linked to your DataRobot user ID via [Amplitude](https://amplitude.com/) to help the DataRobot team understand how the tool is used. Telemetry is an optional feature that can be turned off at any time (see [Configuring and disabling telemetry](#configuring-and-disabling-telemetry)). Telemetry is implemented in `internal/telemetry/`. -All telemetry data sent over the network is stored in the USA. When telemetry is disabled, every operation is a safe no-op — events are logged to the debug logger instead of being sent over the network. +All telemetry data sent over the network is stored in US-based or EU-based servers. When the telemetry feature is disabled, events are only logged locally. ## Configuring and disabling telemetry @@ -29,15 +29,32 @@ When telemetry is disabled, events are logged to the debug logger (visible with Telemetry makes outbound HTTPS requests to two services. In network-restricted environments (corporate proxies, firewalls, air-gapped CI), the following hosts must be allowlisted for telemetry to function: -| Host | Purpose | Port | -|------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|------| -| `api2.amplitude.com` | Amplitude HTTP API (US zone) — event ingestion | 443 | -| *configured DataRobot endpoint* (e.g. `app.datarobot.com`) | `GET /api/v2/account/info/` — fetches the `user_id`, `organization_id`, and `tenant_id` for event attribution | 443 | +1. `api2.amplitude.com:443` - Amplitude HTTP API (US zone) — event ingestion, default +2. `api.eu.amplitude.com:443` - Amplitude HTTP API (EU zone) — event ingestion, iff `ServerZone` is set to EU +3. *configured DataRobot endpoint* (e.g. `app.datarobot.com`) - `GET /api/v2/account/info/` — fetches the `user_id`, `organization_id`, and `tenant_id` for event attributionv The DataRobot endpoint call is only made when the user is authenticated and the cached account info is stale or absent (see [User ID](#user-id)). If that call fails due to network restrictions, telemetry falls back to `device_id`-only tracking — the CLI does not error. No other hosts are contacted by the telemetry subsystem. +## Server zone / data residency + +Amplitude operates separate ingestion endpoints for its US and EU data centers (`api2.amplitude.com` and `api.eu.amplitude.com` respectively). The CLI selects the endpoint at telemetry-client initialization via the SDK's `ServerZone` field, using this precedence: + +1. **Explicit override** — the `telemetry-server-zone` config key, settable via any of: + - Flag: `dr --telemetry-server-zone EU ` + - Environment variable: `DATAROBOT_CLI_TELEMETRY_SERVER_ZONE=EU` + - Config file: `telemetry-server-zone: EU` in `drconfig.yaml` + + When set to a valid value (`US` or `EU`, case-insensitive), this takes precedence over inference. +2. **Inferred from `datarobot_instance`** — if no override is set, the zone is inferred from the configured DataRobot endpoint URL. A host that contains `.eu.` or ends with `.eu` is treated as EU; everything else defaults to US. +3. **Invalid override** — a value other than `US`/`EU` logs a warning to `.dr-tui-debug.log` and falls back to the inferred zone. + +> [!NOTE] +> `--telemetry-server-zone` is a [universal flag](flags.md), forwarded to plugin subprocesses as `DATAROBOT_CLI_TELEMETRY_SERVER_ZONE` so plugins that emit their own telemetry can honor the user's data-residency preference. Plugins that don't emit telemetry simply ignore it. + +Additionally, the `telemetry-server-zone` setting only accepts `US` or `EU` values. Users in regions without a dedicated Amplitude data center (e.g., APAC/Japan) should disable telemetry as noted above. + ## Device ID Amplitude requires a `device_id` or `user_id` on every event. The CLI uses a stable device identifier obtained in this order: diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md index 5c57e6e33..ea4ed67b6 100644 --- a/docs/user-guide/configuration.md +++ b/docs/user-guide/configuration.md @@ -146,7 +146,7 @@ export DATAROBOT_API_CONSUMER_TRACKING_ENABLED=false ### Telemetry -The CLI collects usage analytics linked to your DataRobot user ID to help improve the tool. Telemetry is an optional feature that can be turned off at any time, and all telemetry data is stored in the USA. To disable telemetry: +The CLI collects usage analytics linked to your DataRobot user ID to help improve the tool. Telemetry is an optional feature that can be turned off at any time. By default telemetry data is stored in the USA; selecting the EU server zone stores it in the EU (see [Server zone (data residency)](#server-zone-data-residency) below). To disable telemetry: ```bash # Per-invocation @@ -162,6 +162,24 @@ disable-telemetry: true When telemetry is disabled, no data is sent over the network. See the [developer documentation](../development/telemetry.md) for details on what is collected and how the system works. +#### Server zone (data residency) + +By default the CLI infers the Amplitude ingest region (US or EU) from your configured DataRobot endpoint. To override it explicitly: + +```bash +# Per-invocation +dr --telemetry-server-zone EU templates list + +# Per-session (environment variable) +export DATAROBOT_CLI_TELEMETRY_SERVER_ZONE=EU + +# Permanently (config file) +# Add to ~/.config/datarobot/drconfig.yaml: +telemetry-server-zone: EU +``` + +Accepted values are `US` and `EU` (case-insensitive). An invalid value logs a warning to `.dr-tui-debug.log` and falls back to the inferred region. There is no APAC region — APAC users should disable telemetry instead. See [Server zone / data residency](../development/telemetry.md#server-zone--data-residency) for details. + ### Advanced flags The CLI supports advanced command-line flags for special use cases: diff --git a/internal/config/constants.go b/internal/config/constants.go index e703cfdd0..23aa9ee5c 100644 --- a/internal/config/constants.go +++ b/internal/config/constants.go @@ -32,6 +32,15 @@ const ( // either an LLM Gateway model id or a DataRobot deployment id. DefaultLLMID = "default-llm-id" + // TelemetryServerZone is the config key for the explicit Amplitude server + // zone override ("US" or "EU"). When unset, the telemetry package infers + // the zone from the configured DataRobot endpoint. Settable via the + // --telemetry-server-zone flag, the DATAROBOT_CLI_TELEMETRY_SERVER_ZONE + // env var, or the telemetry-server-zone config-file key. It is a universal + // flag (forwarded to plugin subprocesses) so plugins that emit their own + // telemetry can honor the user's data-residency preference. + TelemetryServerZone = "telemetry-server-zone" + // EnvPrefix is the canonical prefix for all DATAROBOT_CLI_* environment // variables. Use this constant instead of hard-coding the string literal. EnvPrefix = "DATAROBOT_CLI_" diff --git a/internal/telemetry/serverzone.go b/internal/telemetry/serverzone.go new file mode 100644 index 000000000..c75932baa --- /dev/null +++ b/internal/telemetry/serverzone.go @@ -0,0 +1,96 @@ +// Copyright 2026 DataRobot, Inc. and its affiliates. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package telemetry + +import ( + "net/url" + "strings" + + "github.com/amplitude/analytics-go/amplitude/types" + "github.com/datarobot/cli/internal/config" + "github.com/datarobot/cli/internal/config/viperx" + "github.com/datarobot/cli/internal/log" +) + +// euHostPatterns lists the host substrings that identify a DataRobot instance +// in the EU data-residency zone. The Amplitude SDK has no APAC data center, so +// only US and EU are meaningful here. To extend inference (e.g. a new EU host +// pattern), append to this slice — no other changes are required. +// +// A host is treated as EU when, after lowercasing, it either contains ".eu." +// or ends with ".eu". The trailing-dot variant avoids false positives on hosts +// such as "host.europe.datarobot.com". +var euHostPatterns = []string{".eu."} + +// inferServerZone derives the Amplitude ServerZone from a DataRobot base URL. +// EU-matching hosts return ServerZoneEU; everything else (including the empty +// string) defaults to ServerZoneUS. +func inferServerZone(baseURL string) types.ServerZone { + host := strings.ToLower(baseURL) + + // Match against the hostname (port-stripped) rather than the full URL so + // that an EU endpoint with an explicit port (e.g. "https://mytenant.eu:8443") + // still satisfies the ".eu" suffix rule. Fall back to the lowercased full + // string if parsing fails or no host is present. + if u, err := url.Parse(baseURL); err == nil && u.Hostname() != "" { + host = strings.ToLower(u.Hostname()) + } + + if strings.HasSuffix(host, ".eu") { + return types.ServerZoneEU + } + + for _, pattern := range euHostPatterns { + if strings.Contains(host, pattern) { + return types.ServerZoneEU + } + } + + return types.ServerZoneUS +} + +// resolveServerZone determines the Amplitude ServerZone to use at client +// initialization. An explicit override (flag, env var, or config file) takes +// precedence over the value inferred from the configured DataRobot endpoint. +// +// Precedence follows viper's own ordering (flag > env > config). An empty or +// whitespace-only override is treated as "unset" and falls back to inference. +// An invalid value (not "US" or "EU", case-insensitive) logs a warning to the +// debug log and falls back to the inferred zone rather than failing CLI +// execution — telemetry initialization must never block or error visibly. +func resolveServerZone() types.ServerZone { + inferred := inferServerZone(config.GetBaseURL()) + + raw := strings.TrimSpace(viperx.GetString(config.TelemetryServerZone)) + if raw == "" { + return inferred + } + + switch strings.ToUpper(raw) { + case "EU": + return types.ServerZoneEU + + case "US": + return types.ServerZoneUS + + default: + log.Warnf( + "invalid value %q for telemetry-server-zone (expected US or EU); falling back to inferred zone %s", + raw, inferred, + ) + + return inferred + } +} diff --git a/internal/telemetry/serverzone_test.go b/internal/telemetry/serverzone_test.go new file mode 100644 index 000000000..a4ec0f45e --- /dev/null +++ b/internal/telemetry/serverzone_test.go @@ -0,0 +1,111 @@ +// Copyright 2026 DataRobot, Inc. and its affiliates. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package telemetry + +import ( + "testing" + + "github.com/amplitude/analytics-go/amplitude/types" + "github.com/datarobot/cli/internal/config" + "github.com/datarobot/cli/internal/config/viperx" + "github.com/stretchr/testify/assert" +) + +func TestInferServerZone(t *testing.T) { + tests := []struct { + name string + baseURL string + want types.ServerZone + }{ + {name: "US default", baseURL: "https://app.datarobot.com", want: types.ServerZoneUS}, + {name: "EU subdomain", baseURL: "https://app.eu.datarobot.com", want: types.ServerZoneEU}, + {name: "Japan cloud routes to US (no APAC Amplitude DC)", baseURL: "https://app.jp.datarobot.com", want: types.ServerZoneUS}, + {name: "EU suffix", baseURL: "https://mytenant.eu", want: types.ServerZoneEU}, + {name: "EU suffix with explicit port", baseURL: "https://mytenant.eu:8443", want: types.ServerZoneEU}, + {name: "EU subdomain with explicit port", baseURL: "https://app.eu.datarobot.com:443", want: types.ServerZoneEU}, + {name: "EU segment with trailing dot", baseURL: "https://app.eu.datarobot.com/api/v2", want: types.ServerZoneEU}, + {name: "europe is not EU", baseURL: "https://host.europe.datarobot.com", want: types.ServerZoneUS}, + {name: "empty defaults to US", baseURL: "", want: types.ServerZoneUS}, + {name: "uppercase host matched case-insensitively", baseURL: "https://APP.EU.DATAROBOT.COM", want: types.ServerZoneEU}, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + assert.Equal(t, tc.want, inferServerZone(tc.baseURL)) + }) + } +} + +func TestResolveServerZone_EmptyUsesInferred(t *testing.T) { + viperx.Reset() + t.Cleanup(viperx.Reset) + + viperx.Set(config.DataRobotURL, "https://app.eu.datarobot.com") + + assert.Equal(t, types.ServerZoneEU, resolveServerZone()) +} + +func TestResolveServerZone_OverrideWinsOverInference(t *testing.T) { + viperx.Reset() + t.Cleanup(viperx.Reset) + + // EU endpoint, explicit US override → US. + viperx.Set(config.DataRobotURL, "https://app.eu.datarobot.com") + viperx.Set(config.TelemetryServerZone, "US") + + assert.Equal(t, types.ServerZoneUS, resolveServerZone()) + + // US endpoint, explicit EU override → EU. + viperx.Set(config.DataRobotURL, "https://app.datarobot.com") + viperx.Set(config.TelemetryServerZone, "EU") + + assert.Equal(t, types.ServerZoneEU, resolveServerZone()) +} + +func TestResolveServerZone_CaseInsensitive(t *testing.T) { + viperx.Reset() + t.Cleanup(viperx.Reset) + + viperx.Set(config.DataRobotURL, "https://app.datarobot.com") + + for _, val := range []string{"eu", "Eu", "eU"} { + viperx.Set(config.TelemetryServerZone, val) + + assert.Equal(t, types.ServerZoneEU, resolveServerZone(), + "override %q should resolve to EU", val) + } +} + +func TestResolveServerZone_InvalidFallsBackToInferred(t *testing.T) { + viperx.Reset() + t.Cleanup(viperx.Reset) + + // EU endpoint with an unsupported value (APAC has no Amplitude DC) → warn + // and fall back to the inferred EU zone, not a hard-coded US. + viperx.Set(config.DataRobotURL, "https://app.eu.datarobot.com") + viperx.Set(config.TelemetryServerZone, "APAC") + + assert.Equal(t, types.ServerZoneEU, resolveServerZone()) +} + +func TestResolveServerZone_WhitespaceOnlyTreatedAsUnset(t *testing.T) { + viperx.Reset() + t.Cleanup(viperx.Reset) + + viperx.Set(config.DataRobotURL, "https://app.datarobot.com") + viperx.Set(config.TelemetryServerZone, " ") + + assert.Equal(t, types.ServerZoneUS, resolveServerZone()) +} diff --git a/internal/telemetry/telemetry.go b/internal/telemetry/telemetry.go index 34bb223d3..5daeffdcb 100644 --- a/internal/telemetry/telemetry.go +++ b/internal/telemetry/telemetry.go @@ -100,10 +100,11 @@ func NewClient(props *CommonProperties) *Client { config := amplitude.NewConfig(AmplitudeAPIKey) config.Logger = &litudeLogger{} + config.ServerZone = resolveServerZone() - client := amplitude.NewClient(config) + log.Debug("Telemetry client initialized (Amplitude)", "server_zone", string(config.ServerZone)) - log.Debug("Telemetry client initialized (Amplitude)") + client := amplitude.NewClient(config) return &Client{ amp: client,