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:

AttributeTypeMandatory/OptionalDescription
manifest_versionString EnumMandatoryVersion of the manifest schema. Supported values include 1.0.0 and 2.0.0.
app_idStringMandatoryThe unique identifying name of this offering. Usually kebab case of the app title. For example, if the app title is “Marketplace Offering”, then the app_id would be marketplace-offering.
app_uuidUUIDMandatoryGlobally unique UUID for this application.
assetsDictionaryMandatoryObject containing any Datadog installable entity.
assets[dashboards]DictionaryOptionalOut-of-the-box dashboards associated with this offering.
assets[dashboards["dashboard_short_name"]]StringMandatoryKey/value pairs of any out-of-the-box dashboards. The key is the globally unique short name of the dashboard and the value is the relative path to the dashboard’s JSON definition in relation to this manifest.
assets[integration]DictionaryOptionalObject containing information about the integration.
assets[integration[configuration]]DictionaryMandatory, can be { }Object representing the configuration specification for this integration.
assets[integration[configuration[spec]]]StringMandatoryRelative path to where the configuration spec lives in relation to this manifest.
assets[integration[events]]DictionaryMandatoryInformation about events emitted by this integration.
assets[integration[events[creates_events]]]BooleanMandatoryWhether or not this integration emits events to Datadog.
assets[integration[metrics]]DictionaryMandatoryInformation about the metrics this integration emits.
assets[integration[metrics[check]]]String or List of StringMandatoryA string or list representing metrics that this integration always emits on every run.
assets[integration[metrics[metadata_path]]]StringMandatoryRelative path to where the metrics metadata lives in relation to this manifest.
assets[integration[metrics[prefix]]]StringMandatoryThe prefix for metrics emitted by this integration.
assets[integration[service_checks]]DictionaryMandatory, but can be { }Information about service checks emitted by this integration.
assets[integration[service_checks[metadata_path]]]StringMandatoryRelative path to where the service check metadata lives in relation to this manifest.
assets[integration[source_type_name]]StringMandatoryUser-facing name of this integration.
assets[monitors]DictionaryOptionalRecommended monitors.
assets[monitors["monitor_short_name"]]StringMandatoryKey/value pairs for any recommended monitors. The key is the globally unique short name of the monitor and the value is the relative path to the monitor’s JSON definition in relation to this manifest.
authorDictionaryMandatoryInformation about the author of this app.
author[homepage]String (URL)MandatoryThe web URL to the homepage of the author.
author[name]StringMandatoryThe human-readable name for this company.
author[sales_email]String (Email)MandatoryThe email to contact for any subscription-level events.
author[support_email]String (Email)MandatoryThe email to contact for any support and maintenance queries.
author[vendor_id]StringMandatoryThe vendor ID to use for subscription purposes. Must be globally unique and cannot be changed. Should follow the strict standards of app_id where only dashes and alphabetic chars are allowed. This value is provided to partners.
display_on_public_websiteBooleanMandatoryWhether or not information about this listing is displayed on the public Datadog docs site. Once this is set to True, it cannot be changed.
legal_termsDictionaryMandatoryAny legal documentation that a user needs to agree to in order to use this app.
legal_terms[eula]StringMandatoryRelative path to the EULA (End User License Agreement) PDF in relation to this manifest.
pricingArray of DictionariesMandatoryList of objects representing the pricing model of the integration. See Marketplace GitHub repository for pricing details. The Marketplace GitHub repository is private, email marketplace@datadog.com for access.
tileDictionaryMandatoryInformation about this offering
tile[media]Array of DictionariesMandatory, can be [ ]Information about various image and video style objects that are presented in the media gallery carousel on the listing page.
tile[media[media_type]]String or EnumMandatoryThe type of media this is. Allowed values are image and video.
tile[media[caption]]StringMandatoryThe caption for the image.
tile[media[image_url]]StringMandatoryThe relative path to this image in relation to this manifest file.
tile[classifier_tags]Array of StringMandatory, can be [ ]Some classifier information about this app. This includes information such as supported_os and available_offerings.
tile[description]String[80]MandatoryA brief description of what this offering provides. Limited to 80 characters.
tile[title]String[50]MandatoryThe user-friendly title for this app.
AttributeTypeMandatory/OptionalDescription
integration_idStringMandatoryThe unique identifying name of this integration. Usually kebab case of the Display Name
categoriesArray of StringMandatoryIntegration categories used on the public documentation Integrations page.
creates_eventsBooleanMandatoryIf the integration should be able to create events. If this is set to false, attempting to create an event from the integration results in an error.
display_nameStringMandatoryThe title displayed on the corresponding integration tile on the Datadog site and the Integrations page.
guidStringMandatoryUnique ID for the integration. Generate a UUID
is_publicBooleanMandatoryIf set to false the integration README.md content is not included in the Datadog public documentation.
maintainerStringMandatoryEmail of the owner of the integration.
manifest_versionStringMandatoryVersion of the current manifest.
nameStringMandatoryUnique name for the integration. Use the folder name for this parameter.
public_titleStringMandatoryTitle of the integration displayed on the documentation. Should follow the following format: <INTEGRATION_NAME>.
short_descriptionStringMandatoryThis text appears at the top of the integration tile as well as the integration’s rollover text on the integrations page. Maximum 80 characters.
supportStringMandatoryOwner of the integration.
supported_osArray of StringMandatoryList of supported OSs. Choose among linux,mac_os, and windows.
typeStringMandatoryType of the integration, should be set to check.
aliasesArray of StringOptionalA list of URL aliases for the Datadog documentation.
descriptionStringOptionalThis text appears when sharing an integration documentation link.
is_betaBooleanOptionalDefault false. If set to true the integration README.md content is not displayed in the Datadog public documentation.
metric_to_checkStringOptionalThe presence of this metric determines if this integration is working properly. If this metric is not being reported when this integration is installed, the integration is marked as broken on the Datadog site.
metric_prefixStringOptionalThe namespace for this integration’s metrics. Every metric reported by this integration is prepended with this value.
process_signaturesArray of StringOptionalA list of signatures that matches the command line of this integration.
assetsDictionaryMandatoryRelative location of where certain asset files live and their respective names.
assets-> dashboardsDictionaryMandatoryDictionary where the key is the name of the dashboard (must be globally unique across integrations) and the value is the relative file path where the dashboard definition lives.
assets-> monitorsDictionaryMandatoryDictionary where the key is the name of the monitor (must be globally unique across integrations) and the value is the relative file path where the dashboard definition lives.
assets-> service_checksStringMandatoryRelative location of where the service_checks.json file lives.

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:

AttributeDescription
agent_versionMinimum Agent version supported.
integrationThe name of the integration that emits this service check. Must be the non-normalized display_name from manifest.json.
checkName of the Service Check. It must be unique.
statusesList of different status of the check, to choose among ok, warning, and critical. unknown is also a possibility.
groupsTags sent with the Service Check.
nameDisplayed name of the Service Check. The displayed name must be self-explanatory and unique across all integrations.
descriptionDescription of the Service Check

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:

Column nameMandatory/OptionalDescription
metric_nameMandatoryName of the metric.
metric_typeMandatoryType of the metric.
intervalOptionalCollection interval of the metric in second.
unit_nameOptionalUnit of the metric. Complete list of supported units.
per_unit_nameOptionalIf there is a unit sub-division, i.e request per second
descriptionOptionalDescription of the metric.
orientationMandatorySet to 1 if the metric should go up, i.e myapp.turnover. Set to 0 if the metric variations are irrelevant. Set to -1 if the metric should go down, i.e myapp.latency.
integrationMandatoryThe name of the integration that emits the metric. Must be the normalized version of the display_name from the manifest.json file. Any character besides letters, underscores, dashes, and numbers are converted to underscores, for example: Openstack Controller -> openstack_controllerand ASP.NET -> asp_net and CRI-o -> cri-o.
short_nameMandatoryExplicit Unique ID for the metric.
curated_metricOptionalMarks which metrics for an integration are noteworthy for a given type (cpu and memory are both accepted). These are displayed in the UI above the other integration metrics.