Every integration has a specification detailing all the options that influence behavior. These YAML files are located at
The producer's job is to read a specification and:
- Validate for correctness
- Populate all unset default fields
- Resolve any defined templates
- Output the complete specification as JSON for arbitrary consumers
Consumers may utilize specs in a number of scenarios, such as:
- rendering example configuration shipped to end users
- documenting all options in-app & on the docs site
- form for creating configuration in multiple formats on Integration tiles
- automatic configuration loading for Checks
- Agent based and/or in-app validator for user-supplied configuration
The root of every spec is a map with 3 keys:
name- The display name of what the spec refers to e.g.
Datadog Agent, etc.
version- The released version of what the spec refers to
files- A list of all files that influence behavior
Every file has 3 possible attributes:
name- This is the name of the file the Agent will look for (REQUIRED)
example_name- This is the name of the example file the Agent will ship. If none is provided, the default will be
conf.yaml.example. The exception is auto-discovery files, which are also named
options- A list of options (REQUIRED)
Every option has 10 possible attributes:
name- This is the name of the option (REQUIRED)
description- Information about the option (REQUIRED)
required- Whether or not the option is required for basic functionality. It defaults to
hidden- Whether or not the option should not be publicly exposed. It defaults to
display_priority- An integer representing the relative visual rank the option should take on compared to other options when publicly exposed. It defaults to
0, meaning that every option will be displayed in the order defined in the spec.
deprecation- If the option is deprecated, a mapping of relevant information. For example:
deprecation: Release: 8.0.0 Migration: | do this and that
multiple- Whether or not options may be selected multiple times like
instancesor just once like
metadata_tags- A list of tags (like
docs:foo) that can serve for unexpected use cases in the future
options- Nested options, indicating that this is a section like
value- The expected type data
There are 2 types of options: those with and without a
value. Those with a
value attribute are the actual user-controlled settings that influence behavior like
username. Those without are expected to be sections and therefore must have an
options attribute. An option cannot have both attributes.
Options with a
value (non-section) also support:
secret- Whether or not consumers should treat the option as sensitive information like
password. It defaults to
The option vs section logic was chosen instead of going fully typed to avoid deeply nested
The type system is based on a loose subset of OpenAPI 3 data types.
The differences are:
- Only the
maximumnumeric modifiers are supported
- Only the
patternstring modifier is supported
propertiesobject modifier is not a map, but rather a list of maps with a required
nameattribute. This is so consumers will load objects consistently regardless of language guarantees regarding map key order.
Values also support 1 field of our own:
example- An example value, only required if the type is
boolean. The default is
Every option may reference pre-defined templates using a key called
template. The template format looks like
path/to must point an existing directory relative to a template directory and
template_file must have the file extension
You can use custom templates that will take precedence over the pre-defined templates by using the
template_paths parameter of the ConfigSpec class.
For occasions when deeply nested default template values need to be overridden, there is the ability to redefine attributes via a . (dot) accessor.
options: - template: instances/http overrides: timeout.value.example: 42
Example file consumer¶
The example consumer uses each spec to render the example configuration files that are shipped with every Agent and individual Integration release.
It respects a few extra option-level attributes:
example- A complete example of an option in lieu of a strictly typed
enabled- Whether or not to un-comment the option, overriding the behavior of
display_priority- This is an integer affecting the order in which options are displayed, with higher values indicating higher priority. The default is
It also respects a few extra fields under the
value attribute of each option:
display_default- This is the default value that will be shown in the header of each option, useful if it differs from the
example. You may set it to
nullexplicitly to disable showing this part of the header.
compact_example- Whether or not to display complex types like arrays in their most compact representation. It defaults to
--sync flag of the config validation command to render the example configuration files.
Data model consumer¶
The model consumer uses each spec to render the pydantic models that checks use to validate and interface with configuration. The models are shipped with every Agent and individual Integration release.
It respects an extra field under the
value attribute of each option:
default- This is the default value that options will be set to, taking precedence over the
validators- This refers to an array of pre-defined field validators to use. Every entry will refer to a relative import path to a field validator under
datadog_checks.base.utils.models.validationand will be executed in the defined order.
--sync flag of the model validation command to render the data model files.
__init__(self, contents, template_paths=None, source=None, version=None)
Source code in
def __init__(self, contents, template_paths=None, source=None, version=None): super().__init__(contents, template_paths, source, version) self.spec_type = 'Configuration' self.templates = ConfigTemplates(template_paths)