Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions cmd/root.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)")
Expand All @@ -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")
Expand Down
22 changes: 22 additions & 0 deletions cmd/root_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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
Expand Down
27 changes: 22 additions & 5 deletions docs/development/telemetry.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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 <command>`
- 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:
Expand Down
20 changes: 19 additions & 1 deletion docs/user-guide/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand Down
9 changes: 9 additions & 0 deletions internal/config/constants.go
Original file line number Diff line number Diff line change
Expand Up @@ -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_"
Expand Down
96 changes: 96 additions & 0 deletions internal/telemetry/serverzone.go
Original file line number Diff line number Diff line change
@@ -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
}
}
Comment thread
ajalon1 marked this conversation as resolved.

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
}
}
111 changes: 111 additions & 0 deletions internal/telemetry/serverzone_test.go
Original file line number Diff line number Diff line change
@@ -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())
}
5 changes: 3 additions & 2 deletions internal/telemetry/telemetry.go
Original file line number Diff line number Diff line change
Expand Up @@ -100,10 +100,11 @@ func NewClient(props *CommonProperties) *Client {

config := amplitude.NewConfig(AmplitudeAPIKey)
config.Logger = &amplitudeLogger{}
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,
Expand Down
Loading