locate-config-setting

Locate a Datadog Agent configuration setting or section in the schema source and print its definition plus the exact file and line where it lives. Use this whenever you need to answer "where/how is config key `X` defined?" — its type, default, env vars, description, or which schema file to edit. It is much faster and more reliable than grepping the ~20k lines of schema YAML by hand, because the schema is **split across files** (`core_schema.yaml` plus per-section sub-files referenced via `$ref`), so a naive grep often points at the wrong file. ## Command ```bash dda inv -- schema.locate <setting.path> ``` `<setting.path>` is the **dotted logical path** exactly as a user writes it in `datadog.yaml` / `system-probe.yaml` — e.g. `api_key`, `proxy.https`, `apm_config.enabled`. (Use `--` so invoke treats the path as a positional arg.) It can also be a **pattern**: any argument containing a character outside `[A-Za-z0-9_.]` (e.g. `*`, `$`, `[`) is matched against *every* full dotted path in the schema instead of looked up exactly. The pattern is treated as a regular expression (`re.search`); if it isn't valid regex it falls back to shell-style glob (`fnmatch`). So `'*enabled'` lists every setting whose path ends with `enabled`. Pattern matches are printed as a compact, sorted `[<schema>] <path> -> <file>:<line>` list (one line per match) rather than full node blocks; pass `--json` for the full `{schema, path, file, line, node}` array. ### Flags | Flag | Effect | |---|---| | `--target core` / `--target system-probe` | Restrict to one schema (default: search **both**). | | `--json` | Emit a JSON array of `{schema, path, file, line, node}` instead of human text. Use this when you want to parse the result programmatically. | ## What it prints - **Setting (leaf):** the full schema node — `node_type`, `type`, `default`, `env_vars`, `visibility`, `description`, `tags`. - **Section:** the section's own metadata, with `properties` collapsed to the **sorted list of immediate child key names** (so a big section like `apm_config` doesn't dump thousands of lines). Drill into a child to see its full node. - A clickable location header per match: `[<schema>] <file>:<line>`. - If a key exists in **both** schemas (e.g. `log_level`), it prints one block per schema, labeled `[core]` and `[system-probe]`. ## Location semantics (important) - A **top-level split section** (e.g. `apm_config`, `logs_config`) is reported at its `$ref:` line in `pkg/config/schema/yaml/core_schema.yaml` — that's where it's wired in. - A setting **inside** a split section (e.g. `apm_config.enabled`) is reported in the **sub-file** (`pkg/config/schema/yaml/apm_config.yaml:<line>`) — that's where its real definition is, and the file you'd edit. - A setting/section that lives inline in the top file (e.g. `api_key`, `proxy.https`) is reported directly in `core_schema.yaml`. ## Behavior notes - Reads the YAML **source** under `pkg/config/schema/yaml/` — no build step or agent binary needed; works straight from a checkout. Line numbers are real. - Only traverses named settings and sections (`properties`). Array `items` and `patternProperties` internals are out of scope. - Not found → prints an error and exits non-zero (no fuzzy suggestions). ## Examples ```bash # Top-level setting → core_schema.yaml + full node dda inv -- schema.locate api_key # Setting inside a split section → resolves into the sub-file dda inv -- schema.locate apm_config.enabled # Bare split section → $ref site in core_schema.yaml, child names only dda inv -- schema.locate apm_config # Restrict to one schema and get machine-readable output dda inv -- schema.locate process_config.enabled --target core --json # Pattern (glob): every setting whose full path ends with 'enabled' dda inv -- schema.locate '*enabled' # Pattern (regex): every path containing 'proxy' (a bare word like 'proxy' is an # exact lookup, so add metacharacters to force a pattern/contains-match) dda inv -- schema.locate '.*proxy' ``` ## Related - The task lives in `tasks/schema/locate.py` (registered in `tasks/schema/__init__.py`). - Schema source: `pkg/config/schema/yaml/`. - To **add** a new config field (not just locate one), use the `create-config-field` skill.