Track CLI command-path and alias usage in x-elastic-client-meta telemetry
- Dominant language
- TypeScript
- Stars
- 41
- Forks
- 24
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 56
Description
## Context
The CLI now exposes multiple equivalent paths for many commands (see #229 and #282). Given the ongoing UX discussion around namespacing, we should capture which invocation style users actually choose before going live, so future design decisions are grounded in data rather than opinion.
This is a sub-issue of #272.
---
## What to track
### 1. Command path used (string)
Include the canonical dot-path of the command actually invoked in `x-elastic-client-meta`. For example:
```
stack.es.indices.list
stack.kb.data-views.list
cloud.serverless.projects.search.create
cloud.hosted.deployments.list-deployments
```
This is always normalised to the **canonical path** regardless of which alias was typed (see §2 below).
### 2. Alias used (boolean flag)
Add a compact boolean field (e.g. `alias:true`) to `x-elastic-client-meta` when the user invoked the command via a shorthand alias rather than the canonical path. Josh's suggestion: _"assume they're using the long/fully qualified command path UNLESS we add a data point that they used an alias"_ — keep the field absent (or `false`) for canonical invocations to minimise header size.
---
## Full alias map for reference
### Stack — top-level shortcuts
| User types | Canonical path | Alias? |
|---|---|---|
| `elastic es …` | `stack es …` | yes |
| `elastic elasticsearch …` | `stack es …` | yes |
| `elastic kb …` | `stack kb …` | yes |
| `elastic kibana …` | `stack kb …` | yes |
| `elastic stack es …` | `stack es …` | no (canonical) |
| `elastic stack elasticsearch …` | `stack es …` | yes |
| `elastic stack kb …` | `stack kb …` | no (canonical) |
| `elastic stack kibana …` | `stack kb …` | yes |
### Cloud serverless — project type aliases
| User types | Canonical path | Alias? |
|---|---|---|
| `elastic cloud serverless projects search …` | `cloud.serverless.projects.search` | no (canonical) |
| `elastic cloud serverless projects elasticsearch …` | `cloud.serverless.projects.search` | yes |
### Cloud cross-cutting — promoted namespace renames
These are display-name renames; the underlying API namespace is always resolved to the canonical display name, so no alias flag is needed here — but the canonical dot-path (e.g. `cloud.trust`, `cloud.auth`) should be what appears in telemetry.
| Old API namespace | Canonical display name in telemetry |
|---|---|
| `accounts` | `cloud.trust` |
| `authentication` | `cloud.auth` |
| `organizations` | `cloud.orgs` |
| `user-role-assignments` | `cloud.users` |
| `billing-costs-analysis` | `cloud.billing` |
### Cloud hosted — namespace renames
| Old API namespace | Canonical display name in telemetry |
|---|---|
| `deployments-traffic-filter` | `cloud.hosted.traffic-filters` |
---
## Other data points worth capturing before GA
Beyond alias tracking, the following would give us a more complete picture of pre-GA usage patterns:
| Signal | Why it matters | Suggested mechanism |
|---|---|---|
| `--dry-run` flag used | Understand how many users are "testing" vs actually running commands | Boolean field in `x-elastic-client-meta` |
| `--json` flag used | Understand scripting/automation adoption | Boolean field in `x-elastic-client-meta` |
| `--input-file` flag used | Understand file-based workflow adoption | Boolean field in `x-elastic-client-meta` |
| `--use-context` flag used | Measure multi-context usage | Boolean field in `x-elastic-client-meta` |
| Config resolver type used (`keychain`, `env`, `cmd`, etc.) | Understand credential management patterns | String field in `x-elastic-client-meta` |
| Output format (table vs JSON) | Inform default output decisions | String field |
| Command latency (client-side) | Baseline perf before GA; catch regressions | Add to existing transport timing |
---
## Implementation notes
- The command dot-path is already available inside the `preAction` hook in `src/cli.ts` via `thisCommand._name` chain — it can be assembled at hook time and injected into the transport's `x-elastic-client-meta` before the request fires.
- For non-ES requests (Cloud, Kibana) the header needs to be set on the relevant HTTP clients too (tracked in #273).
- The alias boolean can be set in the `process.argv`-rewrite block in `src/cli.ts` and read by the `preAction` hook.
- Keep the additional metadata compact — `x-elastic-client-meta` is a header on every request.
Contributor guide
Assessment
This issue has not been assessed yet.