Create Config Field

Add a new configuration setting to a Datadog Agent config file by declaring it in the configuration schema.

The schema is the single source of truth for every Agent setting: its type, default, documentation, environment variables, validation rules and visibility all live in one YAML node. Do not add BindEnvAndSetDefault calls by hand — the pkg/config/setup/*_settings.go files are generated from the schema, and so are datadog.yaml.example / system-probe.yaml.example, the JSON Schema published to SchemaStore, and the runtime config validation.

Consult these references only when the instructions below do not provide enough detail for the current task:

• For guidance on adding, documenting, or publishing settings, read the settings how-to.
• For unfamiliar keywords or validation rules, read the keyword reference.
• For complex nested settings or the distinction between sections and object values, read the annotated examples.
• For command arguments, read the CLI reference.
• For schema terminology and design rationale, read the schema overview.

Where settings live

One schema per config file, all under pkg/config/schema/yaml/:

Large top-level sections are split into sibling files referenced via $ref, so the node for apm_config.enabled lives in apm_config.yaml, not in core_schema.yaml.

Never grep for the file by hand — dda inv -- schema.locate resolves the $ref for you (see Step 2).

Instructions

Step 1: Gather information from the user

Use AskUserQuestion to collect the following. If $ARGUMENTS provides the setting path, skip that question.

1. Target schema: datadog.yaml (core) or system-probe.yaml?
2. Setting path (dot-separated, e.g. my_feature.enabled).
3. Type: boolean, string, number, integer, array, or object. For array, also the element type (items.type is mandatory).
4. Default: a single default, or per-platform platform_default.
5. Visibility: public (appears in the generated *.yaml.example and public docs) or undocumented (the default — internal, no keyword emitted).
6. Description: mandatory for public, strongly encouraged otherwise. Written for users, not Agent developers. This should explain what the settings does and how to use it.
7. Description for each ancestor section: if a setting is public, each parent section must be public too with their own description. Ask for a description per section newly made public, separately from the setting's. Never reuse or copy the setting's description into its parent section — a section describes what the group of settings is for, a setting describes its own value.
8. Comment: an optional description aimed at developers.

Step 2: Check the setting does not already exist

dda inv -- schema.locate my_feature.enabled          # exact path
dda inv -- schema.locate '.*my_feature'              # pattern (regex/glob)

This also tells you which file to edit. See the locate-config-setting skill for the full flag set.

Step 3: Add the node to the schema

Preferred — the interactive wizard, which routes split sections to the right sub-file, preserves the file's hand-curated ordering, makes ancestor sections public when needed, and lints at the end:

dda inv schema.add-setting                       # core schema
dda inv schema.add-setting --schema=system-probe # system-probe schema

The wizard is interactive (it reads from stdin), so when you cannot drive a TTY, edit the YAML directly instead. Read a neighbouring node first and match its style:

my_feature:
  node_type: section
  type: object
  visibility: public
  description: Configuration for my feature.
  properties:

    enabled:
      node_type: setting
      type: boolean
      default: false
      description: Enables my feature.
      visibility: public

Rules that the linter enforces:

• Every node needs node_type: section or node_type: setting.
• Every setting and section name must be snake_case (lowercase letters and digits, in words separated by single underscores).
• Every setting needs a type and exactly one of default / platform_default.
• platform_default must cover every platform — list linux, windows, darwin, aix explicitly, or add an other catch-all. container / fargate are optional and fall back to linux then other.
• An array setting must declare items.type.
• A public node needs a non-empty description, and every ancestor section must also be public with a description — its own description, gathered in Step 1, not a copy of the child setting's.
• A section needs at least one child; a public section needs at least one direct public child.
• Set node_type: setting — not section — when the value is an object (e.g. docker_labels_as_tags: type: object, default: {}). A section is only for grouping child settings.

Placement matters: the generated config examples follow schema order, so insert the node where it belongs logically, not at the end of the file.