nat.utils.telemetry.config#

Configuration for NAT CLI telemetry.

Most values are evaluated once at import time. The TELEMETRY_ENABLED flag is module-level mutable: it starts at the value derived from the environment / persisted consent, and the CLI entrypoint may flip it after the first-run consent prompt resolves.

Resolution order for TELEMETRY_ENABLED (lazy: import-time + prompt):

  1. NAT_TELEMETRY_ENABLED env var, if set.

  2. Persisted consent at ~/.config/nat/telemetry.toml.

  3. False — until the CLI’s first-run prompt resolves to either ENABLED (TTY user said yes) or DISABLED (TTY user said no, or non-interactive session).

Environment variables#

  • NAT_TELEMETRY_ENABLED (no default — first-run prompt or persisted consent decides): master opt-out switch. Accepts 1/true/yes (case-insensitive); anything else disables.

  • NAT_TELEMETRY_ENDPOINT (default: https://events.telemetry.data.nvidia.com/v1.1/events/json): destination for telemetry payloads. The default points at the shared NeMo Usage Telemetry production ingest. Set to the empty string to build payloads locally without issuing any HTTP request, or to the literal value stdout to write JSON-line payloads to stderr for inspection.

  • NAT_SESSION_PREFIX (default: unset): optional prefix prepended to every session ID. Useful for tagging dev/CI runs.

  • NAT_TELEMETRY_DRY_RUN (default: false): when truthy, payloads are built and logged but no HTTP request is issued.

  • NAT_TELEMETRY_CONSENT_FILE (default: ~/.config/nat/telemetry.toml): override for the persisted consent file location. Primarily a testing hook.

Attributes#

NAT_TELEMETRY_VERSION

Identifier embedded in every event envelope as eventSysVer.

CLIENT_ID

Stable identifier for the NAT CLI client. Sent as clientId.

CPU_ARCHITECTURE

Captured once at import; reported as cpuArchitecture in payloads.

DEFAULT_NAT_TELEMETRY_ENDPOINT

STDOUT_ENDPOINT_SENTINEL

When NAT_TELEMETRY_ENDPOINT equals this value, payloads are written to

_TRUTHY

TELEMETRY_ENABLED

Master opt-out flag. Initialized at import; may be flipped by the

NAT_TELEMETRY_ENDPOINT

Resolved telemetry endpoint. May be a URL or STDOUT_ENDPOINT_SENTINEL.

NAT_TELEMETRY_DRY_RUN

When true, payloads are logged but no HTTP request is made.

SESSION_PREFIX

Functions#

_is_truthy(→ bool)

_resolve_initial_telemetry_enabled(→ bool)

Resolve the initial value at import time.

Module Contents#

NAT_TELEMETRY_VERSION = 'nat-telemetry/1.0'#

Identifier embedded in every event envelope as eventSysVer.

CLIENT_ID = '184482118588404'#

Stable identifier for the NAT CLI client. Sent as clientId.

Shared with the NeMo Usage Telemetry project — NAT events are tagged by nemoSource = "agent_toolkit" to distinguish them from sibling NeMo products’ events at query time.

CPU_ARCHITECTURE#

Captured once at import; reported as cpuArchitecture in payloads.

DEFAULT_NAT_TELEMETRY_ENDPOINT = 'https://events.telemetry.data.nvidia.com/v1.1/events/json'#
STDOUT_ENDPOINT_SENTINEL = 'stdout'#

When NAT_TELEMETRY_ENDPOINT equals this value, payloads are written to stderr as JSON lines instead of POSTed.

_TRUTHY = ('1', 'true', 'yes')#
_is_truthy(value: str | None, *, default: bool) → bool#
_resolve_initial_telemetry_enabled() → bool#

Resolve the initial value at import time.

Defers persisted-consent reading to consent.resolve_initial_consent so all the policy rules live in one place. The CLI entrypoint may later flip this flag via the consent prompt; consumers (handler, telemetry_hook) re-read the live value rather than caching it.

TELEMETRY_ENABLED: bool#

Master opt-out flag. Initialized at import; may be flipped by the first-run consent prompt during a CLI invocation. Consumers should access this attribute on the module rather than from … import TELEMETRY_ENABLED so the live value is honored.

NAT_TELEMETRY_ENDPOINT: str#

Resolved telemetry endpoint. May be a URL or STDOUT_ENDPOINT_SENTINEL.

NAT_TELEMETRY_DRY_RUN: bool = False#

When true, payloads are logged but no HTTP request is made.

SESSION_PREFIX: str | None#