Integration Assets Reference

Configuration file

When preparing a new integration, you must include an example configuration that contains the necessary options and reasonable defaults. The example configuration file, which in this case is located at <CHECK_NAME>/datadog_checks/<CHECK_NAME>/data/conf.yaml.example, has two top-level elements: init_config and instances. The configuration under init_config is applied to the integration globally, and is used in every instantiation of the integration, whereas anything within instances is specific to a given instantiation.

Configuration blocks in either section take the following form:

## @<COMMAND> [- <ARGS>]
## <DESCRIPTION LINE 1>
## <DESCRIPTION LINE 2>
#
<KEY>: <VALUE>

Configuration blocks follow a few guidelines:

• Description must not be empty
• Placeholders should always follow this format: <THIS_IS_A_PLACEHOLDER>, as per the documentation contributing guidelines:
• All required parameters are not commented by default.
• All optional parameters are commented by default.
• If a placeholder has a default value for an integration (like the status endpoint of an integration), it can be used instead of a generic placeholder.

@param specification

Practically speaking, the only command is @param, which is used to describe configuration blocks—primarily for documentation purposes. @param is implemented using one of the following forms:

@param <name> - <type> - required
@param <name> - <type> - optional
@param <name> - <type> - optional - default: <defval>

Arguments:

• name: the name of the parameter, such as search_string (mandatory).
• type: the data type for the parameter value (mandatory). Possible values:
  • boolean
  • string
  • integer
  • double
  • float
  • dictionary
  • list*
  • object
• defval: default value for the parameter; can be empty (optional).

list and object variables span over multiple lines and have special rules.

• In a list, individual elements are not documented with the @param specification
• In an object you can choose to either document elements individually with the @param specification or to have a common top-level description following the specification of the object itself.

Optional parameters

An optional parameter must be commented by default. Before every line the parameter spans on, add # with the same indentation as the @param specification.

Block comments

You can add a block comment anywhere in the configuration file with the following rules:

• Comments start with ##
• Comments should be indented like any variable (the hyphen doesn’t count)

For more information about YAML syntax, see Wikipedia. Feel free to play around with the Online YAML Parser, too!

Manifest file

Every integration contains a manifest.json file that describes operating parameters, positioning within the greater Datadog integration eco-system, and other such items.

There are two versions of the manifest.json file. While we will continue supporting manifest version 1 for existing integrations, all new integrations, Datadog Apps, and Marketplace offerings should use version 2 of the manifest.

If you see the following at the top of your manifest.json file, this means you are using version 2:

"manifest_version": "2.0.0"

Otherwise, you can assume that you are using version 1.

These two versions have different attributes and structures. You can find the complete list of mandatory and optional attributes for both versions of the manifest.json file below:

Service check file

The service_check.json file describes the service checks made by the integration.

The service_checks.json file contains the following mandatory attributes:

Metrics metadata file

The metadata.csv file describes all of the metrics that can be collected by the integration.

Descriptions of each column of the metadata.csv file: